Copy this skeleton into your tutorial series as doc 00 (the very first one). Replace every
<...>placeholder. Keep the section order — it is what makes the doc work as a global map.Reminder: verify every
file:function:lineagainst the real source before you write it.Diagrams below use the
graphvizdrawing skill (invoke it to render the```dotblocks).
# ⓪ The Journey of One <ACTION> (read me first)
> This is the **lead doc** of the whole series — read it first.
>
> The per-file deep-dives (01, 02, …) are a microscope on each file. But the thing
> beginners get lost on is not one confusing line — it's *"how do these files connect?
> When I do X, what happens, in what order?"*
>
> This doc answers exactly that: we follow **one action** — `<the user action, e.g.
> "user types 'move forward 1m'">` — and watch it cross the whole system to its final
> effect. **Every hop is tagged with file · function · line and links to its deep-dive.**
## How to use this doc
- **First read:** go top to bottom; don't open every link. Build the mental image of
"one action flows through N stations."
- **While reading 01–NN:** whenever a deep-dive feels like "all trees, no forest," come
back here and find that file's station to see its upstream/downstream.
## The big picture
<one-paragraph framing: the two "worlds" the action crosses, e.g. human/natural-language
world vs machine/binary world, and that this system is the translator between them.>
```dot
digraph journey {
rankdir=TB;
node [shape=box, style="rounded,filled", fontname="sans-serif"];
a [label="<actor>\n<input>"];
b [label="<stage 2>\nfile·function"];
c [label="<final effect>"];
a -> b -> c;
}Notice the data changes SHAPE along the way (often the single most clarifying table):
| Stage | What the information looks like |
|---|---|
| You sent | <e.g. a sentence of natural language> |
| After | <e.g. a tool call: name + params> |
| Inside | <e.g. a plain object {…}> |
| On the wire | <e.g. a JSON string / bytes> |
| After | <e.g. native binary message> |
📍 <file> · <function> · lines <a–b>
<short real snippet>
- <plain-language explanation + an analogy>
- 🔍 Deep-dive: doc NN ·
📍 <file> · <function> · lines <a–b>
<explain. Add a「Syntax mini-lesson」if a new construct shows up.>
- 🔍 Deep-dive: doc NN ·
<… repeat one Station per hop, in execution order …>
<the final hop(s) that leave your codebase; what shape change happens here.>
<for read/request actions: how the response is awaited and routed back —
e.g. a race between a callback resolving and a timeout, then a dispatcher
that routes inbound messages by id/type back to the right waiter.>
📍 <file> · <function> · lines <a–b>
digraph dispatch {
rankdir=LR;
node [shape=box, style="rounded,filled"];
inbound [label="inbound message\nparse → look at type"];
sw [label="switch(type)", shape=diamond];
x [label="case A → route to subscribers"];
y [label="case B → resolve pending by id"];
inbound -> sw; sw -> x; sw -> y;
}| # | File | Function | Lines | One line | Deep-dive |
|---|---|---|---|---|---|
| 0 | <file> |
<fn> |
a–b | <…> | NN |
| 1 | <file> |
<fn> |
a–b | <…> | NN |
| … |
- <pattern, e.g. layering / one interface, swappable implementations> —
- <pattern, e.g. data changes shape, meaning preserved> — <…>
- <pattern, e.g. request/response via id-pairing> — <…>
- Start the deep-dives: → doc 01 · , then 01→NN in order.
- This main-line stays here — whenever you lose the forest, come back to the quick-ref.
Next: doc 01 · →
---
## Tips for filling this in
- **Pick the action carefully.** It should pass through the spine of the system (entry → core logic → output), not a side feature.
- **One Station per hop, in execution order.** If two things happen "before the action" (startup wiring, context setup), give them low-numbered stations.
- **Shape-change table earns its keep.** If your system transforms data across layers, this table alone often makes the whole architecture click.
- **Links can point forward to not-yet-written docs.** That's expected — you write this doc first.