docs: refresh codebase map
This commit is contained in:
+190
-117
@@ -1,196 +1,266 @@
|
||||
# Codebase Structure
|
||||
|
||||
**Analysis Date:** 2026-04-18
|
||||
**Analysis Date:** 2026-04-20
|
||||
|
||||
## Directory Layout
|
||||
|
||||
```text
|
||||
agent_park/
|
||||
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
|
||||
├── src/app/ # Next.js App Router entry points, layouts, API routes, global assets
|
||||
├── 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 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
|
||||
├── 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 `@/*` path alias
|
||||
├── vercel.json # Vercel build/deploy config
|
||||
└── vitest.config.ts # Vitest config for `src/**/*.test.ts`
|
||||
├── 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 seed path.
|
||||
- Contains: `prisma/schema.prisma`, migration directories under `prisma/migrations/*`, and `prisma/seed.ts`.
|
||||
- Key files: `prisma/schema.prisma`, `prisma/seed.ts`
|
||||
- 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: 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`
|
||||
- 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 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`
|
||||
- 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 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`
|
||||
- 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 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`
|
||||
- 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 data-fetching and read-model builders.
|
||||
- Contains: `src/hooks/useProjects.ts` and `src/hooks/useHome.ts`.
|
||||
- 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 handling.
|
||||
- Contains: `src/i18n/request.ts`.
|
||||
- Purpose: Configure `next-intl` request resolution and message loading.
|
||||
- Contains: `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`
|
||||
- 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 dictionaries loaded by `next-intl`.
|
||||
- Contains: `src/messages/en.json` and `src/messages/zh.json`.
|
||||
- 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 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.
|
||||
- `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 API.
|
||||
- `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 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/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:**
|
||||
- `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.
|
||||
- `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 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.
|
||||
- `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 repository tree.
|
||||
- `e2e/`: Not present in the inspected 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`.
|
||||
- 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 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/`.
|
||||
- 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 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 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 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 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:
|
||||
- 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`.
|
||||
- `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 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 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:**
|
||||
- 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`.
|
||||
- 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, following `src/app/[locale]/layout.tsx` and `src/components/project/ProjectList.tsx`.
|
||||
- Resolve them through `next-intl` in route or component code.
|
||||
|
||||
**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.
|
||||
- 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:**
|
||||
- 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.
|
||||
- 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 one route page plus its route-local client islands.
|
||||
- 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 service module, and colocated tests for the tag-maintenance feature.
|
||||
- Purpose: Contains a route handler, a route-local service module, and colocated tests for tag governance.
|
||||
- Generated: No
|
||||
- Committed: Yes
|
||||
|
||||
**`prisma/migrations/`:**
|
||||
- Purpose: Stores schema migration history.
|
||||
- Purpose: Store schema migration history.
|
||||
- Generated: Yes
|
||||
- Committed: Yes
|
||||
|
||||
@@ -199,26 +269,29 @@ agent_park/
|
||||
- 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/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 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.
|
||||
**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 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.
|
||||
**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 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`.
|
||||
**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-18*
|
||||
*Structure analysis: 2026-04-20*
|
||||
|
||||
Reference in New Issue
Block a user