# N8N Context

Generated at: 2026-04-20T11:04:30.112Z

This file is generated from `docs/integrations/n8n/registry.json` plus repository scanning.
It exists so external n8n workflows become committed, reviewable context for AI agents and GSD.

## Workflow Inventory

## AI Search

- Status: `confirmed`
- ID: `ai-search`
- Purpose: Resolve semantic search candidates from n8n and hydrate them into project results.
- n8n workflow id: `F5cQ06DykBfpeyfqL-pd7`
- Export file: `not recorded`

### Entrypoints
- webhook: GET ai-search

### Repository Touchpoints
- src/app/api/search/ai/route.ts

### Environment
- N8N_AI_SEARCH_WEBHOOK

### Contracts
- Request fields: `desc`, `limit`, `page`, `offset`, `tags`, `domains`, `productForms`
- Response fields: `results[].id`, `results[].similarity`, `pagination.total`, `pagination.totalPages`, `pagination.hasMore`

### Schemas
- N8NSearchResponseSchema

### Related Systems
- Upstreams: RAG项目搜索, pgvector similarity search, SiliconFlow embeddings
- Downstreams: src/hooks/useProjects.ts#getProjectsByIds, POST /api/search/ai response

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: webhook path is `ai-search` and the workflow returns `results[].id` plus `similarity`.

## Signals Aggregation

- Status: `confirmed`
- ID: `signals-aggregation`
- Purpose: Aggregate multi-source discussion signals, filter them with AI, and ingest them into the repository signal store.
- n8n workflow id: `bAxNZKGq2ApUUiw9`
- Export file: `not recorded`

### Entrypoints
- schedule: multi-source discussion crawl

### Repository Touchpoints
- src/lib/auth.ts
- src/app/api/webhook/signals/route.ts
- src/app/api/signals/route.ts
- src/lib/validations.ts
- prisma/schema.prisma

### Environment
- WEBHOOK_API_KEY

### Contracts
- Request fields: `apiKey`, `signals[].source`, `signals[].sourceUrl`, `signals[].title`, `signals[].titleEn`, `signals[].summary`, `signals[].summaryEn`, `signals[].topic`, `signals[].topicEn`, `signals[].tags`, `signals[].sections`, `signals[].engagement`, `signals[].hotScore`, `signals[].isHot`, `signals[].publishedAt`, `signals[].isActive`
- Response fields: `success`, `processed`, `created`, `updated`, `failed`, `errors[].index`, `errors[].field`, `errors[].message`

### Schemas
- SignalWebhookPayloadSchema
- SignalIngestionInputSchema
- SignalQuerySchema

### Related Systems
- Upstreams: Hacker News, GitHub, arXiv, Reddit, Product Hunt, Hugging Face
- Downstreams: GET /api/signals, signals page feed, signal hotness computation

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow posts to `/api/webhook/signals` and also triggers external discovery dedupe/task creation. Workflow currently embeds a shared secret in HTTP body and should move to credentials/env.

## Project Tag Reset

- Status: `confirmed`
- ID: `tag-reset`
- Purpose: Reset selected project tags in bulk from n8n classification results.
- n8n workflow id: `8tIgBqLyWrBewJPs`
- Export file: `not recorded`

### Entrypoints
- manual: bulk tag reset

### Repository Touchpoints
- src/lib/auth.ts
- src/app/api/tags/reset-projects/route.ts
- src/lib/validations.ts
- prisma/schema.prisma

### Environment
- WEBHOOK_API_KEY

### Contracts
- Request fields: `apiKey`, `dryRun`, `replaceAllCategories`, `categories`, `projects[].projectSlug`, `projects[].selectedTagSlugsByCategory`
- Response fields: `success`, `result.dryRun`, `result.categories`, `result.updatedCount`, `result.failedCount`, `result.results[].projectSlug`, `result.results[].status`, `result.results[].details`

### Schemas
- ProjectTagResetRequestSchema

### Related Systems
- Upstreams: n8n tag classification
- Downstreams: project tag relations, project detail page revalidation, project list revalidation

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow reads `/api/tags` and `/api/projects`, then posts bulk updates into `/api/tags/reset-projects`. Workflow currently embeds a shared secret in HTTP body and should move to credentials/env.

## Project Ingestion (Multi-source)

- Status: `external-upstream`
- ID: `project-ingestion-multi-source`
- Purpose: Consume queued discovery tasks, enrich project metadata with AI/browser steps, and write final ingestion results back to Agent Park.
- n8n workflow id: `1Ig1CyVMsGJFaHOe`
- Export file: `not recorded`

