Project Structure

Raypx is organized as a pnpm workspace monorepo. The root contains the TanStack Start application, and 11 internal packages live under packages/.

Directory Layout

Application Source (src/)

src/routes/

TanStack Start uses file-based routing. Each file in this directory maps to a URL path. Parenthesized directories like (auth) and (dashboard) are layout groups — they contribute a layout component but do not appear in the URL.

• __root.tsx — the root layout that wraps every page. Contains providers, the head element, and the document shell.
• api/ — API route handlers. auth/$.ts handles Better Auth endpoints, rpc/$.ts handles oRPC calls, and health.ts provides a health check.
• (home)/index.tsx — the landing page.
• (auth)/ — sign-in, sign-up, and password reset pages.
• (dashboard)/ — authenticated dashboard routes.

src/middleware/

Request-level middleware that runs before route handlers:

• security.ts — sets security headers (CSP, HSTS, X-Frame-Options, etc.) on every response.
• auth.ts — authentication session middleware for protected routes.

src/lib/

Server-side modules that provide core services:

• auth.server.ts — initializes the Better Auth server instance with plugins and database adapter.
• db.server.ts — creates the Drizzle ORM database client.
• rate-limit.ts — in-memory rate limiter for API endpoints.
• storage.server.ts — file storage abstraction supporting local disk and S3 backends.

src/utils/orpc.ts

The oRPC client setup. This file creates an isomorphic client that calls router procedures directly on the server (bypassing HTTP) and falls back to fetch-based calls on the client:

const getORPCClient = createIsomorphicFn()
  .server(() =>
    createRouterClient(appRouter, {
      context: async () => createContext({ req: getRequest() }),
    }),
  )
  .client((): RouterClient<typeof appRouter> => {
    const link = new RPCLink({
      url: `${window.location.origin}/api/rpc`,
      fetch(url, options) {
        return fetch(url, { ...options, credentials: "include" })
      },
    })
    return createORPCClient(link)
  })

src/components/

Reusable React components organized by feature. Shared components like providers.tsx, theme-toggle.tsx, and logo.tsx live at the top level. Feature-specific components are in subdirectories.

src/start.ts

The application entry point. Defines the middleware chain that runs on every request:

export const startInstance = createStart(() => {
  return {
    requestMiddleware: [securityMiddleware, i18nMiddleware, llmMiddleware],
  }
})

Packages (packages/)

Each package follows the @raypx/{name} naming convention and is listed as a workspace dependency. See Internal Packages for detailed documentation.

Configuration Files

Content (content/docs/)

Fumadocs MDX content for the documentation site. Organized by locale (en-US/, zh-CN/) with a mirrored directory structure.

Next Steps

• Architecture Overview — understand the system design.
• Internal Packages — explore each package.