Initial commit

2026-03-30 19:59:31 +08:00
commit c552dabbdd
72 changed files with 4471 additions and 0 deletions
@@ -0,0 +1 @@
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres
@@ -0,0 +1,279 @@
+# AGENTS.md - Server App Guidelines
+
+TanStack Start fullstack web app with ORPC (contract-first RPC).
+
+## Tech Stack
+
+> **⚠️ This project uses Bun — NOT Node.js / npm. All commands use `bun`. Always use `bun run <script>` (not `bun <script>`) to avoid conflicts with Bun built-in subcommands. Never use `npm`, `npx`, or `node`.**
+
+- **Framework**: TanStack Start (React 19 SSR, file-based routing)
+- **Runtime**: Bun — **NOT Node.js**
+- **Package Manager**: Bun — **NOT npm / yarn / pnpm**
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS v4
+- **Database**: PostgreSQL + Drizzle ORM v1 beta (`drizzle-orm/postgres-js`, RQBv2)
+- **State**: TanStack Query v5
+- **RPC**: ORPC (contract-first, type-safe)
+- **Build**: Vite + Nitro
+
+## Commands
+
+```bash
+# Development
+bun run dev                    # Vite dev server (localhost:3000)
+bun run db:studio              # Drizzle Studio GUI
+
+# Build
+bun run build                  # Production build → .output/
+bun run compile                # Compile to standalone binary (current platform, depends on build)
+bun run compile:darwin         # Compile for macOS (arm64 + x64)
+bun run compile:darwin:arm64   # Compile for macOS arm64
+bun run compile:darwin:x64     # Compile for macOS x64
+bun run compile:linux          # Compile for Linux (x64 + arm64)
+bun run compile:linux:arm64    # Compile for Linux arm64
+bun run compile:linux:x64      # Compile for Linux x64
+bun run compile:windows        # Compile for Windows (default: x64)
+bun run compile:windows:x64    # Compile for Windows x64
+
+# Code Quality
+bun run fix                    # Biome auto-fix
+bun run typecheck              # TypeScript check
+
+# Database
+bun run db:generate            # Generate migrations from schema
+bun run db:migrate             # Run migrations
+bun run db:push                # Push schema directly (dev only)
+
+# Testing (not yet configured)
+bun test path/to/test.ts       # Run single test
+bun test -t "pattern"          # Run tests matching pattern
+```
+
+## Directory Structure
+
+```
+src/
+├── client/                # Client-side code
+│   └── orpc.ts            # ORPC client + TanStack Query utils (single entry point)
+├── components/            # React components
+├── routes/                # TanStack Router file routes
+│   ├── __root.tsx         # Root layout
+│   ├── index.tsx          # Home page
+│   └── api/
+│       ├── $.ts           # OpenAPI handler + Scalar docs
+│       ├── health.ts      # Health check endpoint
+│       └── rpc.$.ts       # ORPC RPC handler
+├── server/                # Server-side code
+│   ├── api/               # ORPC layer
+│   │   ├── contracts/     # Input/output schemas (Zod)
+│   │   ├── middlewares/   # Middleware (db provider, auth)
+│   │   ├── routers/       # Handler implementations
+│   │   ├── interceptors.ts # Shared error interceptors
+│   │   ├── context.ts     # Request context
+│   │   ├── server.ts      # ORPC server instance
+│   │   └── types.ts       # Type exports
+│   └── db/
+│       ├── schema/        # Drizzle table definitions
+│       ├── fields.ts      # Shared field builders (id, createdAt, updatedAt)
+│       ├── relations.ts   # Drizzle relations (defineRelations, RQBv2)
+│       └── index.ts       # Database instance (postgres-js driver)
+├── env.ts                 # Environment variable validation
+├── router.tsx             # Router configuration
+├── routeTree.gen.ts       # Auto-generated (DO NOT EDIT)
+└── styles.css             # Tailwind entry
+```
+
+## ORPC Pattern
+
+### 1. Define Contract (`src/server/api/contracts/feature.contract.ts`)
+```typescript
+import { oc } from '@orpc/contract'
+import { createSelectSchema } from 'drizzle-orm/zod'
+import { z } from 'zod'
+import { featureTable } from '@/server/db/schema'
+
+const selectSchema = createSelectSchema(featureTable)
+
+export const list = oc.input(z.void()).output(z.array(selectSchema))
+export const create = oc.input(insertSchema).output(selectSchema)
+```
+
+### 2. Implement Router (`src/server/api/routers/feature.router.ts`)
+```typescript
+import { ORPCError } from '@orpc/server'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+export const list = os.feature.list.use(db).handler(async ({ context }) => {
+  return await context.db.query.featureTable.findMany({
+    orderBy: { createdAt: 'desc' },
+  })
+})
+```
+
+### 3. Register in Index Files
+```typescript
+// src/server/api/contracts/index.ts
+import * as feature from './feature.contract'
+export const contract = { feature }
+
+// src/server/api/routers/index.ts
+import * as feature from './feature.router'
+export const router = os.router({ feature })
+```
+
+### 4. Use in Components
+```typescript
+import { useSuspenseQuery, useMutation } from '@tanstack/react-query'
+import { orpc } from '@/client/orpc'
+
+const { data } = useSuspenseQuery(orpc.feature.list.queryOptions())
+const mutation = useMutation(orpc.feature.create.mutationOptions())
+```
+
+## Database (Drizzle ORM v1 beta)
+
+- **Driver**: `drizzle-orm/postgres-js` (NOT `bun-sql`)
+- **Validation**: `drizzle-orm/zod` (built-in, NOT separate `drizzle-zod` package)
+- **Relations**: Defined via `defineRelations()` in `src/server/db/relations.ts`
+- **Query**: RQBv2 — use `db.query.tableName.findMany()` with object-style `orderBy` and `where`
+
+### Schema Definition
+```typescript
+import { pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core'
+import { sql } from 'drizzle-orm'
+
+export const myTable = pgTable('my_table', {
+  id: uuid().primaryKey().default(sql`uuidv7()`),
+  name: text().notNull(),
+  createdAt: timestamp({ withTimezone: true }).notNull().defaultNow(),
+  updatedAt: timestamp({ withTimezone: true }).notNull().defaultNow().$onUpdateFn(() => new Date()),
+})
+```
+
+### Relations (RQBv2)
+```typescript
+// src/server/db/relations.ts
+import { defineRelations } from 'drizzle-orm'
+import * as schema from './schema'
+
+export const relations = defineRelations(schema, (r) => ({
+  // Define relations here using r.one / r.many / r.through
+}))
+```
+
+### DB Instance
+```typescript
+// src/server/db/index.ts
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { relations } from '@/server/db/relations'
+// In RQBv2, relations already contain schema info — no separate schema import needed
+
+const db = drizzle({
+  connection: env.DATABASE_URL,
+  relations,
+})
+```
+
+### RQBv2 Query Examples
+```typescript
+// Object-style orderBy (NOT callback style)
+const todos = await db.query.todoTable.findMany({
+  orderBy: { createdAt: 'desc' },
+})
+
+// Object-style where
+const todo = await db.query.todoTable.findFirst({
+  where: { id: someId },
+})
+```
+
+## Code Style
+
+### Formatting (Biome)
+- **Indent**: 2 spaces
+- **Quotes**: Single `'`
+- **Semicolons**: Omit (ASI)
+- **Arrow parens**: Always `(x) => x`
+
+### Imports
+Biome auto-organizes:
+1. External packages
+2. Internal `@/*` aliases
+3. Type imports (`import type { ... }`)
+
+```typescript
+import { createFileRoute } from '@tanstack/react-router'
+import { z } from 'zod'
+import { db } from '@/server/db'
+import type { ReactNode } from 'react'
+```
+
+### TypeScript
+- `strict: true`
+- `noUncheckedIndexedAccess: true` - array access returns `T | undefined`
+- Use `@/*` path aliases (maps to `src/*`)
+
+### Naming
+| Type | Convention | Example |
+|------|------------|---------|
+| Files (utils) | kebab-case | `auth-utils.ts` |
+| Files (components) | PascalCase | `UserProfile.tsx` |
+| Components | PascalCase arrow | `const Button = () => {}` |
+| Functions | camelCase | `getUserById` |
+| Types | PascalCase | `UserProfile` |
+
+### React
+- Use arrow functions for components (Biome enforced)
+- Use `useSuspenseQuery` for guaranteed data
+- Let React Compiler handle memoization (no manual `useMemo`/`useCallback`)
+
+## Environment Variables
+
+```typescript
+// src/env.ts - using @t3-oss/env-core
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_API_URL: z.string().optional(),
+  },
+})
+```
+
+## Development Principles
+
+> **These principles apply to ALL code changes. Agents MUST follow them on every task.**
+
+1. **No backward compatibility** — This project is in rapid iteration. Always use the latest API and patterns. Never keep deprecated code paths or old API fallbacks.
+2. **Always sync documentation** — When code changes, immediately update all related documentation (`AGENTS.md`, `README.md`, inline code examples). Code and docs must never drift apart.
+3. **Forward-only migration** — When upgrading dependencies, fully adopt the new API. Don't mix old and new patterns.
+
+## Critical Rules
+
+**DO:**
+- Run `bun run fix` before committing
+- Use `@/*` path aliases
+- Include `createdAt`/`updatedAt` on all tables
+- Use `ORPCError` with proper codes
+- Use `drizzle-orm/zod` (NOT `drizzle-zod`) for schema validation
+- Use RQBv2 object syntax for `orderBy` and `where`
+- Update `AGENTS.md` and other docs whenever code patterns change
+
+**DON'T:**
+- Use `npm`, `npx`, `node`, `yarn`, `pnpm` — always use `bun` / `bunx`
+- Edit `src/routeTree.gen.ts` (auto-generated)
+- Use `as any`, `@ts-ignore`, `@ts-expect-error`
+- Commit `.env` files
+- Use empty catch blocks
+- Import from `drizzle-zod` (use `drizzle-orm/zod` instead)
+- Use RQBv1 callback-style `orderBy` / old `relations()` API
+- Use `drizzle-orm/bun-sql` driver (use `drizzle-orm/postgres-js`)
+- Pass `schema` to `drizzle()` constructor (only `relations` is needed in RQBv2)
+- Import `os` from `@orpc/server` in middleware — use `@/server/api/server` (the local typed instance)
+- Leave docs out of sync with code changes
@@ -0,0 +1,12 @@
+{
+  "$schema": "../../node_modules/@biomejs/biome/configuration_schema.json",
+  "extends": "//",
+  "files": {
+    "includes": ["**", "!**/routeTree.gen.ts"]
+  },
+  "css": {
+    "parser": {
+      "tailwindDirectives": true
+    }
+  }
+}
@@ -0,0 +1,64 @@
+import { mkdir, rm } from 'node:fs/promises'
+import { parseArgs } from 'node:util'
+
+const ENTRYPOINT = '.output/server/index.mjs'
+const OUTDIR = 'out'
+
+const SUPPORTED_TARGETS: readonly Bun.Build.CompileTarget[] = [
+  'bun-windows-x64',
+  'bun-darwin-arm64',
+  'bun-darwin-x64',
+  'bun-linux-x64',
+  'bun-linux-arm64',
+]
+
+const isSupportedTarget = (value: string): value is Bun.Build.CompileTarget =>
+  (SUPPORTED_TARGETS as readonly string[]).includes(value)
+
+const { values } = parseArgs({
+  options: { target: { type: 'string' } },
+  strict: true,
+  allowPositionals: false,
+})
+
+const resolveTarget = (): Bun.Build.CompileTarget => {
+  if (values.target !== undefined) {
+    if (!isSupportedTarget(values.target)) {
+      throw new Error(`Invalid target: ${values.target}\nAllowed: ${SUPPORTED_TARGETS.join(', ')}`)
+    }
+    return values.target
+  }
+
+  const os = process.platform === 'win32' ? 'windows' : process.platform
+  const candidate = `bun-${os}-${process.arch}`
+  if (!isSupportedTarget(candidate)) {
+    throw new Error(`Unsupported host: ${process.platform}-${process.arch}`)
+  }
+  return candidate
+}
+
+const main = async () => {
+  const target = resolveTarget()
+  const suffix = target.replace('bun-', '')
+  const outfile = `server-${suffix}`
+
+  await mkdir(OUTDIR, { recursive: true })
+  await Promise.all([rm(`${OUTDIR}/${outfile}`, { force: true }), rm(`${OUTDIR}/${outfile}.exe`, { force: true })])
+
+  const result = await Bun.build({
+    entrypoints: [ENTRYPOINT],
+    outdir: OUTDIR,
+    compile: { outfile, target },
+  })
+
+  if (!result.success) {
+    throw new Error(result.logs.map(String).join('\n'))
+  }
+
+  console.log(`✓ ${target} → ${OUTDIR}/${outfile}`)
+}
+
+main().catch((err) => {
+  console.error('❌', err instanceof Error ? err.message : err)
+  process.exit(1)
+})
@@ -0,0 +1,11 @@
+import { defineConfig } from 'drizzle-kit'
+import { env } from '@/env'
+
+export default defineConfig({
+  out: './drizzle',
+  schema: './src/server/db/schema/index.ts',
+  dialect: 'postgresql',
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+})
@@ -0,0 +1,59 @@
+{
+  "name": "@furtherverse/server",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bunx --bun vite build",
+    "compile": "bun compile.ts",
+    "compile:darwin": "bun run compile:darwin:arm64 && bun run compile:darwin:x64",
+    "compile:darwin:arm64": "bun compile.ts --target bun-darwin-arm64",
+    "compile:darwin:x64": "bun compile.ts --target bun-darwin-x64",
+    "compile:linux": "bun run compile:linux:x64 && bun run compile:linux:arm64",
+    "compile:linux:arm64": "bun compile.ts --target bun-linux-arm64",
+    "compile:linux:x64": "bun compile.ts --target bun-linux-x64",
+    "compile:windows": "bun run compile:windows:x64",
+    "compile:windows:x64": "bun compile.ts --target bun-windows-x64",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:push": "drizzle-kit push",
+    "db:studio": "drizzle-kit studio",
+    "dev": "bunx --bun vite dev",
+    "fix": "biome check --write",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@orpc/client": "catalog:",
+    "@orpc/contract": "catalog:",
+    "@orpc/openapi": "catalog:",
+    "@orpc/server": "catalog:",
+    "@orpc/tanstack-query": "catalog:",
+    "@orpc/zod": "catalog:",
+    "@t3-oss/env-core": "catalog:",
+    "@tanstack/react-query": "catalog:",
+    "@tanstack/react-router": "catalog:",
+    "@tanstack/react-router-ssr-query": "catalog:",
+    "@tanstack/react-start": "catalog:",
+    "drizzle-orm": "catalog:",
+    "postgres": "catalog:",
+    "react": "catalog:",
+    "react-dom": "catalog:",
+    "uuid": "catalog:",
+    "zod": "catalog:"
+  },
+  "devDependencies": {
+    "@furtherverse/tsconfig": "workspace:*",
+    "@rolldown/plugin-babel": "catalog:",
+    "@tailwindcss/vite": "catalog:",
+    "@tanstack/devtools-vite": "catalog:",
+    "@tanstack/react-devtools": "catalog:",
+    "@tanstack/react-query-devtools": "catalog:",
+    "@tanstack/react-router-devtools": "catalog:",
+    "@types/bun": "catalog:",
+    "@vitejs/plugin-react": "catalog:",
+    "drizzle-kit": "catalog:",
+    "nitro": "catalog:",
+    "tailwindcss": "catalog:",
+    "vite": "catalog:"
+  }
+}
@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow:
@@ -0,0 +1,53 @@
+import { createORPCClient } from '@orpc/client'
+import { RPCLink } from '@orpc/client/fetch'
+import { createRouterClient } from '@orpc/server'
+import { createTanstackQueryUtils } from '@orpc/tanstack-query'
+import { createIsomorphicFn } from '@tanstack/react-start'
+import { getRequestHeaders } from '@tanstack/react-start/server'
+import { router } from '@/server/api/routers'
+import type { RouterClient } from '@/server/api/types'
+
+const getORPCClient = createIsomorphicFn()
+  .server(() =>
+    createRouterClient(router, {
+      context: () => ({
+        headers: getRequestHeaders(),
+      }),
+    }),
+  )
+  .client(() => {
+    const link = new RPCLink({
+      url: `${window.location.origin}/api/rpc`,
+    })
+    return createORPCClient<RouterClient>(link)
+  })
+
+const client: RouterClient = getORPCClient()
+
+export const orpc = createTanstackQueryUtils(client, {
+  experimental_defaults: {
+    todo: {
+      create: {
+        mutationOptions: {
+          onSuccess: (_, __, ___, ctx) => {
+            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
+          },
+        },
+      },
+      update: {
+        mutationOptions: {
+          onSuccess: (_, __, ___, ctx) => {
+            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
+          },
+        },
+      },
+      remove: {
+        mutationOptions: {
+          onSuccess: (_, __, ___, ctx) => {
+            ctx.client.invalidateQueries({ queryKey: orpc.todo.list.key() })
+          },
+        },
+      },
+    },
+  },
+})
@@ -0,0 +1,3 @@
+export function ErrorComponent() {
+  return <div>An unhandled error happened!</div>
+}
@@ -0,0 +1,3 @@
+export function NotFoundComponent() {
+  return <div>404 - Not Found</div>
+}
@@ -0,0 +1,14 @@
+import { createEnv } from '@t3-oss/env-core'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.url(),
+  },
+  clientPrefix: 'VITE_',
+  client: {
+    VITE_APP_TITLE: z.string().min(1).optional(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+})
@@ -0,0 +1,122 @@
+/* eslint-disable */
+
+// @ts-nocheck
+
+// noinspection JSUnusedGlobalSymbols
+
+// This file was automatically generated by TanStack Router.
+// You should NOT make any changes in this file as it will be overwritten.
+// Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
+
+import { Route as rootRouteImport } from './routes/__root'
+import { Route as IndexRouteImport } from './routes/index'
+import { Route as ApiHealthRouteImport } from './routes/api/health'
+import { Route as ApiSplatRouteImport } from './routes/api/$'
+import { Route as ApiRpcSplatRouteImport } from './routes/api/rpc.$'
+
+const IndexRoute = IndexRouteImport.update({
+  id: '/',
+  path: '/',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiHealthRoute = ApiHealthRouteImport.update({
+  id: '/api/health',
+  path: '/api/health',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiSplatRoute = ApiSplatRouteImport.update({
+  id: '/api/$',
+  path: '/api/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+const ApiRpcSplatRoute = ApiRpcSplatRouteImport.update({
+  id: '/api/rpc/$',
+  path: '/api/rpc/$',
+  getParentRoute: () => rootRouteImport,
+} as any)
+
+export interface FileRoutesByFullPath {
+  '/': typeof IndexRoute
+  '/api/$': typeof ApiSplatRoute
+  '/api/health': typeof ApiHealthRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRoutesByTo {
+  '/': typeof IndexRoute
+  '/api/$': typeof ApiSplatRoute
+  '/api/health': typeof ApiHealthRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRoutesById {
+  __root__: typeof rootRouteImport
+  '/': typeof IndexRoute
+  '/api/$': typeof ApiSplatRoute
+  '/api/health': typeof ApiHealthRoute
+  '/api/rpc/$': typeof ApiRpcSplatRoute
+}
+export interface FileRouteTypes {
+  fileRoutesByFullPath: FileRoutesByFullPath
+  fullPaths: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  fileRoutesByTo: FileRoutesByTo
+  to: '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  id: '__root__' | '/' | '/api/$' | '/api/health' | '/api/rpc/$'
+  fileRoutesById: FileRoutesById
+}
+export interface RootRouteChildren {
+  IndexRoute: typeof IndexRoute
+  ApiSplatRoute: typeof ApiSplatRoute
+  ApiHealthRoute: typeof ApiHealthRoute
+  ApiRpcSplatRoute: typeof ApiRpcSplatRoute
+}
+
+declare module '@tanstack/react-router' {
+  interface FileRoutesByPath {
+    '/': {
+      id: '/'
+      path: '/'
+      fullPath: '/'
+      preLoaderRoute: typeof IndexRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/health': {
+      id: '/api/health'
+      path: '/api/health'
+      fullPath: '/api/health'
+      preLoaderRoute: typeof ApiHealthRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/$': {
+      id: '/api/$'
+      path: '/api/$'
+      fullPath: '/api/$'
+      preLoaderRoute: typeof ApiSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+    '/api/rpc/$': {
+      id: '/api/rpc/$'
+      path: '/api/rpc/$'
+      fullPath: '/api/rpc/$'
+      preLoaderRoute: typeof ApiRpcSplatRouteImport
+      parentRoute: typeof rootRouteImport
+    }
+  }
+}
+
+const rootRouteChildren: RootRouteChildren = {
+  IndexRoute: IndexRoute,
+  ApiSplatRoute: ApiSplatRoute,
+  ApiHealthRoute: ApiHealthRoute,
+  ApiRpcSplatRoute: ApiRpcSplatRoute,
+}
+export const routeTree = rootRouteImport
+  ._addFileChildren(rootRouteChildren)
+  ._addFileTypes<FileRouteTypes>()
+
+import type { getRouter } from './router.tsx'
+import type { createStart } from '@tanstack/react-start'
+declare module '@tanstack/react-start' {
+  interface Register {
+    ssr: true
+    router: Awaited<ReturnType<typeof getRouter>>
+  }
+}
@@ -0,0 +1,33 @@
+import { QueryClient } from '@tanstack/react-query'
+import { createRouter } from '@tanstack/react-router'
+import { setupRouterSsrQueryIntegration } from '@tanstack/react-router-ssr-query'
+import type { RouterContext } from './routes/__root'
+import { routeTree } from './routeTree.gen'
+
+export const getRouter = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 30 * 1000,
+        retry: 1,
+      },
+    },
+  })
+
+  const router = createRouter({
+    routeTree,
+    context: {
+      queryClient,
+    } satisfies RouterContext,
+
+    scrollRestoration: true,
+    defaultPreloadStaleTime: 0,
+  })
+
+  setupRouterSsrQueryIntegration({
+    router,
+    queryClient,
+  })
+
+  return router
+}
@@ -0,0 +1,70 @@
+import { TanStackDevtools } from '@tanstack/react-devtools'
+import type { QueryClient } from '@tanstack/react-query'
+import { ReactQueryDevtoolsPanel } from '@tanstack/react-query-devtools'
+import { createRootRouteWithContext, HeadContent, Scripts } from '@tanstack/react-router'
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
+import type { ReactNode } from 'react'
+import { ErrorComponent } from '@/components/Error'
+import { NotFoundComponent } from '@/components/NotFound'
+import appCss from '@/styles.css?url'
+
+export interface RouterContext {
+  queryClient: QueryClient
+}
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: () => ({
+    meta: [
+      {
+        charSet: 'utf-8',
+      },
+      {
+        name: 'viewport',
+        content: 'width=device-width, initial-scale=1',
+      },
+      {
+        title: 'Furtherverse',
+      },
+    ],
+    links: [
+      {
+        rel: 'stylesheet',
+        href: appCss,
+      },
+    ],
+  }),
+  shellComponent: RootDocument,
+  errorComponent: () => <ErrorComponent />,
+  notFoundComponent: () => <NotFoundComponent />,
+})
+
+function RootDocument({ children }: Readonly<{ children: ReactNode }>) {
+  return (
+    <html lang="zh-Hans">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        {import.meta.env.DEV && (
+          <TanStackDevtools
+            config={{
+              position: 'bottom-right',
+            }}
+            plugins={[
+              {
+                name: 'TanStack Router',
+                render: <TanStackRouterDevtoolsPanel />,
+              },
+              {
+                name: 'TanStack Query',
+                render: <ReactQueryDevtoolsPanel />,
+              },
+            ]}
+          />
+        )}
+        <Scripts />
+      </body>
+    </html>
+  )
+}
@@ -0,0 +1,44 @@
+import { OpenAPIHandler } from '@orpc/openapi/fetch'
+import { OpenAPIReferencePlugin } from '@orpc/openapi/plugins'
+import { onError } from '@orpc/server'
+import { ZodToJsonSchemaConverter } from '@orpc/zod/zod4'
+import { createFileRoute } from '@tanstack/react-router'
+import { name, version } from '@/../package.json'
+import { handleValidationError, logError } from '@/server/api/interceptors'
+import { router } from '@/server/api/routers'
+
+const handler = new OpenAPIHandler(router, {
+  plugins: [
+    new OpenAPIReferencePlugin({
+      docsProvider: 'scalar',
+      schemaConverters: [new ZodToJsonSchemaConverter()],
+      specGenerateOptions: {
+        info: {
+          title: name,
+          version,
+        },
+      },
+      docsPath: '/docs',
+      specPath: '/spec.json',
+    }),
+  ],
+  interceptors: [onError(logError)],
+  clientInterceptors: [onError(handleValidationError)],
+})
+
+export const Route = createFileRoute('/api/$')({
+  server: {
+    handlers: {
+      ANY: async ({ request }) => {
+        const { response } = await handler.handle(request, {
+          prefix: '/api',
+          context: {
+            headers: request.headers,
+          },
+        })
+
+        return response ?? new Response('Not Found', { status: 404 })
+      },
+    },
+  },
+})
@@ -0,0 +1,27 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { name, version } from '@/../package.json'
+
+const createHealthResponse = (): Response =>
+  Response.json(
+    {
+      status: 'ok',
+      service: name,
+      version,
+      timestamp: new Date().toISOString(),
+    },
+    {
+      status: 200,
+      headers: {
+        'cache-control': 'no-store',
+      },
+    },
+  )
+
+export const Route = createFileRoute('/api/health')({
+  server: {
+    handlers: {
+      GET: async () => createHealthResponse(),
+      HEAD: async () => new Response(null, { status: 200 }),
+    },
+  },
+})
@@ -0,0 +1,27 @@
+import { onError } from '@orpc/server'
+import { RPCHandler } from '@orpc/server/fetch'
+import { createFileRoute } from '@tanstack/react-router'
+import { handleValidationError, logError } from '@/server/api/interceptors'
+import { router } from '@/server/api/routers'
+
+const handler = new RPCHandler(router, {
+  interceptors: [onError(logError)],
+  clientInterceptors: [onError(handleValidationError)],
+})
+
+export const Route = createFileRoute('/api/rpc/$')({
+  server: {
+    handlers: {
+      ANY: async ({ request }) => {
+        const { response } = await handler.handle(request, {
+          prefix: '/api/rpc',
+          context: {
+            headers: request.headers,
+          },
+        })
+
+        return response ?? new Response('Not Found', { status: 404 })
+      },
+    },
+  },
+})
@@ -0,0 +1,193 @@
+import { useMutation, useSuspenseQuery } from '@tanstack/react-query'
+import { createFileRoute } from '@tanstack/react-router'
+import type { ChangeEventHandler, SubmitEventHandler } from 'react'
+import { useState } from 'react'
+import { orpc } from '@/client/orpc'
+
+export const Route = createFileRoute('/')({
+  component: Todos,
+  loader: async ({ context }) => {
+    await context.queryClient.ensureQueryData(orpc.todo.list.queryOptions())
+  },
+})
+
+function Todos() {
+  const [newTodoTitle, setNewTodoTitle] = useState('')
+
+  const listQuery = useSuspenseQuery(orpc.todo.list.queryOptions())
+  const createMutation = useMutation(orpc.todo.create.mutationOptions())
+  const updateMutation = useMutation(orpc.todo.update.mutationOptions())
+  const deleteMutation = useMutation(orpc.todo.remove.mutationOptions())
+
+  const handleCreateTodo: SubmitEventHandler<HTMLFormElement> = (e) => {
+    e.preventDefault()
+    if (newTodoTitle.trim()) {
+      createMutation.mutate({ title: newTodoTitle.trim() })
+      setNewTodoTitle('')
+    }
+  }
+
+  const handleInputChange: ChangeEventHandler<HTMLInputElement> = (e) => {
+    setNewTodoTitle(e.target.value)
+  }
+
+  const handleToggleTodo = (id: string, currentCompleted: boolean) => {
+    updateMutation.mutate({
+      id,
+      data: { completed: !currentCompleted },
+    })
+  }
+
+  const handleDeleteTodo = (id: string) => {
+    deleteMutation.mutate({ id })
+  }
+
+  const todos = listQuery.data
+  const completedCount = todos.filter((todo) => todo.completed).length
+  const totalCount = todos.length
+  const progress = totalCount > 0 ? (completedCount / totalCount) * 100 : 0
+
+  return (
+    <div className="min-h-screen bg-slate-50 py-12 px-4 sm:px-6 font-sans">
+      <div className="max-w-2xl mx-auto space-y-8">
+        {/* Header */}
+        <div className="flex items-end justify-between">
+          <div>
+            <h1 className="text-3xl font-bold text-slate-900 tracking-tight">我的待办</h1>
+            <p className="text-slate-500 mt-1">保持专注，逐个击破</p>
+          </div>
+          <div className="text-right">
+            <div className="text-2xl font-semibold text-slate-900">
+              {completedCount}
+              <span className="text-slate-400 text-lg">/{totalCount}</span>
+            </div>
+            <div className="text-xs font-medium text-slate-400 uppercase tracking-wider">已完成</div>
+          </div>
+        </div>
+
+        {/* Add Todo Form */}
+        <form onSubmit={handleCreateTodo} className="relative group z-10">
+          <div className="relative transform transition-all duration-200 focus-within:-translate-y-1">
+            <input
+              type="text"
+              value={newTodoTitle}
+              onChange={handleInputChange}
+              placeholder="添加新任务..."
+              className="w-full pl-6 pr-32 py-5 bg-white rounded-2xl shadow-[0_8px_30px_rgb(0,0,0,0.04)] border-0 ring-1 ring-slate-100 focus:ring-2 focus:ring-indigo-500/50 outline-none transition-all placeholder:text-slate-400 text-lg text-slate-700"
+              disabled={createMutation.isPending}
+            />
+            <button
+              type="submit"
+              disabled={createMutation.isPending || !newTodoTitle.trim()}
+              className="absolute right-3 top-3 bottom-3 px-6 bg-indigo-600 hover:bg-indigo-700 text-white rounded-xl font-medium transition-all shadow-md shadow-indigo-200 disabled:opacity-50 disabled:shadow-none hover:shadow-lg hover:shadow-indigo-300 active:scale-95"
+            >
+              {createMutation.isPending ? '添加中' : '添加'}
+            </button>
+          </div>
+        </form>
+
+        {/* Progress Bar (Only visible when there are tasks) */}
+        {totalCount > 0 && (
+          <div className="h-1.5 w-full bg-slate-200 rounded-full overflow-hidden">
+            <div
+              className="h-full bg-indigo-500 transition-all duration-500 ease-out rounded-full"
+              style={{ width: `${progress}%` }}
+            />
+          </div>
+        )}
+
+        {/* Todo List */}
+        <div className="space-y-3">
+          {todos.length === 0 ? (
+            <div className="py-20 text-center">
+              <div className="inline-flex items-center justify-center w-16 h-16 rounded-full bg-slate-100 mb-4">
+                <svg
+                  className="w-8 h-8 text-slate-400"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  stroke="currentColor"
+                  aria-hidden="true"
+                >
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v6m0 0v6m0-6h6m-6 0H6" />
+                </svg>
+              </div>
+              <p className="text-slate-500 text-lg font-medium">没有待办事项</p>
+              <p className="text-slate-400 text-sm mt-1">输入上方内容添加您的第一个任务</p>
+            </div>
+          ) : (
+            todos.map((todo) => (
+              <div
+                key={todo.id}
+                className={`group relative flex items-center p-4 bg-white rounded-xl border border-slate-100 shadow-sm transition-all duration-200 hover:shadow-md hover:border-slate-200 ${
+                  todo.completed ? 'bg-slate-50/50' : ''
+                }`}
+              >
+                <button
+                  type="button"
+                  onClick={() => handleToggleTodo(todo.id, todo.completed)}
+                  className={`flex-shrink-0 w-6 h-6 rounded-full border-2 transition-all duration-200 flex items-center justify-center mr-4 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 ${
+                    todo.completed
+                      ? 'bg-indigo-500 border-indigo-500'
+                      : 'border-slate-300 hover:border-indigo-500 bg-white'
+                  }`}
+                >
+                  {todo.completed && (
+                    <svg
+                      className="w-3.5 h-3.5 text-white"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={3}
+                      aria-hidden="true"
+                    >
+                      <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
+                    </svg>
+                  )}
+                </button>
+
+                <div className="flex-1 min-w-0">
+                  <p
+                    className={`text-lg transition-all duration-200 truncate ${
+                      todo.completed
+                        ? 'text-slate-400 line-through decoration-slate-300 decoration-2'
+                        : 'text-slate-700'
+                    }`}
+                  >
+                    {todo.title}
+                  </p>
+                </div>
+
+                <div className="flex items-center opacity-0 group-hover:opacity-100 transition-opacity duration-200 absolute right-4 pl-4 bg-gradient-to-l from-white via-white to-transparent sm:static sm:bg-none">
+                  <span className="text-xs text-slate-400 mr-3 hidden sm:inline-block">
+                    {new Date(todo.createdAt).toLocaleDateString('zh-CN')}
+                  </span>
+                  <button
+                    type="button"
+                    onClick={() => handleDeleteTodo(todo.id)}
+                    className="p-2 text-slate-400 hover:text-red-500 hover:bg-red-50 rounded-lg transition-colors focus:outline-none"
+                    title="删除"
+                  >
+                    <svg
+                      className="w-5 h-5"
+                      fill="none"
+                      viewBox="0 0 24 24"
+                      stroke="currentColor"
+                      strokeWidth={1.5}
+                      aria-hidden="true"
+                    >
+                      <path
+                        strokeLinecap="round"
+                        strokeLinejoin="round"
+                        d="M19 7l-.867 12.142A2 2 0 0116.138 21H7.862a2 2 0 01-1.995-1.858L5 7m5 4v6m4-6v6m1-10V4a1 1 0 00-1-1h-4a1 1 0 00-1 1v3M4 7h16"
+                      />
+                    </svg>
+                  </button>
+                </div>
+              </div>
+            ))
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
@@ -0,0 +1,25 @@
+import type { DB } from '@/server/db'
+
+/**
+ * 基础 Context - 所有请求都包含的上下文
+ */
+export interface BaseContext {
+  headers: Headers
+}
+
+/**
+ * 数据库 Context - 通过 db middleware 扩展
+ */
+export interface DBContext extends BaseContext {
+  db: DB
+}
+
+/**
+ * 认证 Context - 通过 auth middleware 扩展（未来使用）
+ *
+ * @example
+ * export interface AuthContext extends DBContext {
+ *   userId: string
+ *   user: User
+ * }
+ */
@@ -0,0 +1,7 @@
+import * as todo from './todo.contract'
+
+export const contract = {
+  todo,
+}
+
+export type Contract = typeof contract
@@ -0,0 +1,32 @@
+import { oc } from '@orpc/contract'
+import { createInsertSchema, createSelectSchema, createUpdateSchema } from 'drizzle-orm/zod'
+import { z } from 'zod'
+import { generatedFieldKeys } from '@/server/db/fields'
+import { todoTable } from '@/server/db/schema'
+
+const selectSchema = createSelectSchema(todoTable)
+
+const insertSchema = createInsertSchema(todoTable).omit(generatedFieldKeys)
+
+const updateSchema = createUpdateSchema(todoTable).omit(generatedFieldKeys)
+
+export const list = oc.input(z.void()).output(z.array(selectSchema))
+
+export const create = oc.input(insertSchema).output(selectSchema)
+
+export const update = oc
+  .input(
+    z.object({
+      id: z.uuid(),
+      data: updateSchema,
+    }),
+  )
+  .output(selectSchema)
+
+export const remove = oc
+  .input(
+    z.object({
+      id: z.uuid(),
+    }),
+  )
+  .output(z.void())
@@ -0,0 +1,26 @@
+import { ORPCError, ValidationError } from '@orpc/server'
+import { z } from 'zod'
+
+export const logError = (error: unknown) => {
+  console.error(error)
+}
+
+export const handleValidationError = (error: unknown) => {
+  if (error instanceof ORPCError && error.code === 'BAD_REQUEST' && error.cause instanceof ValidationError) {
+    // If you only use Zod you can safely cast to ZodIssue[] (per ORPC official docs)
+    const zodError = new z.ZodError(error.cause.issues as z.core.$ZodIssue[])
+
+    throw new ORPCError('INPUT_VALIDATION_FAILED', {
+      status: 422,
+      message: z.prettifyError(zodError),
+      data: z.flattenError(zodError),
+      cause: error.cause,
+    })
+  }
+
+  if (error instanceof ORPCError && error.code === 'INTERNAL_SERVER_ERROR' && error.cause instanceof ValidationError) {
+    throw new ORPCError('OUTPUT_VALIDATION_FAILED', {
+      cause: error.cause,
+    })
+  }
+}
@@ -0,0 +1,11 @@
+import { os } from '@/server/api/server'
+import { getDB } from '@/server/db'
+
+export const db = os.middleware(async ({ context, next }) => {
+  return next({
+    context: {
+      ...context,
+      db: getDB(),
+    },
+  })
+})
@@ -0,0 +1 @@
+export * from './db.middleware'
@@ -0,0 +1,6 @@
+import { os } from '../server'
+import * as todo from './todo.router'
+
+export const router = os.router({
+  todo,
+})
@@ -0,0 +1,40 @@
+import { ORPCError } from '@orpc/server'
+import { eq } from 'drizzle-orm'
+import { todoTable } from '@/server/db/schema'
+import { db } from '../middlewares'
+import { os } from '../server'
+
+export const list = os.todo.list.use(db).handler(async ({ context }) => {
+  const todos = await context.db.query.todoTable.findMany({
+    orderBy: { createdAt: 'desc' },
+  })
+  return todos
+})
+
+export const create = os.todo.create.use(db).handler(async ({ context, input }) => {
+  const [newTodo] = await context.db.insert(todoTable).values(input).returning()
+
+  if (!newTodo) {
+    throw new ORPCError('INTERNAL_SERVER_ERROR', { message: 'Failed to create todo' })
+  }
+
+  return newTodo
+})
+
+export const update = os.todo.update.use(db).handler(async ({ context, input }) => {
+  const [updatedTodo] = await context.db.update(todoTable).set(input.data).where(eq(todoTable.id, input.id)).returning()
+
+  if (!updatedTodo) {
+    throw new ORPCError('NOT_FOUND')
+  }
+
+  return updatedTodo
+})
+
+export const remove = os.todo.remove.use(db).handler(async ({ context, input }) => {
+  const [deleted] = await context.db.delete(todoTable).where(eq(todoTable.id, input.id)).returning({ id: todoTable.id })
+
+  if (!deleted) {
+    throw new ORPCError('NOT_FOUND')
+  }
+})
@@ -0,0 +1,5 @@
+import { implement } from '@orpc/server'
+import type { BaseContext } from './context'
+import { contract } from './contracts'
+
+export const os = implement(contract).$context<BaseContext>()
@@ -0,0 +1,6 @@
+import type { ContractRouterClient, InferContractRouterInputs, InferContractRouterOutputs } from '@orpc/contract'
+import type { Contract } from './contracts'
+
+export type RouterClient = ContractRouterClient<Contract>
+export type RouterInputs = InferContractRouterInputs<Contract>
+export type RouterOutputs = InferContractRouterOutputs<Contract>
@@ -0,0 +1,55 @@
+import { sql } from 'drizzle-orm'
+import { timestamp, uuid } from 'drizzle-orm/pg-core'
+import { v7 as uuidv7 } from 'uuid'
+
+// id
+
+const id = (name: string) => uuid(name)
+export const pk = (name: string, strategy?: 'native' | 'extension') => {
+  switch (strategy) {
+    // PG 18+
+    case 'native':
+      return id(name).primaryKey().default(sql`uuidv7()`)
+
+    // PG 13+ with extension
+    case 'extension':
+      return id(name).primaryKey().default(sql`uuid_generate_v7()`)
+
+    // Any PG version
+    default:
+      return id(name)
+        .primaryKey()
+        .$defaultFn(() => uuidv7())
+  }
+}
+
+// timestamp
+
+export const createdAt = (name = 'created_at') => timestamp(name, { withTimezone: true }).notNull().defaultNow()
+
+export const updatedAt = (name = 'updated_at') =>
+  timestamp(name, { withTimezone: true })
+    .notNull()
+    .defaultNow()
+    .$onUpdateFn(() => new Date())
+
+// generated fields
+
+export const generatedFields = {
+  id: pk('id'),
+  createdAt: createdAt('created_at'),
+  updatedAt: updatedAt('updated_at'),
+}
+
+// Helper to create omit keys from generatedFields
+const createGeneratedFieldKeys = <T extends Record<string, unknown>>(fields: T): Record<keyof T, true> => {
+  return Object.keys(fields).reduce(
+    (acc, key) => {
+      acc[key as keyof T] = true
+      return acc
+    },
+    {} as Record<keyof T, true>,
+  )
+}
+
+export const generatedFieldKeys = createGeneratedFieldKeys(generatedFields)
@@ -0,0 +1,24 @@
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { env } from '@/env'
+import { relations } from '@/server/db/relations'
+
+export const createDB = () =>
+  drizzle({
+    connection: env.DATABASE_URL,
+    relations,
+  })
+
+export type DB = ReturnType<typeof createDB>
+
+export const getDB = (() => {
+  let db: DB | null = null
+
+  return (singleton = true): DB => {
+    if (!singleton) {
+      return createDB()
+    }
+
+    db ??= createDB()
+    return db
+  }
+})()
@@ -0,0 +1,4 @@
+import { defineRelations } from 'drizzle-orm'
+import * as schema from './schema'
+
+export const relations = defineRelations(schema, (_r) => ({}))
@@ -0,0 +1 @@
+export * from './todo'
@@ -0,0 +1,8 @@
+import { boolean, pgTable, text } from 'drizzle-orm/pg-core'
+import { generatedFields } from '../fields'
+
+export const todoTable = pgTable('todo', {
+  ...generatedFields,
+  title: text('title').notNull(),
+  completed: boolean('completed').notNull().default(false),
+})
@@ -0,0 +1 @@
+@import "tailwindcss";
@@ -0,0 +1,8 @@
+{
+  "extends": "@furtherverse/tsconfig/react.json",
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
@@ -0,0 +1,47 @@
+{
+  "$schema": "../../node_modules/turbo/schema.json",
+  "extends": ["//"],
+  "tasks": {
+    "build": {
+      "env": ["NODE_ENV", "VITE_*"],
+      "inputs": ["src/**", "public/**", "package.json", "tsconfig.json", "vite.config.ts"],
+      "outputs": [".output/**"]
+    },
+    "compile": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:darwin": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:darwin:arm64": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:darwin:x64": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:linux": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:linux:arm64": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:linux:x64": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:windows": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    },
+    "compile:windows:x64": {
+      "dependsOn": ["build"],
+      "outputs": ["out/**"]
+    }
+  }
+}
@@ -0,0 +1,31 @@
+import babel from '@rolldown/plugin-babel'
+import tailwindcss from '@tailwindcss/vite'
+import { devtools as tanstackDevtools } from '@tanstack/devtools-vite'
+import { tanstackStart } from '@tanstack/react-start/plugin/vite'
+import react, { reactCompilerPreset } from '@vitejs/plugin-react'
+import { nitro } from 'nitro/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  clearScreen: false,
+  plugins: [
+    tanstackDevtools(),
+    tailwindcss(),
+    tanstackStart(),
+    react(),
+    babel({
+      presets: [reactCompilerPreset()],
+    }),
+    nitro({
+      preset: 'bun',
+      serveStatic: 'inline',
+    }),
+  ],
+  resolve: {
+    tsconfigPaths: true,
+  },
+  server: {
+    port: 3000,
+    strictPort: true,
+  },
+})
				`@@ -0,0 +1 @@`
				`DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres`