agent-park/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-04-18

Directory Layout

agent_park/
├── prisma/                    # Prisma schema, migrations, and seed script
├── src/app/                   # Next.js App Router entry points, layouts, API routes, global assets
├── 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 utilities, validation, Prisma client, taxonomy logic
├── src/messages/              # Locale message JSON files
├── .eslintrc.json             # ESLint rules
├── .prettierrc.json           # Prettier rules
├── next.config.js             # Next.js config with next-intl plugin
├── tailwind.config.ts         # Tailwind theme and content scan config
├── tsconfig.json              # TypeScript config and `@/*` path alias
├── vercel.json                # Vercel build/deploy config
└── vitest.config.ts           # Vitest config for `src/**/*.test.ts`

Directory Purposes

prisma/:

• Purpose: Own the database contract and seed path.
• Contains: prisma/schema.prisma, migration directories under prisma/migrations/*, and prisma/seed.ts.
• Key files: prisma/schema.prisma, prisma/seed.ts

src/app/:

• Purpose: Hold all App Router entry points, route-local components, API handlers, and app-wide assets.
• Contains: layout.tsx, page.tsx, route.ts, route-local client components, globals.css, robots.ts, sitemap.ts, and icon.svg.
• Key files: src/app/layout.tsx, src/app/[locale]/layout.tsx, src/app/[locale]/page.tsx, src/app/[locale]/projects/page.tsx, src/app/api/projects/route.ts, src/app/api/signals/route.ts

src/app/[locale]/:

• Purpose: Group locale-prefixed user-facing routes.
• Contains: localized pages such as src/app/[locale]/page.tsx, src/app/[locale]/projects/page.tsx, src/app/[locale]/projects/[id]/page.tsx, src/app/[locale]/signals/page.tsx, src/app/[locale]/about/page.tsx, and fallbacks like src/app/[locale]/not-found.tsx.
• Key files: src/app/[locale]/layout.tsx, src/app/[locale]/projects/ProjectsPageClient.tsx, src/app/[locale]/projects/ProjectsResultsClient.tsx

src/app/api/:

• Purpose: Group JSON endpoints and webhook handlers by resource.
• Contains: route handlers and a route-local service module at src/app/api/tags/maintenance/service.ts.
• 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/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 domain area, not by primitive type.
• Contains: feature folders home, layout, locale, project, search, and signals.
• Key files: src/components/project/ProjectList.tsx, src/components/project/ProjectDetail.tsx, src/components/search/AISearchBar.tsx, src/components/signals/SignalFeedClient.tsx

src/hooks/:

• Purpose: Hold server-side data-fetching and read-model builders.
• Contains: src/hooks/useProjects.ts and src/hooks/useHome.ts.
• Key files: src/hooks/useProjects.ts, src/hooks/useHome.ts

src/i18n/:

• Purpose: Configure next-intl request handling.
• Contains: src/i18n/request.ts.
• Key files: src/i18n/request.ts

src/lib/:

• Purpose: Hold cross-cutting domain and infrastructure utilities.
• Contains: auth, cache helpers, Prisma client, GitHub link helpers, tag taxonomy, slug generation, hotness scoring, and validation schemas.
• Key files: src/lib/auth.ts, src/lib/cache.ts, src/lib/prisma.ts, src/lib/tag-taxonomy.ts, src/lib/signal-hotness.ts, src/lib/validations.ts, src/lib/github/badges.ts

src/messages/:

• Purpose: Store locale dictionaries loaded by next-intl.
• Contains: src/messages/en.json and src/messages/zh.json.
• Key files: src/messages/en.json, src/messages/zh.json

Key File Locations

Entry Points:

• src/app/layout.tsx: Root HTML/body shell and conditional analytics.
• src/app/[locale]/layout.tsx: Locale-aware site shell, navigation, footer, and translation provider.
• src/app/[locale]/page.tsx: Localized home page.
• src/app/[locale]/projects/page.tsx: Projects search/browse page.
• src/app/[locale]/projects/[id]/page.tsx: Project detail page.
• src/app/[locale]/signals/page.tsx: Signals feed page shell.
• src/app/[locale]/about/page.tsx: About page.
• src/middleware.ts: Locale routing middleware.

API Endpoints:

• src/app/api/projects/route.ts: Paginated projects list API.
• src/app/api/projects/[slug]/route.ts: Single-project JSON endpoint.
• src/app/api/search/ai/route.ts: AI search proxy and hydrator.
• src/app/api/signals/route.ts: Cursor-paginated signals feed API.
• src/app/api/tags/route.ts: Tags list API.
• src/app/api/tags/maintenance/route.ts: Authenticated tag update/merge API.
• src/app/api/tags/reset-projects/route.ts: Authenticated project-tag replacement API.
• src/app/api/webhook/signals/route.ts: Authenticated signal ingestion webhook.

Configuration:

• next.config.js: Wraps Next config with the next-intl plugin and remote image rules.
• tailwind.config.ts: Tailwind content paths and theme extension.
• tsconfig.json: Strict TypeScript settings and the @/* alias.
• vitest.config.ts: Node test environment and src/**/*.test.ts inclusion.
• vercel.json: Build/install commands and region targeting.
• .eslintrc.json: Lint rules.
• .prettierrc.json: Formatting rules.
• .env.example: Template environment file. .env and .env.local are present in the repository root but were not inspected.

Core Logic:

