# Codebase Structure

**Analysis Date:** 2026-04-18

## Directory Layout

```text
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*