Reactive-Resume/.planning/codebase/STACK.md

# Technology Stack

**Analysis Date:** 2026-05-11

## Languages

**Primary:**
- TypeScript `^6.0.3` — All workspace code under `apps/web/src` and `packages/*/src`. Typechecked with the experimental TS native compiler `@typescript/native-preview` (`7.0.0-dev.20260510.1`) via `tsgo --noEmit`.
- TSX (React 19) — UI components in `apps/web/src`, `packages/ui/src/components`, `packages/pdf/src/templates`, and email templates in `packages/email/src/templates`.

**Secondary:**
- JavaScript (ESM, `"type": "module"`) — A handful of config files such as `commitlint.config.cjs` and `apps/web/postcss.config` style snippets.
- JSON / JSONC — `package.json`, `tsconfig.json`, `biome.json`, `turbo.json`, `knip.json`, `apps/web/components.json`, `packages/schema/schema.json`, locale and webfont metadata.
- SQL — Drizzle-generated migrations under `migrations/` (e.g. `migrations/20260507144406_fast_nova/`).
- YAML — `compose.yml`, `compose.dev.yml`, `lefthook.yml`, `crowdin.yml`, `pnpm-workspace.yaml`.
- Markdown — `AGENTS.md`, `README.md`, `SECURITY.md`, `LICENSE`, docs under `docs/`.

## Runtime

**Environment:**
- Node.js `24` — Pinned in `Dockerfile` via `ARG NODE_VERSION=24`. Single Node process exposes the web app on port `3000`.
- Browser runtime — React 19 SSR + hydration via TanStack Start. PWA service worker registered from `apps/web/vite.config.ts`.

**Package Manager:**
- pnpm `11.0.9` — Pinned in `package.json` `packageManager` field (with integrity hash). Managed via Corepack (`corepack enable`) per `AGENTS.md`.
- Workspace topology: `pnpm-workspace.yaml` includes `apps/*` and `packages/*`.
- Lockfile: `pnpm-lock.yaml` is present and committed at repo root.
- `allowBuilds` in `pnpm-workspace.yaml`: `bcrypt`, `esbuild`, `lefthook`, `msw`, `sharp`.
- `postcss` is pinned by an override to `^8.5.14` in `pnpm-workspace.yaml`.

**Build Orchestrator:**
- Turborepo `^2.9.12` — `turbo.json` defines tasks (`build`, `dev`, `typecheck`, `test`, `db:generate`, `db:migrate`, `db:studio`, `lingui:extract`) and the `globalEnv` whitelist for cache invalidation.
- The Docker build also pins `turbo@2.9.9` via `pnpm dlx` for the pruner stages.

## Frameworks

**Core (apps/web):**
- React `^19.2.6` with `react-dom ^19.2.6` (from `apps/web/package.json`).
- TanStack Start `^1.167.65` — Full-stack framework wiring Vite, Nitro, and React Router. Server handlers live in route files under `apps/web/src/routes`.
- TanStack Router `^1.169.2` — File-based router. `apps/web/src/routeTree.gen.ts` is generated.
- TanStack React Query `^5.100.9` with SSR bridge `@tanstack/react-router-ssr-query ^1.166.12`.
- TanStack React Form `^1.32.0` and React Hotkeys `^0.10.0`.
- Vite `^8.0.11` (rolldown-based) — `apps/web/vite.config.ts` orchestrates plugins.
- Nitro `3.0.260429-beta` — Server framework used through `nitro/vite`. Plugins at `apps/web/plugins/1.migrate.ts` and `apps/web/plugins/2.storage.ts` run on Nitro startup.
- `srvx ^0.11.15` — HTTP server runtime used by Nitro/TanStack Start.

**RPC / API:**
- oRPC `^1.14.2` family — `@orpc/server`, `@orpc/client`, `@orpc/openapi`, `@orpc/json-schema`, `@orpc/zod`, `@orpc/tanstack-query`, `@orpc/experimental-ratelimit`.
- `@modelcontextprotocol/sdk ^1.29.0` — MCP server exposed at `/mcp` via `apps/web/src/routes/mcp/index.ts`.

**Auth:**
- Better Auth `1.6.10` — Core auth framework configured in `packages/auth/src/config.ts`.
- Better Auth plugins: `@better-auth/api-key ^1.6.10`, `@better-auth/drizzle-adapter ^1.6.10`, `@better-auth/infra ^0.2.6` (dashboard), `@better-auth/oauth-provider ^1.6.10`, `@better-auth/passkey ^1.6.10`, plus built-ins (`admin`, `jwt`, `twoFactor`, `username`, `genericOAuth`).
- `jose ^6.2.3` — JWT verification for OAuth tokens (MCP authentication).
- `bcrypt ^6.0.0` — Password hashing (10 rounds in `packages/auth/src/config.ts`).

