NOit Documenting Data Flow

STAR diagram pieces → interactive viewer + overview
By NOit — Architecture documentation that stays in sync.

What It Does

┌─────────────────────────────────────────────────────────────────┐
│  YOU WRITE THIS (once per function)                            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ docs/architecture/diagrams/01-api-gateway.md              │   │
│  │ ```mermaid                                                │   │
│  │ graph LR                                                  │   │
│  │   hub["⚙️ handle_request()"]:::hub                        │   │
│  │   in1["📥 HTTP Request"]:::input                          │   │
│  │   dep1["🤖 Auth Service"]:::dep                           │   │
│  │   out1["💾 Response + Logs"]:::output                     │   │
│  │   in1 --> hub --> dep1 ==> out1                           │   │
│  │ ```                                                       │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  GENERATOR CREATES THIS (automatically)                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ docs/architecture_diagrams.html  ← Interactive viewer    │   │
│  │ docs/architecture/OVERVIEW.md      ← High-level index    │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Source of truth = Markdown pieces. Never hand-edit the HTML.

Features

Feature	Description
🎯 STAR Pattern	Hub-and-spoke: function = center, inputs/deps/outputs = spokes
🌙 Dark Theme	Consistent palette across MkDocs + generated viewer
🔍 Interactive	Pan, zoom, fullscreen, fit-to-screen on every diagram
📱 Responsive	Works on mobile, tablets, desktop
🏷️ Grouped Nav	Filter by Infra / Ops / Sequences (configurable)
🤖 MCP Server	AI agents can create/update diagrams via tools
💻 VS Code Extension	Sidebar tree to browse and toggle active pieces for the current chat
📦 Zero Config	Drop into any MkDocs Material project
🎨 Every Mermaid Interactive	All mermaid fences get pan/zoom automatically

Quick Start

# Install
pip install noit-documenting-data-flow

# Or with MkDocs for full docs stack
pip install "noit-documenting-data-flow[docs]"

# Initialize in your project
noit-diagram-rollup init

# Add your first diagram piece
cp docs/architecture/diagrams/00-template.md docs/architecture/diagrams/01-my-api.md
# Edit 01-my-api.md with your function's data flow

# Generate the viewer
noit-diagram-rollup build --write

# Serve docs
mkdocs serve
# Open http://127.0.0.1:8000/architecture_diagrams.html

MCP Server (for AI Agents)

Run the MCP server to let AI agents manage your diagrams:

# Stdio transport (for Claude Code, etc.)
noit-mcp-server

# Or HTTP transport
noit-mcp-server --transport http --port 8765

Available Tools:

Tool	Description
create_diagram_piece	Create a new STAR diagram piece from template
update_diagram_piece	Update an existing piece
list_diagram_pieces	List all pieces with metadata
build_viewer	Generate the interactive HTML viewer
get_diagram_piece	Read a piece's content

VS Code Extension

A companion extension lives in vscode-extension/ and gives the editor a sidebar tree of all your STAR pieces, grouped by infra / ops / seq. Each piece has a checkbox; toggling it writes the path to .claude/diagrams-active.md, a hand-editable Markdown sidecar. A single command — NOit: Inject Active Diagrams into Chat — pastes @path lines for the active set into the prompt, so the agent sees exactly the pieces you marked.

The sidecar is the source of truth, not the tree: the agent can @-reference .claude/diagrams-active.md directly even if the extension isn't running. See vscode-extension/README.md for setup, configuration, and the file layout.

Project Structure (after init)

your-project/
├── mkdocs.yml                    # Add: extra_javascript/css for interactive mermaid
├── docs/
│   ├── architecture_diagrams.html    # GENERATED - interactive viewer
│   ├── architecture/
│   │   ├── diagrams/
│   │   │   ├── .pages                    # Nav order (awesome-pages)
│   │   │   ├── rollup.manifest.yml       # Groups + badges
│   │   │   ├── 00-template.md            # STAR template (copy this)
│   │   │   ├── 01-your-function.md       # Your pieces go here
│   │   │   └── mermaid-style.md          # Dark palette reference
│   │   └── OVERVIEW.md                   # GENERATED - high-level index
│   ├── javascripts/
│   │   └── mermaid-interactive.js        # Makes ALL mermaid fences interactive
│   └── stylesheets/
│       └── mermaid-interactive.css       # Dark theme for interactive diagrams
├── scripts/
│   └── build_diagram_rollup.py           # Generator (also via CLI)
├── vscode-extension/                     # Optional: sidebar tree for active pieces
└── .claude/
    ├── diagrams-active.md                # Active set (managed by extension, hand-editable)
    └── skills/
        └── documenting-data-flow/
            └── SKILL.md                  # Skill definition for agents

