How to read an architecture page

Goal

By the end you will be able to open any page under /arquitecturas/, know what each tab shows, and replay a flow to see what the system does in one concrete case. The worked example is the claude-kit page: 12 containers, 18 calls and 4 flows.

Why

A box-and-arrow diagram tells you what is connected to what, not in which order or why. The reader rebuilds the story from memory and usually gets it wrong. Living-architecture pages fix that with two ideas: a C4-style container diagram (every box is something deployed on its own) and flows that animate over that same diagram. Every drawn call maps to code you can point at, so what you see is what the project does, not what someone wished it did.

Steps

1. Open a page. Go to /arquitecturas/ and pick a card. Each card shows how many containers, calls and flows the project has and which machines it runs on. Start with a small one.
2. Start with the containers tab (C4). Actors sit on the left; stores and external services on the right. Colour tells you whose piece it is: the project’s own, own but from another repository, or external. A box with a dashed border exists outside the project.
3. Click a box. Its card opens: the responsibility, the technology, and details such as the machine it runs on, its inputs and its outputs. In claude-kit, the status-line box says it receives the session JSON on stdin and returns text.
4. Read the arrows. Each line is a call with a label: protocol and payload (for example git pull --ff-only). A dashed line marks an adapter chosen by configuration.
5. Replay a flow. Above the diagram are the “reproducir flujo” (replay flow) buttons, one per use case. Press one and the call of each step lights up while a packet travels from origin to target. The numbered steps appear on the right; the active one matches the lit call.
6. Tell steps, replies and notes apart. In the sequences tab the same flow is drawn as a UML diagram. A solid arrow with its label is the call. A dashed arrow with no label is the reply (target back to origin). A step that happens inside a single box shows as a loop on its lifeline, and that box pulses on the C4. An amber note spans several lifelines and highlights the boxes involved. Numbering skips notes.
7. Check the remaining tabs. They exist only when they add something: states (a state machine with the happy path, and error transitions drawn red and dashed), data (entity-relationship or folder structure, plus lineage when the project has it), deployment, and decisions with the discarded alternative. A missing tab means the project has no such aspect, not that someone forgot it.
8. Try it on your phone. Below 600 px wide, sequences stop being a diagram and become a vertical numbered list in the form origin → target: text. The same player lights it up step by step.