mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
804fd756e7be11e90f417e81c6ef18032b45eee4
agent-park/.planning/codebase/STRUCTURE.md
T
mzaxd ab3f8fecc3 docs: refresh codebase map
2026-04-20 18:59:15 +08:00

16 KiB
Raw Blame History

Codebase Structure

Analysis Date: 2026-04-20

Directory Layout

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

Reference in New Issue View Git Blame Copy Permalink