298 lines
16 KiB
Markdown
298 lines
16 KiB
Markdown
# 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*
|