The two diagrams a design doc needs: C4 context and container

The win for today: two diagrams in the DocuDex design doc — a system context diagram and a container diagram — in Excalidraw, each titled, each line labelled with what flows and how. About thirty-five minutes. C4 is notation-independent, so the tool is yours; export each drawing as SVG with "embed scene" on, so the picture is also the editable source, and commit it beside the design doc so it changes when the doc does. The context diagram in section 3 is given as Mermaid text only so it fits in a lesson — read it as a list of boxes and lines, then draw it.

What to do (read this first)

1. Draw the context diagram: DocuDex as one box; every person and every external system it touches; one labelled line per interaction. Section 3 gives you this one drawn.
2. Draw the container diagram: open the DocuDex box; one box per thing that runs or stores data; labelled lines with the technology. Section 4 has the prompts.
3. Give each a title, a one-line legend, and run the checklist.
4. Export both as SVG (embed scene on) beside the design doc and embed them: context under Context and scope, container at the top of Design. Update the fetch step while you are there — after the POC it is "module cache + go/doc", not a downloader.

1. C4 in five minutes

Simon Brown's C4 model is four zoom levels for the same system. System context: the system as one box, with the people and other systems around it. Container: "something that needs to be running" — a CLI process, a web server, a database file — not a Docker container specifically. Component: the building blocks inside one container. Code: classes and functions. The site says most teams need the first three; this course says a design doc needs the first two, and the component level only when a single container's insides are the thing being decided.

C4 is "notation independent", but it asks three things of any diagram: titled diagrams, legends, and labelled lines with direction and technology. Those three are the whole difference between a diagram that answers questions and a picture of boxes. Ubl's Design Docs at Google lists a system-context diagram among the supporting elements a design doc may include — may, when it helps a reader; not as a section.

2. Which level is it? (5 min)

DocuDex things. Sort each one.

3. The context diagram, specified (5 min)

Here is DocuDex at the context level as your design doc and POC describe it today, written as Mermaid so the boxes and lines are unambiguous. Redraw it in Excalidraw. Read it as a claim about the design; if a box or line is wrong, the doc is wrong too.

---
title: DocuDex — system context
---
flowchart LR
    dev([Developer])
    agent([Coding agent])
    modcache[(Go module cache\nGOMODCACHE)]
    gomod[/go.mod\nin the repo/]
    vcs[(Version control\ndocudex.toml)]
    docudex[DocuDex\nCLI + local web UI]
 
    dev -- "runs init / add / sync / serve\n(shell)" --> docudex
    agent -- "runs lookup, reads Markdown\n(shell, files)" --> docudex
    docudex -- "reads module sources\n(filesystem)" --> modcache
    docudex -- "reads dependency versions\n(file)" --> gomod
    docudex -- "reads and writes manifest\n(file)" --> vcs
    docudex -- "serves docs\n(HTTP, localhost)" --> dev

Legend: rounded boxes are people or agents; cylinders are stores DocuDex does not own; the rectangle is the system. Lines read "does what, over what". In Excalidraw, keep the same three shapes and put this legend as a text block in the corner.

Three things to notice. Every line has a verb and a technology — "reads module sources (filesystem)", not an arrow. There is no pkg.go.dev and no hosted service, because the design has neither; the diagram is only as good as its agreement with the text. And the agent is a user, drawn like one, which is the MVP's whole pitch in one box.

4. The container diagram, yours (15 min)

Open the DocuDex box. Draw one box per thing that runs or stores data, and nothing that doesn't. From your design doc and ADRs the containers are: the CLI process, the local HTTP server and web UI (same binary? say so), the Markdown docset on disk, the SQLite FTS5 index, and docudex.toml. The people and external systems from the context diagram stay at the edges.

For every line answer: who initiates it, what flows, over what? The ones worth getting right, because each encodes a decision you have already made:

• Markdown → SQLite: "rebuilt by sync" (ADR 0001: Markdown is the source of truth, SQLite is a cache).
• go.mod → docudex.toml: "derived by init/add; drift warned by sync" (ADR 0002).
• Module cache → Markdown: "go/doc over module sources" (the POC).
• Agent → Markdown: "reads files directly" and Agent → CLI: "lookup" — both paths, since the design keeps both.
• Web UI → SQLite: "full-text search (FTS5)"; Web UI → Markdown: "renders".

Title it, add a legend line, and check it against the design doc's non-goals: if there is a box for anything on that list, delete it.

5. Retrieval (2 min)

One of these is from lesson 5.

Read next

The C4 model site, the System context and Container pages only — ten minutes. Ignore the tooling section; Excalidraw is enough for a design doc.