STAR Diagram Template

graph LR
    %% ── STAR hub: the ONE function this piece documents ──
    hub["⚙️ FUNCTION_NAME<br/>src/path/to/module.py"]:::hub

    %% ── Spoke: inputs (data the function reads) ──
    subgraph In["📥 Inputs"]
        in1["INPUT_SOURCE_1<br/>where it comes from"]:::input
        in2["INPUT_SOURCE_2"]:::input
    end

    %% ── Spoke: dependencies (services / models it calls) ──
    subgraph Deps["🤖 Dependencies"]
        dep1["LLM / API / Cache"]:::dep
        svc1["EXTERNAL_SERVICE"]:::extSvc
    end

    %% ── Spoke: outputs (data it writes / emits) ──
    subgraph Out["💾 Outputs"]
        out1["OUTPUT_SINK<br/>store / snapshot / preview"]:::output
    end

    %% ── Streaming edges: in → hub → out ──
    in1 -->|"what flows"| hub
    in2 --> hub
    hub <-->|"read / write"| dep1
    hub -->|"query"| svc1
    hub ==>|"result"| out1

    classDef hub      fill:#4A148C,stroke:#CE93D8,color:#F3E5F9,stroke-width:3px
    classDef input    fill:#37474F,stroke:#78909C,color:#CFD8DC,stroke-width:1px
    classDef dep      fill:#0D47A1,stroke:#42A5F5,color:#BBDEFB,stroke-width:1px
    classDef extSvc   fill:#E65100,stroke:#FFB74D,color:#FFF3E0,stroke-width:2px
    classDef output   fill:#1B5E20,stroke:#66BB6A,color:#C8E6C9,stroke-width:2px

Rules:

• One function = one hub = one piece (.md file)
• Use <br/> for line breaks (never \n)
• Use edge vocab: --> direct, ==> pipeline, -.-> async/optional, <--> bidirectional
• Register in .pages (nav order) and rollup.manifest.yml (group + badge)

MkDocs Integration

Add to your mkdocs.yml:

extra_javascript:
  - javascripts/mermaid-interactive.js
extra_css:
  - stylesheets/mermaid-interactive.css

plugins:
  - awesome-pages          # enables .pages nav
  - roamlinks              # enables [[wikilinks]]

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

CLI Reference

noit-diagram-rollup --help

Commands:
  init              Initialize diagram structure in current project
  build             Build viewer + overview (dry-run by default)
  validate          Validate all pieces have valid mermaid + required fields

Options:
  --diagrams-dir PATH     Diagrams folder (default: docs/architecture/diagrams)
  --manifest PATH         Manifest file (default: <diagrams-dir>/rollup.manifest.yml)
  --out-html PATH         Output HTML (default: docs/architecture_diagrams.generated.html)
  --out-overview PATH     Output overview (default: docs/architecture/diagrams/OVERVIEW.generated.md)
  --write                 Write to real paths (default: dry-run to temp dir)
  --template PATH         Viewer template (default: built-in dark template)

MCP Tools Reference

{
  "create_diagram_piece": {
    "slug": "my-api-handler",
    "title": "API Request Handler",
    "function_path": "src/api/handler.py",
    "group": "ops",
    "inputs": [{"id": "req", "label": "HTTP Request", "description": "JSON + headers"}],
    "dependencies": [{"id": "auth", "label": "Auth Service", "type": "extSvc"}],
    "outputs": [{"id": "resp", "label": "HTTP Response", "description": "JSON + status"}]
  }
}

Groups: infra (badge: infra), ops (badge: ops), seq (badge: seq)

Configuration

Create noit-diagram-rollup.yaml in project root:

diagrams_dir: "docs/architecture/diagrams"
manifest: "rollup.manifest.yml"
title: "My Project Architecture Diagrams"
subtitle: "Generated from STAR pieces"
groups:
  - id: "infra"
    label: "Infrastructure"
    badge: "infra"
  - id: "ops"
    label: "Operations"
    badge: "ops"
  - id: "seq"
    label: "Sequences"
    badge: "seq"

Contributing

git clone https://github.com/noit/noit-documenting-data-flow
cd noit-documenting-data-flow
pip install -e ".[dev]"
pytest tests/

License

MIT — © 2024 NOit

---

Built by NOit — Making architecture documentation effortless since 2024.
🌐 noit2.com | 📧 az@zagent.live