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