mzaxd/agent-park
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
68d4f09b7220612e109491c0b52261b09e7d31ab
agent-park/.planning/codebase/INTEGRATIONS.md
T
mzaxd ab3f8fecc3 docs: refresh codebase map
2026-04-20 18:59:15 +08:00

9.2 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink