225 lines
12 KiB
Markdown
225 lines
12 KiB
Markdown
# 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*
|