• src/hooks/useProjects.ts: Project list/detail queries, filter normalization, tag grouping, caching, and retry logic.
• src/hooks/useHome.ts: Home-page aggregate data builder.
• src/lib/tag-taxonomy.ts: Tag category metadata and inference rules.
• src/lib/validations.ts: Zod schemas for API inputs and domain payloads.
• src/app/api/tags/maintenance/service.ts: Transactional tag maintenance logic.
• src/lib/signal-hotness.ts: Signal hot-score computation and schema capability detection.

Testing:

• src/lib/auth.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 repository tree.

Naming Conventions

Files:

• Use Next.js route conventions inside src/app, for example page.tsx, layout.tsx, route.ts, not-found.tsx, robots.ts, and sitemap.ts.
• Use PascalCase.tsx for reusable components, for example src/components/project/ProjectCard.tsx, src/components/project/ProjectSidebar.tsx, and src/components/home/HomeOverviewStats.tsx.
• Keep route-specific helper components adjacent to the route they support, for example src/app/[locale]/projects/ProjectsPageClient.tsx and src/app/[locale]/projects/ProjectsResultsClient.tsx.
• Use lower-case or kebab-case utility filenames in src/lib, for example src/lib/prisma.ts, src/lib/cache.ts, src/lib/tag-taxonomy.ts, and src/lib/signal-hotness.ts.
• Keep test files adjacent to the code they cover using *.test.ts, for example src/app/api/tags/maintenance/service.test.ts.

Directories:

• Group reusable UI by product area under src/components, for example src/components/project and src/components/search.
• Group route files by URL shape under src/app, for example src/app/[locale]/projects/[id] and src/app/api/projects/[slug].
• Keep infrastructure and domain utilities flat under src/lib instead of nesting many sublayers. The only nested utility folder detected is src/lib/github/.

Where to Add New Code

New User-Facing Page or Route Segment:

• Primary code: add a new route under src/app/[locale]/... using Next conventions, for example src/app/[locale]/new-section/page.tsx.
• Shared shell changes: modify src/app/[locale]/layout.tsx only if the new route needs site-wide navigation or footer changes.
• Metadata/SEO for the route: colocate generateMetadata in the route file, following src/app/[locale]/about/page.tsx and src/app/[locale]/signals/page.tsx.

New API Endpoint:

• Primary code: add route.ts under src/app/api/<resource>/.
• Route-local helpers or service logic: colocate them next to the route, following src/app/api/tags/maintenance/service.ts.
• Validation: add or extend schemas in src/lib/validations.ts unless the validation is tightly route-local and one-off.

New Reusable UI Component:

• Implementation: place it in the matching feature folder under src/components/.
• Examples:
  • Project-related UI goes in src/components/project/.
  • Search UI goes in src/components/search/.
  • Home-page modules go in src/components/home/.
• If a component is only used by one route and owns that route’s browser state, colocate it under the route folder in src/app/[locale]/..., following src/app/[locale]/projects/ProjectsPageClient.tsx.

New Data Query or Read Model:

• Shared project/home reads: extend src/hooks/useProjects.ts or src/hooks/useHome.ts.
• New domain-specific reads: add a new module under src/hooks/ if the logic becomes large enough to stand alone.
• Use src/lib/prisma.ts for Prisma access instead of creating new Prisma clients.

New Shared Utility or Domain Rule:

• Shared helpers: add to src/lib/.
• Taxonomy/tag rules: extend src/lib/tag-taxonomy.ts.
• Request validation: extend src/lib/validations.ts.
• Authentication helpers for internal APIs: extend src/lib/auth.ts.

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, following src/app/[locale]/layout.tsx and src/components/project/ProjectList.tsx.

New Database Model or Field:

• Schema: update prisma/schema.prisma.
• Migration: create a new directory under prisma/migrations/.
• Seed updates: modify prisma/seed.ts only if the new data is required for local bootstrapping.

New Tests:

• API and utility tests: colocate with the source file as *.test.ts.
• There is no current e2e/ directory in the inspected tree, so introducing end-to-end tests will require creating that top-level directory explicitly.

Special Directories

src/app/[locale]/projects/:

• Purpose: Contains one route page plus its route-local client islands.
• Generated: No
• Committed: Yes

src/app/api/tags/maintenance/:

• Purpose: Contains a route handler, a service module, and colocated tests for the tag-maintenance feature.
• Generated: No
• Committed: Yes

prisma/migrations/:

• Purpose: Stores schema migration history.
• Generated: Yes
• Committed: Yes

.next/:

• Purpose: Next.js build output and development cache.
• Generated: Yes
• Committed: No

.planning/codebase/:

• Purpose: Stores generated repository mapping documents such as this file.
• Generated: Yes
• Committed: Uncertain from inspected source files alone.

Placement Rules

Use src/app for route ownership:

• Put code in src/app only when it directly maps to a URL, metadata document, or route-local UI state.

Use src/components for reuse across routes:

• Promote a route-local component into src/components only when another route needs it or it becomes generic enough to stand alone.

Treat src/hooks as a server query layer, not browser hooks:

• The existing useProjects.ts and useHome.ts modules are imported by server components and API handlers. Follow that pattern when adding read models there.

Keep Prisma out of most UI files:

• UI code typically consumes data returned by src/hooks/* or JSON from src/app/api/*.
• Direct Prisma calls are concentrated in src/hooks/*, src/app/api/*, and src/lib/prisma.ts.

---

Structure analysis: 2026-04-18