Arch Flow

Arch flow documentation

Quick start

When producing architecture or flow docs:

1. Output: Create arch-flow.md beside the feature (same directory as the code being documented) unless the user specifies another path.
2. Content: Pseudocode for queries and control flow; ASCII boxes for flows per Format rules below.
3. Structure: Choose sections from Section structure that fit the feature; use Data flow step template for per-step flows.
4. Before finishing: Apply Checklist before completing.
5. Optional — FigJam diagram: If the user asks for a visual diagram (or says "and create a FigJam diagram"), follow Optional FigJam diagram below after step 4.

Installation (humans)

Single paste-in command and plain steps: README.md.

Format rules

1. Pseudocode Only — No Raw SQL or Code

Queries: Describe in pseudocode, not exact SQL.

# Good
query: sessions joined with events
filter: session.status = active
        session.created_at >= cutoff
        session.start_date > now
returns: session + event metadata per row

# Bad
SELECT s.id, s.event_id FROM sessions s INNER JOIN events e ...

Logic: Use descriptive pseudocode, not language-specific syntax.

# Good
for each (user_id, event_id) in batch:
  lookup user, event_data, sessions, org_data
  if any missing: skip
  build email template
  send email
  wait 100ms

# Bad
for (const { user_id, event_id } of batch) {
  await wait_ms(INTER_EMAIL_DELAY_MS);
}

2. ASCII Box Diagrams

Use ASCII box characters for flow diagrams.

Alignment rules (critical — ensures │ and corners ┌┐└┘ line up):

1. Fixed line width per box: Every line in a box must have the same total character count. Pick a width (e.g. 67 chars) and use it for all lines in that box.
2. Content padding: Between │ and │, pad content with spaces so the inner content is exactly (width - 2) characters. Left-pad, right-pad, or center as needed.
3. Spaces only: Use spaces for padding — no tabs.
4. Consistent width across connected boxes: Top/bottom lines (┌─┐, └─┘) must match the content lines in length.
5. Corner columns: ┌ and └ share the same column; ┐ and ┘ share the same column. The horizontal run between each left/right pair is the same length on every edge line (no ragged ┐/┘ shifted in or out). For split bottoms like └───┬───┘, the ┌/└ and ┐/┘ columns still match the full box width.

Example (67-char lines; inner content = 65 chars):

┌─────────────────────────────────────────────────────────────────┐
│                         Vercel Cron                             │
│                    (Daily at 01:00 UTC)                         │
└─────────────────┬───────────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                    route.ts (GET Handler)                       │
│  • Validate CRON_SECRET                                         │
│  • Call business logic                                          │
└─────────────────┬───────────────────────────────────────────────┘

Quick check: Select a box — every line from ┌ to └ should have identical length. The │ on the left and right must align vertically; ┌/└ and ┐/┘ must sit in the same columns on top and bottom so the rectangle closes cleanly.

Characters: ┌ ─ ┐ │ └ ┘ ┬ ┴ ├ ┤ ┼ ▼

3. Section Structure

Include these sections as relevant to the feature:

Data Flow Step Template

For each logical step in the flow:

┌─────────────────────────────────────────────────────────┐
│  logic.ts: function_name(inputs)                        │
└───────────────────┬─────────────────────────────────────┘
                    │
                    │ Brief description
                    ▼
┌─────────────────────────────────────────────────────────┐
│  query: table_name (or "in-memory aggregation")         │
│  filter: condition1, condition2                         │
│  returns: description of result shape                   │
└───────────────────┬─────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────┐
│  Returns: Type[] or Map<key, value>                     │
│  (optional: example structure in pseudocode)            │
└─────────────────────────────────────────────────────────┘

Checklist Before Completing

• No raw SQL (SELECT, UPDATE, INSERT, etc.)
• No language-specific code (await, const, =>, etc.)
• Queries described as: query:, filter:, returns:
• Logic described as: for each, if, add to, wait Nms
• ASCII box diagrams use ┌─┐│└┘┬┴├┤▼
• Box alignment: every line in a box has same character count; │ align vertically; ┌┐└┘ share left/right columns
• Sections match feature type (cron vs API vs generic)
• arch-flow.md exists at the chosen path with the full doc content
• If FigJam was requested: diagram link added under Visual diagram in arch-flow.md

Optional FigJam diagram

Turn the architecture flow into an editable FigJam board. Optional — only when the user explicitly asks (e.g. "create a FigJam diagram", "visual diagram in FigJam"). Do not block finishing the markdown doc on this step.

Prerequisites

• Figma plugin enabled in Cursor (generate_diagram MCP tool must be available).
• If the tool is missing, finish the markdown doc and tell the user to enable the Figma plugin, then re-run with the existing arch-flow.md.

Pick the reference file

Read the matching reference before writing Mermaid:

Workflow

1. Finish arch-flow.md first — the markdown is the source of truth.
2. Read the reference file from the table above.
3. Translate the relevant section(s) into Mermaid. Node labels must match the ASCII boxes and pseudocode in the doc.
4. Call generate_diagram with name and mermaidSyntax. For architecture diagrams, also pass useArchitectureLayoutCode: "FIGMA_DIAGRAM_2026". Do not call create_new_file first.
5. Add a Visual diagram section to arch-flow.md:

## Visual diagram

Editable FigJam version of this flow: [Open in FigJam](https://figma.com/board/...)

6. Share the link in chat. On iterations, reuse the same file via fileKey from the FigJam URL.