### Entrypoints
- schedule: every 10 minutes

### Repository Touchpoints
- prisma/schema.prisma
- src/app/api/projects/route.ts
- src/app/api/projects/[slug]/route.ts

### Environment
- none

### Contracts
- Request fields: `task.status`, `task.sourceUrl`, `task.sourceType`
- Response fields: `project content`, `tag assignments`, `task completion status`

### Related Systems
- Upstreams: discovery task queue, browser/AI extraction, tag catalog
- Downstreams: project records visible in repository APIs, task completion callbacks, task failure callbacks

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow polls `/api/discovery/tasks`, marks tasks `IN_PROGRESS`, enriches candidates, then completes or fails tasks. The current repo does not contain `/api/discovery/*` handlers, so this is an upstream system dependency rather than a route implemented here.

## GitHub Star Refresh

- Status: `confirmed`
- ID: `github-star-refresh`
- Purpose: Refresh `projects.githubStars` and `projects.githubStarsUpdatedAt` directly from GitHub repository metadata.
- n8n workflow id: `ewx9Gs6cjrTXvwD0`
- Export file: `not recorded`

### Entrypoints
- schedule: daily at 04:00

### Repository Touchpoints
- prisma/schema.prisma
- src/app/api/search/ai/route.ts
- src/hooks/useProjects.ts

### Environment
- none

### Contracts
- Request fields: `projects.id`, `projects.slug`, `external_links.url(type=GITHUB)`
- Response fields: `projects.githubStars`, `projects.githubStarsUpdatedAt`

### Related Systems
- Upstreams: GitHub repository API, projects table, external_links table
- Downstreams: project ranking, star sorting, home ranking display

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow reads active project GitHub links from Postgres, fetches repository metadata from GitHub, then writes star counts directly back to Postgres. This bypasses repository API routes.

## Project Description Vectorization

- Status: `confirmed`
- ID: `project-description-vectorization`
- Purpose: Generate and persist project embeddings used by semantic search.
- n8n workflow id: `1AvejnM5n-WPApU1vFt9C`
- Export file: `not recorded`

### Entrypoints
- schedule: every 30 minutes

### Repository Touchpoints
- prisma/schema.prisma
- prisma/migrations/20260126000000_add_project_embedding/migration.sql
- src/app/api/search/ai/route.ts

### Environment
- none

### Contracts
- Request fields: `projects.id`, `projects.name`, `projects.nameEn`, `projects.description`, `projects.descriptionEn`, `projects.content`, `projects.contentEn`
- Response fields: `projects.embedding`, `projects.embeddingUpdatedAt`

### Related Systems
- Upstreams: SiliconFlow embeddings API, projects table
- Downstreams: RAG项目搜索, semantic search quality

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow selects active projects with null embeddings, generates `BAAI/bge-m3` vectors, and writes them directly into the `vector` column. This is a direct DB maintenance job, not a repository API route.

## GitHub Trending Discovery

- Status: `external-upstream`
- ID: `github-trending-discovery`
- Purpose: Scrape GitHub Trending, dedupe candidates, filter them with AI, and enqueue project discovery tasks.
- n8n workflow id: `hughGsWismCpk7jd`
- Export file: `not recorded`

### Entrypoints
- schedule: daily at 01:00

### Repository Touchpoints
- src/app/api/projects/route.ts
- src/app/api/projects/[slug]/route.ts

### Environment
- none

### Contracts
- Request fields: `GitHub trending repository URL`, `apiKey`, `tasks[].sourceUrl`, `tasks[].sourceType`
- Response fields: `dedupe shouldCreate`, `task creation result`

### Related Systems
- Upstreams: https://github.com/trending, AI keep/discard filter
- Downstreams: /api/discovery/check-duplicates, /api/discovery/tasks, project ingestion queue

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow scrapes GitHub Trending, filters candidates with an LLM, then posts queued tasks into discovery webhook endpoints. The current repo does not implement `/api/discovery/*`, so treat this as upstream data intake.

## Topic Discovery

- Status: `external-upstream`
- ID: `topic-discovery`
- Purpose: Search GitHub topics and keywords for agent/LLM engineering repos, dedupe them, and enqueue discovery tasks.
- n8n workflow id: `iw9vx9ih5Lt0Mobk`
- Export file: `not recorded`

### Entrypoints
- schedule: daily at 01:00

### Repository Touchpoints
- src/app/api/projects/route.ts
- src/app/api/projects/[slug]/route.ts

### Environment
- none

