# Arch Flow

> Drafts architecture documentation with ASCII box diagrams and pseudocode (no raw SQL or implementation syntax). Optionally creates an editable FigJam diagram via the Figma plugin when requested. Use when the user asks for architecture diagrams, flow documentation, arch-flow.md, FigJam architecture flows, or documents cron, API, or feature flows.

- Skill: `hferello/arch-flow` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add hferello/arch-flow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hferello/arch-flow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: hferello (https://skillmd.com/u/hferello)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hferello/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](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:

| Section                         | Purpose                                          |
| ------------------------------- | ------------------------------------------------ |
| **High-Level Flow**             | Entry point → route → logic → dependencies       |
| **Data Flow**                   | Per-step flow: input → query/filter → output     |
| **Component Architecture**      | HTTP layer, business logic, sub-functions        |
| **Security Architecture**       | Auth, service role, external services            |
| **Early Exit Paths**            | Decision tree for early returns                  |
| **Error Handling Flow**         | Success vs failure, per-item vs full failure     |
| **Database Tables Used**        | Tables and key columns (no raw SQL)              |
| **Performance Characteristics** | Query count, batching, timing                    |
| **Time Window Configuration**   | Schedule, date ranges, cutoff logic              |
| **Key Differences**             | Comparison to related features (if applicable)   |
| **Template Structure**          | Props, subject, content (for email/UI templates) |

## 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:

| What you are diagramming | Read |
| ------------------------ | ---- |
| Step-by-step data flow, error paths, early exits | [references/figjam-flowchart.md](references/figjam-flowchart.md) |
| Services, routes, datastores, queues, external APIs | [references/figjam-architecture.md](references/figjam-architecture.md) |

### 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`:

```markdown
## 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.