# Codebase Structure

**Analysis Date:** 2026-04-20

## Directory Layout

```text
agent-park/
├── .planning/codebase/        # Generated codebase maps consumed by GSD
├── docs/integrations/n8n/     # Source-of-truth docs for external n8n workflows and dataflow
├── prisma/                    # Prisma schema, migrations, and seed script
├── public/                    # Static assets served by Next.js
├── scripts/                   # Repo maintenance scripts
├── src/app/                   # App Router pages, layouts, metadata files, and API routes
├── src/components/            # Reusable UI grouped by feature area
├── src/hooks/                 # Server-side query/read-model modules
├── src/i18n/                  # `next-intl` request configuration
├── src/lib/                   # Shared infrastructure and domain utilities
├── src/messages/              # Locale dictionaries
├── AGENTS.md                  # Repo-specific agent instructions
├── next.config.js             # Next.js config with `next-intl`
├── package.json               # App scripts and dependency manifest
├── tailwind.config.ts         # Tailwind theme and content scan config
├── tsconfig.json              # TypeScript config and `@/*` alias
├── vercel.json                # Deployment config
└── vitest.config.ts           # Unit test config
```

## Directory Purposes

**`.planning/codebase/`:**
- Purpose: Store generated architecture, stack, integration, testing, and concern maps for GSD.
- Contains: `ARCHITECTURE.md`, `STRUCTURE.md`, `STACK.md`, `INTEGRATIONS.md`, `CONVENTIONS.md`, `TESTING.md`, `CONCERNS.md`, `N8N-CONTEXT.md`, `N8N-DATAFLOW.md`
- Key files: `.planning/codebase/ARCHITECTURE.md`, `.planning/codebase/STRUCTURE.md`, `.planning/codebase/N8N-CONTEXT.md`, `.planning/codebase/N8N-DATAFLOW.md`

**`docs/integrations/n8n/`:**
- Purpose: Keep external workflow contracts, workflow inventory, and end-to-end dataflow inside the repository.
- Contains: `registry.json`, generated workflow inventory, cross-workflow dataflow docs, exported workflow placeholders, and per-workflow notes.
- Key files: `docs/integrations/n8n/README.md`, `docs/integrations/n8n/registry.json`, `docs/integrations/n8n/DATAFLOW.md`, `docs/integrations/n8n/CONTEXT.generated.md`, `docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md`

**`docs/integrations/n8n/workflows/`:**
- Purpose: Describe individual external workflows separately from the app code.
- Contains: `01-topic-discovery.md` through `08-project-tag-reset.md`, plus `README.md`.
- Key files: `docs/integrations/n8n/workflows/01-topic-discovery.md`, `docs/integrations/n8n/workflows/02-github-trending-discovery.md`, `docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md`, `docs/integrations/n8n/workflows/06-rag-project-search.md`, `docs/integrations/n8n/workflows/07-signals-aggregation.md`

**`prisma/`:**
- Purpose: Own the database contract and local bootstrapping path.
- Contains: `schema.prisma`, `seed.ts`, and migration directories under `prisma/migrations/`.
- Key files: `prisma/schema.prisma`, `prisma/seed.ts`, `prisma/migrations/20260106122028_init/migration.sql`, `prisma/migrations/20260126000000_add_project_embedding/migration.sql`, `prisma/migrations/20260418191500_remove_discovery_pipeline/migration.sql`

**`scripts/`:**
- Purpose: Hold repository maintenance scripts that generate or sync documentation.
- Contains: `generate-n8n-context.mjs`
- Key files: `scripts/generate-n8n-context.mjs`

**`src/app/`:**
- Purpose: Own all App Router entry points, route-local client islands, global assets, metadata routes, and API handlers.
- Contains: `layout.tsx`, `globals.css`, `robots.ts`, `sitemap.ts`, `VercelMetrics.tsx`, localized routes, and `/api/*`.
- Key files: `src/app/layout.tsx`, `src/app/[locale]/layout.tsx`, `src/app/[locale]/page.tsx`, `src/app/[locale]/projects/page.tsx`, `src/app/[locale]/signals/page.tsx`, `src/app/api/projects/route.ts`, `src/app/api/signals/route.ts`

**`src/app/[locale]/`:**
- Purpose: Group all locale-prefixed, user-facing routes under the same shell.
- Contains: Home, about, projects, signals, `not-found.tsx`, and a catch-all fallback.
- Key files: `src/app/[locale]/layout.tsx`, `src/app/[locale]/page.tsx`, `src/app/[locale]/about/page.tsx`, `src/app/[locale]/projects/page.tsx`, `src/app/[locale]/projects/[id]/page.tsx`, `src/app/[locale]/signals/page.tsx`

**`src/app/[locale]/projects/`:**
- Purpose: Own the projects browse route plus the route-local browser islands that manage query-driven browsing.
- Contains: `page.tsx`, `ProjectsPageClient.tsx`, `ProjectsResultsClient.tsx`, and the `[id]/` detail route subfolder.
- Key files: `src/app/[locale]/projects/page.tsx`, `src/app/[locale]/projects/ProjectsPageClient.tsx`, `src/app/[locale]/projects/ProjectsResultsClient.tsx`, `src/app/[locale]/projects/[id]/page.tsx`

**`src/app/api/`:**
- Purpose: Group JSON APIs and webhook handlers by resource area.
- Contains: Project list/detail routes, AI search proxy, signals feed, tags endpoints, and signal ingestion webhook.
- Key files: `src/app/api/projects/route.ts`, `src/app/api/projects/[slug]/route.ts`, `src/app/api/search/ai/route.ts`, `src/app/api/signals/route.ts`, `src/app/api/tags/route.ts`, `src/app/api/tags/maintenance/route.ts`, `src/app/api/tags/reset-projects/route.ts`, `src/app/api/webhook/signals/route.ts`

**`src/components/`:**
- Purpose: Store reusable UI by product area instead of by primitive type.
- Contains: `home`, `layout`, `locale`, `project`, `search`, `signals`, and an empty `ui` folder.
- Key files: `src/components/home/HomeOverviewStats.tsx`, `src/components/project/ProjectCard.tsx`, `src/components/project/ProjectDetail.tsx`, `src/components/project/TagFilterPanel.tsx`, `src/components/search/AISearchBar.tsx`, `src/components/signals/SignalFeedClient.tsx`

**`src/hooks/`:**
- Purpose: Hold server-side query/read-model modules.
- Contains: `useProjects.ts` and `useHome.ts`
- Key files: `src/hooks/useProjects.ts`, `src/hooks/useHome.ts`

**`src/i18n/`:**
- Purpose: Configure `next-intl` request resolution and message loading.
- Contains: `request.ts`
- Key files: `src/i18n/request.ts`

**`src/lib/`:**
- Purpose: Hold shared infrastructure, schema validation, and domain helpers used across pages and APIs.
- Contains: Prisma bootstrap, API auth, cache fallback, slug generation, tag taxonomy, signal hotness helpers, Zod schemas, and GitHub badge utilities.
- Key files: `src/lib/prisma.ts`, `src/lib/prisma-url.ts`, `src/lib/auth.ts`, `src/lib/cache.ts`, `src/lib/signal-hotness.ts`, `src/lib/tag-taxonomy.ts`, `src/lib/validations.ts`, `src/lib/github/badges.ts`

**`src/messages/`:**
- Purpose: Store locale message bundles consumed by `next-intl`.
- Contains: `en.json` and `zh.json`
- Key files: `src/messages/en.json`, `src/messages/zh.json`

**`src/types/`:**
- Purpose: Reserved location for shared type modules.
- Contains: No files in the inspected tree.
- Key files: Not applicable

## Key File Locations

**Entry Points:**
- `src/app/layout.tsx`: Root HTML/body shell and Vercel metrics mounting.
- `src/middleware.ts`: Locale middleware for all non-API, non-static requests.
- `src/app/[locale]/layout.tsx`: Localized shell, navigation, footer, and translation provider.
- `src/app/[locale]/page.tsx`: Home route entry.
- `src/app/[locale]/projects/page.tsx`: Projects browse entry.
- `src/app/[locale]/projects/[id]/page.tsx`: Project detail entry.
- `src/app/[locale]/signals/page.tsx`: Signals route entry.
- `src/app/sitemap.ts`: Dynamic sitemap generation from project data.
- `src/app/robots.ts`: Robots rules and sitemap pointer.
- `scripts/generate-n8n-context.mjs`: n8n context generation entry point.

**API Endpoints:**
- `src/app/api/projects/route.ts`: Paginated projects list endpoint.
- `src/app/api/projects/[slug]/route.ts`: Single-project JSON endpoint.
- `src/app/api/search/ai/route.ts`: AI search proxy to the external n8n webhook plus DB hydration.
- `src/app/api/signals/route.ts`: Cursor-paginated signals feed endpoint.
- `src/app/api/tags/route.ts`: Cached tag list endpoint.
- `src/app/api/tags/maintenance/route.ts`: Authenticated tag merge/update endpoint.
- `src/app/api/tags/maintenance/service.ts`: Route-local service module for tag maintenance transactions.
- `src/app/api/tags/reset-projects/route.ts`: Authenticated project-tag replacement endpoint.
- `src/app/api/webhook/signals/route.ts`: Authenticated signal ingestion webhook.

**Configuration:**
- `package.json`: App scripts, dependency graph, and `pnpm n8n:context`.
- `next.config.js`: `next-intl` plugin wrapper, standalone output, and image host allowlist.
- `tailwind.config.ts`: Theme extension and content scanning.
- `tsconfig.json`: TypeScript settings and the `@/*` alias.
- `vitest.config.ts`: Node test environment and `src/**/*.test.ts` include pattern.
- `vercel.json`: Deployment/build settings.
- `.env.example`: Template env file, including webhook-related variables. Real secrets stay outside committed files.
- `docs/integrations/n8n/registry.json`: Editable source of truth for external workflow contracts.

**Core Logic:**
- `src/hooks/useProjects.ts`: Project/tag read models, cache wrappers, filter logic, and DB retry handling.
- `src/hooks/useHome.ts`: Homepage aggregate data builder.
- `src/lib/validations.ts`: Shared Zod schemas for queries, webhooks, and internal mutation payloads.
- `src/lib/tag-taxonomy.ts`: Tag category ordering, presets, and inference helpers.
- `src/lib/signal-hotness.ts`: Hotness scoring and schema-capability detection.
- `src/lib/auth.ts`: Shared internal API-key validation.
- `src/app/api/tags/maintenance/service.ts`: Tag merge/update transaction logic.
- `scripts/generate-n8n-context.mjs`: Registry-to-doc generation logic for n8n context.

**Testing:**
- `src/lib/auth.test.ts`
- `src/lib/prisma-url.test.ts`
- `src/lib/validations.test.ts`
- `src/lib/validations.tag-maintenance.test.ts`
- `src/app/api/tags/route.test.ts`
- `src/app/api/tags/maintenance/route.test.ts`
- `src/app/api/tags/maintenance/service.test.ts`
- `src/app/api/tags/reset-projects/route.test.ts`
- `e2e/`: Not present in the inspected tree

## Naming Conventions

**Files:**
- Use Next.js route conventions inside `src/app`, such as `page.tsx`, `layout.tsx`, `route.ts`, `not-found.tsx`, `robots.ts`, and `sitemap.ts`.
- Use `PascalCase.tsx` for reusable components under `src/components/`, such as `ProjectCard.tsx`, `ProjectDetail.tsx`, `HomeOverviewStats.tsx`, and `SignalFeedClient.tsx`.
- Keep route-local browser components adjacent to their route, such as `src/app/[locale]/projects/ProjectsPageClient.tsx` and `src/app/[locale]/projects/ProjectsResultsClient.tsx`.
- Keep shared utility files lower-case or kebab-case under `src/lib/`, such as `prisma.ts`, `cache.ts`, `signal-hotness.ts`, and `tag-taxonomy.ts`.
- Keep tests adjacent to the source file they exercise, using `*.test.ts`.

**Directories:**
- Group user-facing routes by URL shape under `src/app/`.
- Group reusable UI by feature area under `src/components/`, not by HTML primitive.
- Keep shared server read-model logic flat in `src/hooks/`.
- Keep cross-cutting utilities flat in `src/lib/`, with only narrow nested folders such as `src/lib/github/`.
- Keep external automation documentation under `docs/integrations/n8n/`, not mixed into `src/`.

## Where to Add New Code

**New User-Facing Route:**
- Primary code: add a route under `src/app/[locale]/...`, for example `src/app/[locale]/new-section/page.tsx`.
- Route metadata: colocate `generateMetadata` in that route file.
- Shared shell changes: edit `src/app/[locale]/layout.tsx` only if the new route needs global navigation/footer updates.

**New Route-Local Browser State:**
- Implementation: colocate the client component under the route folder in `src/app/[locale]/...`.
- Examples to follow: `src/app/[locale]/projects/ProjectsPageClient.tsx`, `src/app/[locale]/projects/ProjectsResultsClient.tsx`

**New Reusable UI Component:**
- Implementation: place it in the matching feature folder under `src/components/`.
- Examples:
- `src/components/project/` for project cards, details, sidebars, filters, and related UI.
- `src/components/search/` for search bars and AI-result renderers.
- `src/components/signals/` for signal-specific reusable UI.

**New Read Query or Read Model:**
- Project and taxonomy reads: extend `src/hooks/useProjects.ts`.
- Home aggregate reads: extend `src/hooks/useHome.ts`.
- New domain-specific read module: add another file under `src/hooks/` if the logic is large enough to stand alone.

**New Shared Utility or Domain Rule:**
- Prisma/bootstrap changes: `src/lib/prisma.ts` or `src/lib/prisma-url.ts`.
- Validation contracts: `src/lib/validations.ts`.
- Tag/category rules: `src/lib/tag-taxonomy.ts`.
- Signal hotness logic: `src/lib/signal-hotness.ts`.
- Internal API auth helpers: `src/lib/auth.ts`.

**New API Endpoint:**
- Primary code: add `route.ts` under `src/app/api/<resource>/`.
- Route-specific service logic: colocate it beside the route, following `src/app/api/tags/maintenance/service.ts`.
- Shared payload validation: add or extend schemas in `src/lib/validations.ts`.

**New n8n Workflow Mapping:**
- Workflow contract/source of truth: update `docs/integrations/n8n/registry.json`.
- Workflow note: add or update the matching file under `docs/integrations/n8n/workflows/`.
- Generated mirrors: run `pnpm n8n:context` so `docs/integrations/n8n/CONTEXT.generated.md` and `.planning/codebase/N8N-CONTEXT.md` stay synchronized.

**New External Discovery Queue Logic:**
- Do not place it under `src/app/api/` unless the discovery service is explicitly being absorbed into this repository.
- Current queue/task endpoints described in `docs/integrations/n8n/DATAFLOW.md` are external boundaries, not missing route stubs to extend casually.

**New Locale Strings:**
- Add keys to both `src/messages/en.json` and `src/messages/zh.json`.
- Resolve them through `next-intl` in route or component code.

**New Database Model or Field:**
- Schema: `prisma/schema.prisma`
- Migration: add a new directory under `prisma/migrations/`
- Seed changes: `prisma/seed.ts` if local bootstrapping requires the new data

**New Tests:**
- Unit-style tests: colocate as `*.test.ts` beside the source file.
- Browser/e2e tests: create a top-level `e2e/` directory because it is not present in the current tree.

## Special Directories

**`docs/integrations/n8n/`:**
- Purpose: Document external workflows that feed or depend on this repo.
- Generated: Partially
- Committed: Yes

**`docs/integrations/n8n/exports/`:**
- Purpose: Reserved location for exported workflow JSON files.
- Generated: Yes
- Committed: Yes

**`.planning/codebase/`:**
- Purpose: Store generated repository maps for GSD orchestration and execution.
- Generated: Yes
- Committed: Yes

**`src/app/[locale]/projects/`:**
- Purpose: Contains the projects browse route plus its route-local client islands and nested detail route.
- Generated: No
- Committed: Yes

**`src/app/api/tags/maintenance/`:**
- Purpose: Contains a route handler, a route-local service module, and colocated tests for tag governance.
- Generated: No
- Committed: Yes

**`prisma/migrations/`:**
- Purpose: Store schema migration history.
- Generated: Yes
- Committed: Yes

**`.next/`:**
- Purpose: Next.js build output and development cache.
- Generated: Yes
- Committed: No

## Placement Rules

**Use `src/app` only for route ownership:**
- Put code under `src/app` when it directly maps to a URL, metadata document, or route-local client island.

**Use `src/components` for cross-route reuse:**
- Promote a route-local component into `src/components/` only when it is reused or clearly generic.

**Treat `src/hooks` as server query modules, not browser hooks:**
- `src/hooks/useProjects.ts` and `src/hooks/useHome.ts` are imported by server components and route handlers.
- Follow that pattern for future read-model modules.

**Keep Prisma concentrated away from most UI files:**
- Direct Prisma access lives in `src/hooks/*`, `src/app/api/*`, and `src/lib/prisma.ts`.
- Most UI should consume read models or JSON responses, not query the database directly.

**Keep external workflow context out of `src/`:**
- n8n and discovery queue behavior belongs in `docs/integrations/n8n/*` and the generated `.planning/codebase/N8N-*.md` mirrors until runtime code is actually moved into this repository.

**Do not assume `/api/discovery/*` exists here:**
- If a feature depends on discovery tasks, first verify whether it belongs to the external discovery service or the app itself.
- The current inspected tree contains no `src/app/api/discovery/` implementation.

---

*Structure analysis: 2026-04-20*