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

# External Integrations

**Analysis Date:** 2026-04-20

## APIs & External Services

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

**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: 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: 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 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

## Data Storage

**Databases:**
- PostgreSQL
  - Connection: `DATABASE_URL`
  - Client: Prisma via `src/lib/prisma.ts` and `@prisma/client`
  - Schema: `prisma/schema.prisma`
  - 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 object-storage SDK is declared in `package.json` or imported under `src/**/*`

**Caching:**
- 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

## Authentication & Identity

**Auth Provider:**
- 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 session/auth provider package or auth middleware is committed in `package.json` or `src/**/*`

## Monitoring & Observability

**Error Tracking:**
- None detected
  - 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 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 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:**
- 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` - 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 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: 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: 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: 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`
- 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-20*