docs: refresh codebase map
This commit is contained in:
@@ -1,125 +1,153 @@
|
||||
# External Integrations
|
||||
|
||||
**Analysis Date:** 2026-04-18
|
||||
**Analysis Date:** 2026-04-20
|
||||
|
||||
## APIs & External Services
|
||||
|
||||
**Workflow Automation / Search:**
|
||||
- n8n webhook - AI search requests are forwarded from `src/app/api/search/ai/route.ts` to the URL in `process.env.N8N_AI_SEARCH_WEBHOOK`.
|
||||
**In-Repo n8n Contracts:**
|
||||
- n8n AI search webhook - The repo-owned AI search proxy in `src/app/api/search/ai/route.ts` forwards validated search requests to the webhook URL in `N8N_AI_SEARCH_WEBHOOK`, then hydrates returned IDs from PostgreSQL via `src/hooks/useProjects.ts`.
|
||||
- SDK/Client: Native `fetch` in `src/app/api/search/ai/route.ts`
|
||||
- Auth: `N8N_AI_SEARCH_WEBHOOK`
|
||||
- Evidence: outbound `GET` request is constructed in `src/app/api/search/ai/route.ts`; `.env.example` provides the webhook variable name.
|
||||
- Repo-side n8n contract registry - n8n workflow metadata and request/response contracts are committed in `docs/integrations/n8n/registry.json`, `docs/integrations/n8n/CONTEXT.generated.md`, `docs/integrations/n8n/DATAFLOW.md`, and per-workflow docs under `docs/integrations/n8n/workflows/*.md`.
|
||||
- SDK/Client: `scripts/generate-n8n-context.mjs`
|
||||
- Auth: None in repo; this is documentation and generation logic
|
||||
- GSD-facing n8n mirrors - Generated mirrors for planning tools live in `.planning/codebase/N8N-CONTEXT.md` and `.planning/codebase/N8N-DATAFLOW.md`.
|
||||
- SDK/Client: Generated by `pnpm n8n:context`
|
||||
- Auth: None in repo
|
||||
|
||||
**Vercel Runtime Telemetry:**
|
||||
- Vercel Analytics - Client analytics are mounted in `src/app/VercelMetrics.tsx` and only rendered when `process.env.VERCEL_ENV === "production"` in `src/app/layout.tsx`.
|
||||
**External-Upstream Workflow Boundaries:**
|
||||
- Discovery Task Service - The n8n docs explicitly describe external endpoints `GET/POST/PATCH /api/discovery/tasks`, `POST /api/discovery/check-duplicates`, and completion/failure callbacks, but this repo does not implement those handlers.
|
||||
- SDK/Client: No in-repo client package; boundary is documented in `docs/integrations/n8n/DATAFLOW.md` and `docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md`
|
||||
- Auth: External to this repo
|
||||
- Topic Discovery and GitHub Trending Discovery - Upstream n8n workflows documented in `docs/integrations/n8n/CONTEXT.generated.md` and `docs/integrations/n8n/workflows/01-topic-discovery.md` / `02-github-trending-discovery.md` depend on GitHub Search and GitHub Trending, then enqueue tasks into the external discovery service.
|
||||
- SDK/Client: n8n runtime outside this repo
|
||||
- Auth: External n8n credentials / runtime env, not committed here
|
||||
- Project Ingestion (Multi-source) - Upstream n8n workflow documented in `docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md` consumes discovery tasks, enriches data with browser/AI steps, and writes project results back outside this repo’s route layer.
|
||||
- SDK/Client: n8n runtime outside this repo
|
||||
- Auth: External n8n credentials / discovery-service auth
|
||||
|
||||
**External Data Sources Used Through n8n:**
|
||||
- GitHub Search API - Upstream dependency for topic discovery documented in `docs/integrations/n8n/CONTEXT.generated.md`.
|
||||
- SDK/Client: n8n workflow, not repository code
|
||||
- Auth: External GitHub credentials in n8n
|
||||
- GitHub Trending - Upstream source for trending discovery documented in `docs/integrations/n8n/CONTEXT.generated.md`.
|
||||
- SDK/Client: n8n scraping workflow
|
||||
- Auth: None implied for the public page
|
||||
- GitHub Repository API - Upstream source for star refresh documented in `docs/integrations/n8n/workflows/04-github-star-refresh.md`.
|
||||
- SDK/Client: n8n workflow, not repository code
|
||||
- Auth: External GitHub credentials in n8n
|
||||
- Hacker News, Reddit, arXiv, Product Hunt, and Hugging Face - Upstream sources for signals aggregation documented in `docs/integrations/n8n/workflows/07-signals-aggregation.md`.
|
||||
- SDK/Client: n8n workflow, not repository code
|
||||
- Auth: External n8n credentials as needed per source
|
||||
- SiliconFlow embeddings API - Upstream embedding provider referenced by the vectorization and RAG search docs in `docs/integrations/n8n/DATAFLOW.md` and `docs/integrations/n8n/CONTEXT.generated.md`.
|
||||
- SDK/Client: n8n workflow, not repository code
|
||||
- Auth: External embedding-service credentials in n8n
|
||||
|
||||
**Platform / Asset Services:**
|
||||
- Vercel Analytics - Client analytics are mounted in `src/app/VercelMetrics.tsx` and gated by `process.env.VERCEL_ENV` in `src/app/layout.tsx`.
|
||||
- SDK/Client: `@vercel/analytics`
|
||||
- Auth: Managed by Vercel runtime; no repo-managed token detected
|
||||
- Vercel Speed Insights - Frontend performance sampling is mounted beside analytics in `src/app/VercelMetrics.tsx`.
|
||||
- Auth: Vercel-managed runtime integration
|
||||
- Vercel Speed Insights - Client performance telemetry is mounted beside analytics in `src/app/VercelMetrics.tsx`.
|
||||
- SDK/Client: `@vercel/speed-insights`
|
||||
- Auth: Managed by Vercel runtime; no repo-managed token detected
|
||||
|
||||
**Static Asset Providers:**
|
||||
- Google Fonts / Material Icons - CSS imports in `src/app/globals.css` load Inter, Space Mono, and Material Icons from `fonts.googleapis.com`.
|
||||
- Auth: Vercel-managed runtime integration
|
||||
- Google Fonts and Material Icons - CSS imports in `src/app/globals.css` pull `Inter`, `Space Mono`, and Material Icons from `fonts.googleapis.com`.
|
||||
- SDK/Client: CSS `@import`
|
||||
- Auth: None
|
||||
- Shields.io - GitHub badge images are generated in `src/lib/github/badges.ts` and rendered through `next/image` in `src/components/project/ProjectCard.tsx` and `src/components/project/GitHubTextStatsCard.tsx`.
|
||||
- Shields.io - GitHub badge URLs are generated in `src/lib/github/badges.ts` and rendered in `src/components/project/ProjectCard.tsx`, `src/components/project/GitHubTextStatsCard.tsx`, and `src/components/project/ProjectSidebar.tsx`.
|
||||
- SDK/Client: URL construction only
|
||||
- Auth: None
|
||||
- Evidence: `img.shields.io` is explicitly whitelisted in `next.config.js`.
|
||||
|
||||
**Content / Link Surfaces:**
|
||||
- GitHub - The app stores GitHub repository links on projects and builds GitHub badge and deep-link URLs in `src/lib/github/badges.ts`.
|
||||
- SDK/Client: None detected
|
||||
- Auth: None detected
|
||||
- Note: GitHub API calls are not detected in current code; integration is via stored URLs and Shields.io images.
|
||||
|
||||
## Data Storage
|
||||
|
||||
**Databases:**
|
||||
- PostgreSQL
|
||||
- Connection: `DATABASE_URL`
|
||||
- Client: Prisma via `@prisma/client` in `src/lib/prisma.ts`
|
||||
- Client: Prisma via `src/lib/prisma.ts` and `@prisma/client`
|
||||
- Schema: `prisma/schema.prisma`
|
||||
- Migrations: `prisma/migrations/*/migration.sql`
|
||||
- Usage: Queried from `src/hooks/useProjects.ts`, `src/app/api/projects/route.ts`, `src/app/api/tags/route.ts`, `src/app/api/signals/route.ts`, and webhook-style route handlers.
|
||||
- Connection hardening: `src/lib/prisma-url.ts` supports `PG_SSL_ROOT_CERT_B64`, `PG_SSL_IDENTITY_P12_B64`, `PG_SSL_IDENTITY_PASSWORD`, `PG_SSL_CERT_DIR`, and `PG_SSL_MODE`
|
||||
- Notes: `prisma/schema.prisma` stores a `vector` column on `Project.embedding`, and n8n docs state some workflows write directly to the database rather than calling repo routes
|
||||
|
||||
**File Storage:**
|
||||
- Local filesystem only
|
||||
- Evidence: No S3, Blob, Cloudinary, or similar storage SDK is declared in `package.json` or imported under `src/**/*`.
|
||||
- Evidence: No S3, Blob, Cloudinary, or object-storage SDK is declared in `package.json` or imported under `src/**/*`
|
||||
|
||||
**Caching:**
|
||||
- Next.js data cache via `unstable_cache`
|
||||
- Service: Built-in framework cache, not a separate external service
|
||||
- Implementation: `src/app/api/tags/route.ts` and `src/hooks/useProjects.ts`
|
||||
- Built-in Next.js data cache
|
||||
- Service: `unstable_cache` in `src/hooks/useHome.ts`, `src/hooks/useProjects.ts`, and `src/app/api/tags/route.ts`
|
||||
- Client: Framework cache, not an external provider
|
||||
- External cache service: None detected
|
||||
- Evidence: No Redis, Memcached, or similar client package is declared in `package.json`.
|
||||
|
||||
## Authentication & Identity
|
||||
|
||||
**Auth Provider:**
|
||||
- Custom shared-secret authentication for machine-to-machine routes
|
||||
- Implementation: `src/lib/auth.ts` compares a provided API key against `process.env.WEBHOOK_API_KEY` using `crypto.timingSafeEqual`.
|
||||
- Used by:
|
||||
- `src/app/api/webhook/signals/route.ts`
|
||||
- `src/app/api/tags/maintenance/route.ts`
|
||||
- `src/app/api/tags/reset-projects/route.ts`
|
||||
- Custom shared-secret auth for machine-to-machine routes
|
||||
- Implementation: `src/lib/auth.ts` uses `crypto.timingSafeEqual` against `WEBHOOK_API_KEY`
|
||||
- Used by: `src/app/api/webhook/signals/route.ts`, `src/app/api/tags/maintenance/route.ts`, and `src/app/api/tags/reset-projects/route.ts`
|
||||
- End-user authentication: Not detected
|
||||
- Evidence: No NextAuth, Clerk, Auth.js, Supabase Auth, OAuth, or session middleware is present in `package.json` or `src/**/*`.
|
||||
- Evidence: No session/auth provider package or auth middleware is committed in `package.json` or `src/**/*`
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
**Error Tracking:**
|
||||
- None detected
|
||||
- Evidence: No Sentry, Bugsnag, Datadog, or Rollbar package is declared in `package.json`.
|
||||
- Evidence: No Sentry, Datadog, Rollbar, Bugsnag, or OpenTelemetry package is declared in `package.json`
|
||||
|
||||
**Logs:**
|
||||
- Server logging uses `console.error` and `console.warn` in route handlers such as `src/app/api/search/ai/route.ts`, `src/app/api/webhook/signals/route.ts`, and `src/app/api/tags/route.ts`.
|
||||
- Frontend telemetry uses Vercel Analytics and Speed Insights in `src/app/VercelMetrics.tsx`.
|
||||
- Server logging uses `console.error` and `console.warn` in route handlers and server data code such as `src/app/api/search/ai/route.ts`, `src/app/api/webhook/signals/route.ts`, `src/app/api/tags/maintenance/route.ts`, `src/app/api/tags/reset-projects/route.ts`, and `src/hooks/useHome.ts`
|
||||
- Frontend telemetry uses Vercel Analytics and Speed Insights via `src/app/VercelMetrics.tsx`
|
||||
|
||||
## CI/CD & Deployment
|
||||
|
||||
**Hosting:**
|
||||
- Vercel
|
||||
- Evidence: `vercel.json` sets `"framework": "nextjs"`, `buildCommand`, `installCommand`, and region `hkg1`.
|
||||
- Evidence: `vercel.json` sets the `nextjs` framework, install/build commands, and region `hkg1`
|
||||
- Container deployment
|
||||
- Evidence: `Dockerfile`, `Dockerfile.runtime`, and `nixpacks.toml` define reproducible Node 22 builds and runtime startup
|
||||
|
||||
**CI Pipeline:**
|
||||
- None detected in repo
|
||||
- Evidence: No `.github/workflows/*`, GitLab CI file, CircleCI config, or other CI config file is present at repo root.
|
||||
- Not detected in repo
|
||||
- Evidence: No committed `.github/` workflow directory and no other CI config file are present at repo root
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
**Required env vars:**
|
||||
- `DATABASE_URL` - Required by Prisma datasource in `prisma/schema.prisma`.
|
||||
- `WEBHOOK_API_KEY` - Required for authenticated webhook-style POST endpoints in `src/lib/auth.ts`.
|
||||
- `N8N_AI_SEARCH_WEBHOOK` - Required by the outbound AI search proxy in `src/app/api/search/ai/route.ts`.
|
||||
- `NEXT_PUBLIC_SITE_URL` - Optional but used to generate canonical URLs in `src/app/robots.ts` and `src/app/sitemap.ts`; code falls back to `https://agentpark.ai`.
|
||||
- `VERCEL_ENV` - Read in `src/app/layout.tsx` to gate Vercel telemetry; expected when deployed on Vercel.
|
||||
- `.env.example` also includes `NEXT_INTL_DEFAULT_LOCALE` and `NEXT_INTL_SUPPORTED_LOCALES`, but current locale middleware and request config rely on hard-coded values in `src/middleware.ts` and `src/i18n/request.ts`.
|
||||
- `DATABASE_URL` - Prisma datasource in `prisma/schema.prisma`
|
||||
- `WEBHOOK_API_KEY` - Shared-secret validation in `src/lib/auth.ts`
|
||||
- `N8N_AI_SEARCH_WEBHOOK` - Outbound AI search proxy target in `src/app/api/search/ai/route.ts`
|
||||
- `NEXT_PUBLIC_SITE_URL` - Canonical URL base in `src/app/robots.ts` and `src/app/sitemap.ts`
|
||||
- `VERCEL_ENV` - Telemetry gating in `src/app/layout.tsx`
|
||||
- `PG_SSL_ROOT_CERT_B64`, `PG_SSL_IDENTITY_P12_B64`, `PG_SSL_IDENTITY_PASSWORD`, `PG_SSL_CERT_DIR`, `PG_SSL_MODE` - Optional Postgres SSL/mTLS parameters in `src/lib/prisma-url.ts`
|
||||
|
||||
**Secrets location:**
|
||||
- Local development secrets: `.env.local` and `.env` files are present in repo root; contents were not read.
|
||||
- Production secrets: Vercel environment variables are implied by `vercel.json` and `process.env.*` usage, but no separate secret manager config is committed.
|
||||
- Local development secrets are expected in `.env.local` or `.env`; contents were not read
|
||||
- Production secrets are expected in deployment settings for Vercel or container hosting
|
||||
- n8n runtime credentials, upstream API tokens, and discovery-service secrets are external to this repo and are only described contractually in `docs/integrations/n8n/*.md`
|
||||
|
||||
## Webhooks & Callbacks
|
||||
|
||||
**Incoming:**
|
||||
- `POST /api/webhook/signals` in `src/app/api/webhook/signals/route.ts`
|
||||
- Purpose: Ingests batched signal payloads into PostgreSQL via Prisma.
|
||||
- Auth: Shared secret in request body validated against `WEBHOOK_API_KEY`.
|
||||
- Purpose: Accept batched signal payloads from the signals aggregation workflow and upsert them into PostgreSQL
|
||||
- Auth: `WEBHOOK_API_KEY` in request body
|
||||
- `POST /api/tags/maintenance` in `src/app/api/tags/maintenance/route.ts`
|
||||
- Purpose: Applies tag updates/merges and revalidates project pages.
|
||||
- Auth: Shared secret in request body validated against `WEBHOOK_API_KEY`.
|
||||
- Purpose: Apply tag updates/merges and revalidate list pages
|
||||
- Auth: `WEBHOOK_API_KEY` in request body
|
||||
- `POST /api/tags/reset-projects` in `src/app/api/tags/reset-projects/route.ts`
|
||||
- Purpose: Resets project tag assignments by category and optionally revalidates pages.
|
||||
- Auth: Shared secret in request body validated against `WEBHOOK_API_KEY`.
|
||||
- Purpose: Bulk-reset project tags by taxonomy category and revalidate list/detail pages
|
||||
- Auth: `WEBHOOK_API_KEY` in request body
|
||||
|
||||
**Outgoing:**
|
||||
- n8n AI search webhook
|
||||
- Source: `src/app/api/search/ai/route.ts`
|
||||
- Method: `GET`
|
||||
- Target: URL from `N8N_AI_SEARCH_WEBHOOK`
|
||||
- Search engine / badge asset requests from the browser are not hard-coded beyond standard page navigation, Google Fonts CSS, Material Icons CSS, and Shields.io image URLs.
|
||||
- Browser-side external navigations and assets
|
||||
- Sources: `src/app/globals.css`, `src/lib/github/badges.ts`, `src/components/project/GitHubTextStatsCard.tsx`
|
||||
- Targets: `fonts.googleapis.com`, `img.shields.io`, and `github.com`
|
||||
- External-upstream discovery service calls
|
||||
- Source of truth: Documented in `docs/integrations/n8n/DATAFLOW.md` and `docs/integrations/n8n/workflows/03-project-ingestion-multi-source.md`
|
||||
- Status: Not implemented by this repo; treat as upstream integration boundary
|
||||
|
||||
---
|
||||
|
||||
*Integration audit: 2026-04-18*
|
||||
*Integration audit: 2026-04-20*
|
||||
|
||||
Reference in New Issue
Block a user