### Contracts
- Request fields: `GitHub search query`, `apiKey`, `tasks[].sourceUrl`, `tasks[].sourceType`
- Response fields: `dedupe shouldCreate`, `task creation result`, `low recall alert`

### Related Systems
- Upstreams: GitHub Search API, AI keep/discard filter, topic watchlist
- Downstreams: /api/discovery/check-duplicates, /api/discovery/tasks, project ingestion queue

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: workflow searches agent, infra, observability, evaluation, and MCP-related repositories, then posts accepted candidates into discovery webhooks. The current repo does not implement `/api/discovery/*`, so this is upstream context rather than in-repo routing.

## AI Chat Gateway

- Status: `adjacent`
- ID: `ai-chat-gateway`
- Purpose: Expose a chat-oriented webhook wrapper around `RAG项目搜索` and package search hits into chat blocks/citations.
- n8n workflow id: `Rncc22jmHEaYOG58`
- Export file: `not recorded`

### Entrypoints
- webhook: POST agent-park-chat

### Repository Touchpoints
- none

### Environment
- none

### Contracts
- Request fields: `requestId`, `sessionId`, `clientId`, `locale`, `mode`, `message`
- Response fields: `message.blocks`, `message.citations`, `message.meta.source`, `progress.stage`

### Related Systems
- Upstreams: RAG项目搜索, n8n webhook `ai-search`
- Downstreams: external chat clients, project detail URLs

### Ownership
- none

### Notes
- Confirmed against live n8n MCP: this workflow is related to Agent Park but does not call a repository route directly. It wraps the RAG webhook and formats citations pointing at project pages.

## Exported Workflow Files

- none

## Detected Repository Touchpoints

- `src/app/api/search/ai/route.ts` (39 matches)
  - L6: `const N8N_WEBHOOK_URL = process.env.N8N_AI_SEARCH_WEBHOOK!`
  - L8: `if (!N8N_WEBHOOK_URL) {`
  - L9: `throw new Error('N8N_AI_SEARCH_WEBHOOK environment variable is not set')`
  - L12: `// n8n 返回的搜索结果 Schema（统一格式）`
  - L13: `const N8NSearchResponseSchema = z.object({`

- `src/app/api/tags/maintenance/route.test.ts` (1 matches)
  - L65: `process.env.WEBHOOK_API_KEY = validApiKey;`

- `src/app/api/tags/reset-projects/route.test.ts` (1 matches)
  - L78: `process.env.WEBHOOK_API_KEY = validApiKey;`

- `src/app/api/webhook/signals/route.ts` (7 matches)
  - L13: `SignalWebhookPayloadSchema,`
  - L15: `type SignalWebhookPayload,`
  - L39: `const validationResult = SignalWebhookPayloadSchema.safeParse(body)`
  - L51: `const payload = validationResult.data as SignalWebhookPayload`
  - L184: `console.error(\`[Webhook Signals] Error at index ${i}:\`, error)`

- `src/hooks/useProjects.ts` (2 matches)
  - L563: `// n8n 返回的简化搜索结果类型`
  - L564: `export type N8NSearchResult = {`

- `src/lib/auth.ts` (1 matches)
  - L9: `expectedApiKey: string | undefined = process.env.WEBHOOK_API_KEY`

- `src/lib/validations.ts` (5 matches)
  - L60: `export const WebhookAuthSchema = z.object({`
  - L106: `export const SignalWebhookPayloadSchema = WebhookAuthSchema.extend({`
  - L147: `export type SignalWebhookPayload = z.infer<typeof SignalWebhookPayloadSchema>;`

- `src/messages/en.json` (2 matches)
  - L220: `"contractTitle": "n8n Field Contract",`
  - L221: `"contractDescription": "Every visual element maps to fields that can be produced from n8n workflow outputs.",`

- `src/messages/zh.json` (2 matches)
  - L220: `"contractTitle": "n8n 字段契约",`
  - L221: `"contractDescription": "页面元素都对应可由 n8n 输出的字段，避免出现无法供数的设计组件。",`

## Environment Variables

- N8N_AI_SEARCH_WEBHOOK
- WEBHOOK_API_KEY

## Gaps To Fill

- All detected repo touchpoints are mapped to documented workflows.

## Maintenance Rules

- When an n8n workflow changes, update `docs/integrations/n8n/registry.json` in the same PR.
- If possible, export the workflow JSON into `docs/integrations/n8n/exports/` and reference it from the registry.
- Re-run `pnpm n8n:context` after every workflow, contract, or route change.
- Treat this file as generated output; edit the registry instead of editing this file directly.