**Database & ORM:**
- Drizzle ORM `1.0.0-beta.22` with PostgreSQL driver `pg ^8.20.0` (node-postgres).
- `drizzle-kit 1.0.0-beta.22` — Migration tooling. Config at `packages/db/drizzle.config.ts` (dialect `postgresql`, schema `./src/schema/index.ts`, out `../../migrations`).
- `drizzle-zod 1.0.0-beta.14-a36c63d` — Schema-derived Zod validators in `packages/api`.

**PDF / Rendering:**
- `@react-pdf/renderer ^4.5.1` with types `@react-pdf/types ^2.11.1` — Used by `packages/pdf/src/document.tsx` and all templates under `packages/pdf/src/templates/<name>/`.
- `pdfjs-dist 5.7.284` — Client-side PDF rendering and parsing (browser-only paths).
- `react-pdf-html ^2.1.5`, `node-html-parser ^7.1.0`, `phosphor-icons-react-pdf ^0.1.3`, `cjk-regex ^3.4.0` — PDF helpers and CJK fallback.
- Font registration owned by `packages/pdf/src/hooks/use-register-fonts.ts`; webfont catalog at `packages/fonts/src/webfontlist.json`.

**UI / Styling:**
- Base UI / shadcn-style components — `@base-ui/react ^1.4.1`, `shadcn ^4.7.0` (CLI), components live in `packages/ui/src/components/*.tsx`. Config at `apps/web/components.json` (style `base-nova`, base color `zinc`, icon library `phosphor`).
- Tailwind CSS `^4.3.0` via `@tailwindcss/vite ^4.3.0` and `@tailwindcss/postcss ^4.3.0`. Plugin `@tailwindcss/typography ^0.5.19`. Global stylesheet at `packages/ui/src/styles/globals.css`.
- PostCSS `^8.5.14` and `tw-animate-css ^1.4.0`.
- `class-variance-authority ^0.7.1`, `clsx ^2.1.1`, `tailwind-merge ^3.6.0`.
- Icons: `@phosphor-icons/react ^2.1.10`, `@phosphor-icons/web ^2.1.2`.
- Fonts: `@fontsource-variable/ibm-plex-sans ^5.2.8` (shipped with `packages/ui`).
- Theming: `next-themes ^0.4.6`.
- Animation: `motion ^12.38.0`.
- Toasts: `sonner ^2.0.7`.
- Command palette: `cmdk ^1.1.1`.
- Misc UI: `react-resizable-panels ^4.11.0`, `react-window ^2.2.7`, `react-zoom-pan-pinch ^4.0.3`, `qrcode.react ^4.2.0`, `@uiw/color-convert ^2.10.1`, `@uiw/react-color-colorful ^2.10.1`.

**Drag & Drop and Editing:**
- `@dnd-kit/core ^6.3.1`, `@dnd-kit/sortable ^10.0.0`, `@dnd-kit/utilities ^3.2.2`.
- TipTap `^3.23.1` editor with `starter-kit`, `pm`, `react`, plus extensions `color`, `highlight`, `table`, `text-align`, `text-style`.

**State / Validation / Patterns:**
- Zustand `^5.0.13` — Client and AI state stores (`packages/ai/src/store.ts`).
- Immer `^11.1.8`.
- Zod `^4.4.3` — Validators across schema, api, env, ai, import, utils packages.
- `ts-pattern ^5.9.0` — Pattern matching in API services.
- `es-toolkit ^1.46.1` and `fuse.js ^7.3.0`.

**Internationalization (i18n):**
- Lingui `^6.0.1` family — `@lingui/core`, `@lingui/react`, `@lingui/cli`, `@lingui/format-po`, `@lingui/vite-plugin`, `@lingui/babel-plugin-lingui-macro`.
- Babel transformer chain via `@rolldown/plugin-babel ^0.2.3` and `babel-plugin-macros ^3.1.0`.
- Locale config at `apps/web/lingui.config.ts` (source locale `en-US`, ~55 target locales, pseudo-locale `zu-ZA`).
- Translation catalogs at `apps/web/locales/{locale}.po`. Crowdin sync configured in `crowdin.yml`.

**Email:**
- React Email `^6.1.1` with `@react-email/ui ^6.1.1` — Templates in `packages/email/src/templates/auth.tsx`.
- Nodemailer `^8.0.7` SMTP transport — `packages/email/src/transport.ts`.

**AI:**
- Vercel AI SDK `ai ^6.0.177` and `@ai-sdk/react ^3.0.179`.
- Provider SDKs: `@ai-sdk/openai ^3.0.63`, `@ai-sdk/anthropic ^3.0.76`, `@ai-sdk/google ^3.0.71`, `@ai-sdk/openai-compatible ^2.0.47`, `ollama-ai-provider-v2 ^3.5.0`.
- Supported providers enumerated at `packages/ai/src/types.ts`: `openai`, `anthropic`, `gemini`, `vercel-ai-gateway`, `openrouter`, `ollama`.
- JSON patch / repair: `fast-json-patch ^3.1.1`, `jsonrepair ^3.14.0`, `deepmerge-ts ^7.1.5`.

**Storage:**
- AWS SDK v3 — `@aws-sdk/client-s3 ^3.1045.0` used in `packages/api/src/services/storage.ts`. Marked external in the rolldown build (see `apps/web/vite.config.ts`) and isolated into `packages/runtime-externals` for Docker.

**Image Processing:**
- Sharp `^0.34.5` — Used in `packages/api/src/services/storage.ts` `processImageForUpload`. Disabled when `FLAG_DISABLE_IMAGE_PROCESSING` is true.

**Document Generation / Import:**
- `docx ^9.6.1` — DOCX export utilities in `packages/utils/src/resume/docx/`.
- JSON Resume importers in `packages/import` (`json-resume`, `reactive-resume-json`, `reactive-resume-v4-json`).

**HTML Sanitization:**
- `dompurify ^3.4.2` — Used in `packages/utils/src/sanitize.ts`.
- `@sindresorhus/slugify ^3.0.0`, `unique-names-generator ^4.7.1`, `uuid ^14.0.0`.

**PWA:**
- `vite-plugin-pwa ^1.3.0` — Workbox-based service worker, manifest defined in `apps/web/src/libs/pwa`.

**Testing:**
- Vitest `^4.1.5` with `@vitest/coverage-v8 ^4.1.5` (provider `v8`).
- Shared config in `vitest.shared.ts`; per-package configs at `<pkg>/vitest.config.ts`.
- DOM: `happy-dom ^20.9.0` (`disableJavaScriptFileLoading`, `disableCSSFileLoading`, navigation disabled in `vitest.shared.ts`).
- Testing Library: `@testing-library/react ^16.3.2`, `@testing-library/dom ^10.4.1`, `@testing-library/jest-dom ^6.9.1`, `@testing-library/user-event ^14.6.1`.
- Tests are co-located in each package's `src/**/*.{test,spec}.{ts,tsx}` and discovered automatically.

**Lint / Format / Tooling:**
- Biome `^2.4.15` — Sole linter + formatter (`biome.json`: tabs, double quotes, line width 120, organized import groups, `useSortedClasses` for `clsx`/`cva`/`cn`). Pre-commit runs through Lefthook.
- Lefthook `^2.1.6` — Git hooks defined in `lefthook.yml` (`biome check --write --unsafe` on staged JS/TS/JSON files; `commitlint --edit` on commit messages).
- Commitlint `^21.0.0` with `@commitlint/config-conventional` (see `commitlint.config.cjs`).
- Knip `^6.12.2` — Dead-code/unused-deps detection (`knip.json`).
- `npm-check-updates ^22.1.1`.
- `tsx ^4.21.0` — Used by `packages/scripts` for ad hoc TS scripts.

## Key Dependencies

**Critical:**
- `@tanstack/react-start ^1.167.65` — App framework boundary; route server handlers depend on it.
- `@orpc/server ^1.14.2` — Type-safe RPC; backbone of `/api/rpc` and `/api/openapi`.
- `better-auth 1.6.10` — Identity, sessions, OAuth provider, MCP auth.
- `drizzle-orm 1.0.0-beta.22` + `pg ^8.20.0` — All DB access.
- `@react-pdf/renderer ^4.5.1` — Resume PDF generation.
- `@aws-sdk/client-s3 ^3.1045.0` — S3-compatible object storage.
- `@modelcontextprotocol/sdk ^1.29.0` — MCP server endpoint.
- `ai ^6.0.177` + `@ai-sdk/*` — Resume AI features (analysis, parsing, chat).

**Infrastructure:**
- `vite ^8.0.11` + `nitro 3.0.260429-beta` — Build and server runtime.
- `turbo ^2.9.12` — Workspace task graph and caching.
- `dotenv ^17.4.2` — Loaded by `packages/env/src/server.ts` for app/server code (drizzle-kit does NOT auto-load).
- `@t3-oss/env-core ^0.13.11` — Server env validation in `packages/env/src/server.ts`.

