agent-park/docs/integrations/n8n

n8n Context

This directory is the repository-side source of truth for n8n workflows that feed or depend on this app.

Why this exists:

• n8n workflows live outside the application repository, so AI agents only see partial context from code scanning.
• The fix is to commit workflow metadata, contracts, and touchpoint mapping into the repo.
• Generated context is mirrored into .planning/codebase/N8N-CONTEXT.md so GSD can read it without guessing.

Key files:

• registry.json: editable workflow registry and contract source of truth
• CONTEXT.generated.md: generated inventory and repo touchpoint report
• DATAFLOW.md: end-to-end source to UI dataflow
• workflows/README.md: per-workflow documentation index
• N8N-CONTEXT.md: GSD-facing generated mirror
• N8N-DATAFLOW.md: GSD-facing dataflow overview

Expected workflow:

1. Add or update an entry in registry.json for every n8n workflow that touches this repository.
2. If possible, export the workflow JSON from n8n into docs/integrations/n8n/exports/.
3. Run pnpm n8n:context.
4. Commit the registry change together with the generated context file.
5. If runtime behavior changed, also update DATAFLOW.md and the affected workflows/*.md.

Rules:

• registry.json is the editable source of truth.
• CONTEXT.generated.md is generated output.
• DATAFLOW.md is the cross-workflow end-to-end view.
• workflows/*.md are the single-workflow execution notes.
• Keep repository file paths repo-relative, for example src/app/api/search/ai/route.ts.
• Record request and response fields at the contract level, not only business descriptions.
• If a repo touchpoint is not linked to any workflow, the generated file will report it as a gap.

Minimum fields for each workflow entry:

• id
• status
• name
• purpose
• n8n.entrypoints
• repository.consumers
• repository.env
• contracts.requestFields
• contracts.responseFields

Recommended:

• n8n.workflowId
• n8n.exportFile
• repository.schemas
• upstreams
• downstreams
• owners
• notes