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

# External Integrations

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

## 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`.
  - 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.

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

**File Storage:**
- Local filesystem only
  - Evidence: No S3, Blob, Cloudinary, or similar 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`
- 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`
- End-user authentication: Not detected
  - Evidence: No NextAuth, Clerk, Auth.js, Supabase Auth, OAuth, or session middleware is present in `package.json` or `src/**/*`.

## Monitoring & Observability

**Error Tracking:**
- None detected
  - Evidence: No Sentry, Bugsnag, Datadog, or Rollbar 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`.

## CI/CD & Deployment

**Hosting:**
- Vercel
  - Evidence: `vercel.json` sets `"framework": "nextjs"`, `buildCommand`, `installCommand`, and region `hkg1`.

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

## 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`.

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

## 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`.
- `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`.
- `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`.

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

---

*Integration audit: 2026-04-18*