doc-architecture-data-flow

Packet · {{ repo }} · architecture/data-flow.md

1. Objective

Produce {{ docs_root }}/architecture/data-flow.md: a walk of the top 3 processes in {{ repo }}, each rendered as numbered steps plus one Mermaid sequenceDiagram. Every step cites `path:LOC` for the function that advances the flow.

2. Scope

• Create: {{ docs_root }}/architecture/data-flow.md
• Do not touch: any other file under {{ docs_root }}/, any source file in the repo, .context.md, .prefetch.md, or any .packets/*.md other than this one.

3. Input specification

Source	Read how	Cache state
Shared context	Read {{ context_path }}	always first
Prefetch ledger	Read {{ prefetch_path }}	always first
Top processes	{{ context_path }} § Top processes	cached
Process entry points	{{ prefetch_path }} § entry points or mcp__codehub__sql({query: "SELECT p.name, n.name AS entry_name, n.file_path, n.start_line FROM nodes p JOIN nodes n ON p.entry_point_id = n.id WHERE p.kind='Process'"})	cached if digest present
Symbol neighborhoods along each flow	mcp__codehub__context({symbol: <id>})	mid-run (only if cache miss)
Query grounding for ambiguous steps	mcp__codehub__query({text: "<concept>", limit: 10})	mid-run (only if cache miss)
Source spans for step citations	Read <file> over start_line..start_line+20	mid-run

4. Process

1. Read {{ context_path }} and Read {{ prefetch_path }}. Lock the ordered list of top processes; pick the top 3.
2. For each selected process, pull the entry point from .prefetch.md § entry points. If absent, call the sql query in the input spec and cache the digest in this packet's Work log.
3. For each flow, walk from the entry point outward using context({symbol: <entry>}) (reuse cached digest if present). Record the ordered call chain: caller → callee → downstream participant. Cap at 8 steps per flow.
4. Resolve each participant to a logical actor (CLI, MCP server, Analysis, Storage, etc.) by cross-referencing its file path against .context.md § Top communities. Use the community inferred_label as the participant name in the Mermaid diagram.
5. For every step, Read the source span at path:start_line-start_line+20 to confirm the function exists and extract the one-line description. Do not paraphrase beyond that.
6. Draft the H2 block per flow: ## Flow N: <process-name>, followed by numbered steps (each citing `path:LOC`), then a fenced ```mermaid block containing one sequenceDiagram.
7. Write {{ docs_root }}/architecture/data-flow.md with H1 = {{ repo }} · Data flow, at most 3 ## Flow N: H2 sections.