## Configuration

**TypeScript:**
- Root `tsconfig.json` extends `@reactive-resume/config/tsconfig.base.json` (`packages/config/tsconfig.base.json`).
- Each package has its own `tsconfig.json` and runs `tsgo --noEmit`.
- Apps/packages export source from `src/*.ts` via package.json `exports` — no `dist/` artifacts unless explicitly built (e.g. `apps/web/.output`).

**Build:**
- `apps/web/vite.config.ts` orchestrates `tailwindcss`, `tanstackStart`, `viteReact`, `lingui`, `babel` (Lingui macro preset), `nitro` (with `1.migrate.ts` and `2.storage.ts` plugins), and `VitePWA`.
- Rolldown externals: `bcrypt`, `sharp`, `@aws-sdk/client-s3` (kept out of the client/server bundle and provided by `packages/runtime-externals` in Docker).
- Output: `apps/web/.output/server/index.mjs` (Nitro), public assets in `apps/web/.output/public`.

**Database:**
- Drizzle config: `packages/db/drizzle.config.ts` — `dialect: "postgresql"`, schema in `packages/db/src/schema/index.ts`, migrations written to repo-root `migrations/`.
- Client: `packages/db/src/client.ts` exposes singleton `db` plus `Pool` via `pg`, using `env.DATABASE_URL`.
- Startup auto-migration: `apps/web/plugins/1.migrate.ts` runs `drizzle-orm/node-postgres/migrator` against the resolved `migrations/` folder.

**Environment:**
- Server env contract validated by Zod in `packages/env/src/server.ts` (via `@t3-oss/env-core`).
- `dotenv` auto-loads root `.env` from `packages/env/src/server.ts` using `findWorkspaceRoot()`.
- Required: `APP_URL`, `DATABASE_URL`, `AUTH_SECRET`.
- Cache invalidation env vars listed in `turbo.json` `globalEnv`.
- `.env.example` present at repo root; `.env.local` and `.env.production` exist locally (contents not read — may contain secrets).

**Linting / Formatting:**
- `biome.json` — Tabs, 120-col, double quotes, sorted Tailwind classes for `clsx|cva|cn`, organized import groups (`type` imports first, then Node built-ins, test packages, third-party, `@reactive-resume/**`, then aliases/relative).
- `lefthook.yml` — Pre-commit Biome on staged files; commit-msg Commitlint.
- `commitlint.config.cjs` — Conventional commits.
- `knip.json` — Workspace-level ignores for `runtime-externals` external deps.

**Container / Compose:**
- `Dockerfile` (multi-stage): `base` (Node 24 slim + corepack), `pruner` (turbo prune), `builder` (frozen lockfile install + `pnpm turbo run build --filter=web --force`), `runtime-pruner` + `runtime-deps` (deploy `@reactive-resume/runtime-externals` with native deps), final `runtime` image running `node .output/server/index.mjs`, HEALTHCHECK on `/api/health`.
- `compose.dev.yml` — Dev `postgres:latest` + `seaweedfs:latest` (S3 emulator) + `seaweedfs_create_bucket` init container using `quay.io/minio/mc:latest`.
- `compose.yml` — Same services plus the app container `reactive_resume` built from `Dockerfile`, with `data_network`/`storage_network` and S3 env defaults pointing at SeaweedFS.

## Platform Requirements

**Development:**
- Node.js 24, pnpm 11.0.9 (via Corepack), Docker (for Postgres / SeaweedFS).
- Repo-local `data/` directory for local-storage mode (auto-created by `apps/web/plugins/2.storage.ts`).
- `LOCAL_STORAGE_PATH` must be absolute when set.
- SMTP optional; without it `packages/email/src/transport.ts` logs the email to console.

**Production:**
- Single Node 24 process on port 3000 (`apps/web/.output/server/index.mjs`).
- Official Docker image listed in `Dockerfile` labels (`org.opencontainers.image.url=https://rxresu.me`).
- Production uses S3-compatible storage when all three of `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_BUCKET` are set; otherwise falls back to local filesystem under `/app/data` (per Dockerfile `ENV LOCAL_STORAGE_PATH=/app/data`).
- HEALTHCHECK polls `GET /api/health` (handler at `apps/web/src/routes/api/health.ts` checks DB and storage with a 1.5s timeout).
- Rate limiting only active when `NODE_ENV=production` (see `packages/auth/src/config.ts` and `packages/api/src/middleware/rate-limit/index.ts`).

---

*Stack analysis: 2026-05-11*