mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refresh codebase map

Browse Source
This commit is contained in:
mzaxd
2026-04-20 18:59:15 +08:00
parent 5b64422dfb
commit ab3f8fecc3
9 changed files with 1396 additions and 709 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/codebase/STACK.md
+56 -52
View File
@@ -1,97 +1,101 @@
# Technology Stack
**Analysis Date:** 2026-04-18
**Analysis Date:** 2026-04-20
## Languages
**Primary:**
- TypeScript 5.x - Application code, API routes, hooks, Prisma access, and most tooling live in `src/**/*.ts`, `src/**/*.tsx`, `prisma/seed.ts`, `tailwind.config.ts`, and `vitest.config.ts`; the compiler is declared in `package.json`.
- TypeScript 5.x - Main application, API, Prisma helpers, hooks, and tooling live in `src/**/*.ts`, `src/**/*.tsx`, `prisma/seed.ts`, `tailwind.config.ts`, and `vitest.config.ts`; the compiler is declared in `package.json`.
**Secondary:**
- JavaScript - Next.js and PostCSS config live in `next.config.js` and `postcss.config.mjs`.
- JavaScript - Runtime and framework config live in `next.config.js`, `postcss.config.mjs`, and `scripts/generate-n8n-context.mjs`.
- CSS - Global styling and external font/icon imports live in `src/app/globals.css`.
- JSON - Locale message catalogs live in `src/messages/en.json` and `src/messages/zh.json`; repo config also uses `.eslintrc.json` and `.prettierrc.json`.
- Prisma schema DSL - Database schema and datasource definitions live in `prisma/schema.prisma`.
- JSON - Repo and content config live in `package.json`, `tsconfig.json`, `.eslintrc.json`, `.prettierrc.json`, `vercel.json`, `docs/integrations/n8n/registry.json`, and `src/messages/*.json`.
- Prisma schema DSL - Database schema, datasource, enums, and vector column definitions live in `prisma/schema.prisma`.
- SQL migrations - Prisma migration output lives in `prisma/migrations/*/migration.sql`.
- Markdown - Integration contracts and workflow docs live in `docs/integrations/n8n/*.md`, `docs/integrations/n8n/workflows/*.md`, and mirrored GSD docs in `.planning/codebase/N8N-CONTEXT.md` and `.planning/codebase/N8N-DATAFLOW.md`.
## Runtime
**Environment:**
- Node.js - Repo runtime is Node-based because scripts use `next`, `vitest`, `prisma`, and `ts-node` from `package.json`.
- Version pinning: Not detected in repo. No `.nvmrc`, `.node-version`, or `.tool-versions` file is present.
- Local tool version observed in this workspace: Node.js `v22.21.1`.
- Node.js 22.x - Containerized runtime is pinned by `Dockerfile` and `Dockerfile.runtime`, both based on `node:22-bookworm`.
- Server runtime is Next.js App Router with standalone output enabled in `next.config.js` and consumed by `Dockerfile.runtime`.
- Local runtime version pin file is not committed. No `.nvmrc`, `.node-version`, or `.tool-versions` file is present at repo root.
**Package Manager:**
- `pnpm` - Project commands, lockfile, and Vercel install/build configuration use `pnpm` in `package.json`, `pnpm-lock.yaml`, and `vercel.json`.
- Local tool version observed in this workspace: `pnpm 10.27.0`.
- `pnpm` - All install/build/test scripts in `package.json`, `vercel.json`, `Dockerfile`, and `nixpacks.toml` use `pnpm`.
- Lockfile: present in `pnpm-lock.yaml`.
## Frameworks
**Core:**
- Next.js `15.1.11` - App Router web framework for pages, layouts, metadata, and route handlers in `src/app/**/*`; version declared in `package.json`.
- React `19.0.0` and `react-dom` `19.0.0` - UI runtime for components in `src/components/**/*` and route segments in `src/app/**/*`; versions declared in `package.json`.
- `next-intl` `4.0.2` - Locale routing and message loading via `next.config.js`, `src/middleware.ts`, `src/i18n/request.ts`, and `src/app/[locale]/layout.tsx`.
- Prisma `6.1.0` / `@prisma/client` `6.1.0` - ORM and generated client used in `src/lib/prisma.ts`, `src/hooks/useProjects.ts`, `src/app/api/**/*`, `prisma/schema.prisma`, and `prisma/seed.ts`.
- Zod `3.24.1` - Request and payload validation in `src/lib/validations.ts` and multiple route handlers under `src/app/api/**/*`.
- Next.js `15.1.11` - App Router pages, layouts, metadata routes, and route handlers live in `src/app/**/*`; framework config is in `next.config.js`.
- React `19.0.0` and `react-dom` `19.0.0` - UI runtime for components in `src/components/**/*` and route segments in `src/app/**/*`.
- `next-intl` `^4.0.2` - Locale middleware and message loading are wired through `next.config.js`, `src/middleware.ts`, `src/i18n/request.ts`, and localized routes under `src/app/[locale]`.
- Prisma `^6.1.0` / `@prisma/client` `^6.1.0` - ORM and generated client used by `src/lib/prisma.ts`, `src/hooks/useProjects.ts`, `src/hooks/useHome.ts`, and route handlers under `src/app/api/**/*`.
- Zod `^3.24.1` - Runtime validation is centralized in `src/lib/validations.ts` and consumed by API routes such as `src/app/api/search/ai/route.ts` and `src/app/api/webhook/signals/route.ts`.
**Testing:**
- Vitest `2.1.8` - Unit-style test runner configured in `vitest.config.ts` and used by files such as `src/lib/auth.test.ts` and `src/app/api/tags/route.test.ts`.
- Vitest `^2.1.8` - Unit-style tests are configured in `vitest.config.ts` and run against `src/**/*.test.ts`.
- Playwright: Not detected in committed dependencies or config. No `playwright.config.*` file and no committed `e2e/` directory are present.
**Build/Dev:**
- Tailwind CSS `3.4.17` - Utility-first styling configured in `tailwind.config.ts` and consumed by `src/app/globals.css` and component classes across `src/components/**/*`.
- PostCSS `8.x` with `autoprefixer` `10.4.20` - CSS processing configured in `postcss.config.mjs`.
- ESLint `9.x` with `eslint-config-next` `15.1.11` and `eslint-config-prettier` `9.1.0` - Linting configured in `.eslintrc.json`.
- Prettier `3.4.2` - Formatting configured in `.prettierrc.json`.
- `ts-node` `10.9.2` - TypeScript execution for seeding via the `prisma.seed` command in `package.json`.
- `tailwindcss-animate` `1.0.7` - Tailwind plugin loaded in `tailwind.config.ts`.
- Tailwind CSS `^3.4.17` - Utility styling is configured in `tailwind.config.ts` and loaded from `src/app/globals.css`.
- `tailwindcss-animate` `^1.0.7` - Tailwind plugin registered in `tailwind.config.ts`.
- PostCSS `^8` with `autoprefixer` `^10.4.20` - CSS processing is configured in `postcss.config.mjs`.
- ESLint `^9` with `eslint-config-next` `15.1.11` and `eslint-config-prettier` `^9.1.0` - Linting rules are configured in `.eslintrc.json`.
- Prettier `^3.4.2` - Formatting rules are configured in `.prettierrc.json`.
- `ts-node` `^10.9.2` - Used by the Prisma seed command configured in `package.json`.
## Key Dependencies
**Critical:**
- `next` `15.1.11` - Main application framework; routes, layouts, metadata, and route handlers all depend on files under `src/app/**/*`.
- `react` `19.0.0` / `react-dom` `19.0.0` - Required by all React components in `src/components/**/*` and page/layout files in `src/app/**/*`.
- `@prisma/client` `6.1.0` - Database access layer instantiated in `src/lib/prisma.ts` and used heavily in `src/hooks/useProjects.ts`, `src/app/api/projects/route.ts`, `src/app/api/signals/route.ts`, and related files.
- `prisma` `6.1.0` - Schema and migration tool backing `prisma/schema.prisma` and `prisma/migrations/*/migration.sql`.
- `next-intl` `4.0.2` - Locale middleware and message loading depend on `src/middleware.ts`, `src/i18n/request.ts`, and `src/messages/*.json`.
- `zod` `3.24.1` - Input validation for search, tag maintenance, and webhook payloads in `src/app/api/search/ai/route.ts`, `src/app/api/tags/maintenance/route.ts`, and `src/app/api/webhook/signals/route.ts`.
- `next` `15.1.11` - Main web framework for `src/app/**/*`.
- `react` `19.0.0` and `react-dom` `19.0.0` - Required by all React components in `src/components/**/*`.
- `@prisma/client` `^6.1.0` - Data access layer instantiated in `src/lib/prisma.ts`.
- `prisma` `^6.1.0` - Schema and migration tooling for `prisma/schema.prisma` and `prisma/migrations/*`.
- `next-intl` `^4.0.2` - Locale-aware routing and translations for `src/middleware.ts`, `src/i18n/request.ts`, and `src/messages/*.json`.
- `zod` `^3.24.1` - Request validation for search, tags, and webhook contracts in `src/lib/validations.ts`.
**Infrastructure:**
- `@vercel/analytics` `1.6.1` and `@vercel/speed-insights` `1.3.1` - Vercel client telemetry mounted in `src/app/VercelMetrics.tsx` and conditionally included in `src/app/layout.tsx`.
- `react-markdown` `10.1.0`, `remark-gfm` `4.0.1`, and `rehype-sanitize` `6.0.0` - Markdown rendering stack used by `src/components/project/MarkdownContent.tsx`.
- `lucide-react` `0.468.0` - Icon set optimized through `experimental.optimizePackageImports` in `next.config.js`.
- `@vercel/analytics` `^1.6.1` - Client analytics are mounted in `src/app/VercelMetrics.tsx`.
- `@vercel/speed-insights` `^1.3.1` - Frontend performance telemetry is mounted in `src/app/VercelMetrics.tsx`.
- `react-markdown` `^10.1.0`, `remark-gfm` `^4.0.1`, and `rehype-sanitize` `^6.0.0` - Markdown rendering and sanitization stack used by `src/components/project/MarkdownContent.tsx`.
- `lucide-react` `^0.468.0` - Icon package optimized through `experimental.optimizePackageImports` in `next.config.js`.
## Configuration
**Environment:**
- Template env vars are documented in `.env.example`.
- Real runtime env files exist as `.env` and `.env.local`; contents were not read.
- Code-level env usage is limited to:
- `DATABASE_URL` in `prisma/schema.prisma`
- `WEBHOOK_API_KEY` in `src/lib/auth.ts`
- `N8N_AI_SEARCH_WEBHOOK` in `src/app/api/search/ai/route.ts`
- `NEXT_PUBLIC_SITE_URL` in `src/app/robots.ts` and `src/app/sitemap.ts`
- `VERCEL_ENV` in `src/app/layout.tsx`
- `.env.example` also declares `NEXT_INTL_DEFAULT_LOCALE` and `NEXT_INTL_SUPPORTED_LOCALES`, but locale handling in current code is hard-coded in `src/i18n/request.ts` and `src/middleware.ts`.
- Database connectivity is anchored by `DATABASE_URL` in `prisma/schema.prisma` and normalized by `buildPrismaDataSourceUrl()` in `src/lib/prisma-url.ts`.
- Optional Postgres mTLS/SSL overlay is configured in `src/lib/prisma-url.ts` using `PG_SSL_ROOT_CERT_B64`, `PG_SSL_IDENTITY_P12_B64`, `PG_SSL_IDENTITY_PASSWORD`, `PG_SSL_CERT_DIR`, and `PG_SSL_MODE`.
- Internal machine-to-machine auth uses `WEBHOOK_API_KEY` in `src/lib/auth.ts`.
- Outbound AI search proxying uses `N8N_AI_SEARCH_WEBHOOK` in `src/app/api/search/ai/route.ts`.
- Canonical URL generation uses `NEXT_PUBLIC_SITE_URL` in `src/app/robots.ts` and `src/app/sitemap.ts`.
- Vercel-only telemetry gating uses `VERCEL_ENV` in `src/app/layout.tsx`.
- Template env files exist as `.env.example`, `.env.local`, and `.env`; contents were not read.
**Build:**
- `next.config.js` wires `next-intl`, remote image hosts, and `optimizePackageImports`.
- `tsconfig.json` enables strict TypeScript, `noUncheckedIndexedAccess`, `noImplicitReturns`, and the `@/*` path alias.
- `tailwind.config.ts` and `postcss.config.mjs` define the styling pipeline.
- `vercel.json` defines deployment-time build/install commands, Next.js framework selection, region `hkg1`, and disables Git-triggered deployments.
- `package.json` scripts expose `dev`, `build`, `start`, `lint`, `test`, and Prisma seeding.
- `next.config.js` enables `output: "standalone"`, wires `next-intl`, configures remote image hosts, and optimizes `lucide-react` imports.
- `tsconfig.json` enables strict TypeScript, `noUncheckedIndexedAccess`, `noImplicitReturns`, `noFallthroughCasesInSwitch`, and the `@/*` alias.
- `tailwind.config.ts` and `postcss.config.mjs` define the frontend styling pipeline.
- `vercel.json` defines install/build commands, the `nextjs` framework target, and region `hkg1`.
- `Dockerfile`, `Dockerfile.runtime`, and `nixpacks.toml` define container build and runtime packaging.
- `scripts/generate-n8n-context.mjs` generates `docs/integrations/n8n/CONTEXT.generated.md` and the GSD mirror `.planning/codebase/N8N-CONTEXT.md`.
## Platform Requirements
**Development:**
- Node.js and `pnpm` are required to run `package.json` scripts.
- PostgreSQL is required because `prisma/schema.prisma` uses the `postgresql` provider and `DATABASE_URL`.
- Prisma client generation is required before production builds; `vercel.json` explicitly runs `pnpm prisma generate && pnpm build`.
- Node.js 22-compatible runtime and `pnpm` are required to run `package.json` scripts.
- PostgreSQL is required because `prisma/schema.prisma` uses the `postgresql` provider.
- Prisma client generation is part of the build path in `vercel.json`, `Dockerfile`, and `nixpacks.toml`.
- The n8n context refresh flow requires `pnpm n8n:context`, which runs `scripts/generate-n8n-context.mjs`.
**Production:**
- Vercel is the explicit deployment target indicated by `vercel.json` and the Vercel-specific telemetry components in `src/app/VercelMetrics.tsx`.
- The app expects Vercel environment semantics for telemetry gating via `process.env.VERCEL_ENV` in `src/app/layout.tsx`.
- Server runtime storage is PostgreSQL via Prisma; no alternate production datastore is configured in repo.
- Vercel is a first-class deployment target via `vercel.json` and the telemetry components in `src/app/VercelMetrics.tsx`.
- Container deployment is also supported through `Dockerfile`, `Dockerfile.runtime`, and `nixpacks.toml`.
- Production data storage is PostgreSQL via Prisma, with a `vector` column in `prisma/schema.prisma` used by semantic-search-related workflows documented under `docs/integrations/n8n/`.
- Standalone Next.js output is expected by `Dockerfile.runtime`, which boots `.next/standalone/server.js`.
---
*Stack analysis: 2026-04-18*
*Stack analysis: 2026-04-20*