How to
How to document a microservices architecture with AI
One sentence to your agent, one Markdown file back: a context view, a container map and the request path, as typed blocks that chiltepin check verifies and the renderer draws. The agent never places a box; it names services and edges.
1. Give the agent the request
Install the skill once — npx skills add jdiejim/chiltepin -g — then say what the reader needs, in plain words. Do not name a block type; picking it is the skill's job.
Explain the shape of the platform to a new backend engineer: services, databases, third parties. Write it to docs/platform.md and run chiltepin check.
The reader is the point. “A new backend engineer” tells the skill to start wide and go one level down, not to draw every pod. Name the file so the agent writes rather than talks, and ask for the check so the loop closes.
2. What the agent picks, and why
The skill reads the request as the reader's question and answers it with two to five blocks, each a different lens. For this request it picks:
c4— the context view — the platform as one box, the people and third parties around it, a labelled relationship on every edge. Answers “what is this thing?”block— the container map — services, stores and queues inside the platform, grouped and connected. Answers “what is it made of?”sequence— the one request path a newcomer must know — checkout, say — across the services in order. Answers “how does it move?”
Before writing each one it runs chiltepin block <type>, which prints the fields, enums and terse forms from the schema. It writes YAML; it never places a shape.
The block it wrote
The context view the agent wrote for exactly this request, unedited. Eight nodes, seven labelled edges, one kind: dashed for the notification paths.
```c4
id: context
title: System context
level: context
nodes:
- { id: shopper, kind: person, name: Shopper, desc: "Browses, adds to cart, pays." }
- { id: ops, kind: person, name: Warehouse agent, desc: "Picks, packs, and marks parcels shipped from the ops console." }
- { id: platform, kind: system, name: Store platform, desc: "Storefront API, checkout, and fulfilment." }
- { id: stripe, kind: external, name: Stripe, desc: "Card authorisation and capture." }
- { id: avalara, kind: external, name: Avalara, desc: "Sales tax quote per address." }
- { id: easypost, kind: external, name: EasyPost, desc: "Carrier rates and shipping labels." }
- { id: sendgrid, kind: external, name: SendGrid, desc: "Transactional email." }
- { id: twilio, kind: external, name: Twilio, desc: "SMS delivery alerts." }
edges:
- { from: shopper, to: platform, label: browses and buys, tech: HTTPS }
- { from: ops, to: platform, label: picks and ships, tech: HTTPS }
- { from: platform, to: stripe, label: charges cards, tech: REST }
- { from: platform, to: avalara, label: quotes tax, tech: REST }
- { from: platform, to: easypost, label: buys labels, tech: REST }
- { from: platform, to: sendgrid, label: sends email, tech: REST, kind: dashed }
- { from: platform, to: twilio, label: sends SMS, tech: REST, kind: dashed }
```3. Check it
The agent runs npx -y chiltepin check docs/<file>.md --json. Every diagnostic has a stable code, the file and line, and a hint. One it might see on a first draft:
E_SCHEMA docs/platform.md:31 c4: unknown field 'technology'
hint: Valid fields: from, to, label, tech, kind.It fixes what the hint says and re-runs the check. A change is not done until the check passes — and in CI the same command fails the build, so a document cannot drift silently.
4. Render it
npx chiltepin html docs/platform.md -p renders the page and opens it. chiltepin build publishes every doc as a static site with navigation and cross-doc links; chiltepin slides docs/platform.md -p turns the same file into the onboarding deck, one slide per heading; chiltepin pdf prints it. One source, three outputs, no runtime JavaScript.
See it done
The agent-written document for this request is in the gallery: Platform shape, shown exactly as generated from “Explain the shape of the platform to a new backend engineer: services, databases, third parties.”. Related: microservices diagrams, the architecture reference, and the blocks c4, block, sequence.
Frequently asked questions
- Which diagrams document a microservices architecture?
- Three lenses usually cover it: a C4 context view for who and what surrounds the platform, a container or block view for the services, data stores and queues inside it, and a sequence diagram for the one request path a new engineer must understand first. Chiltepin renders all three from typed YAML, and chiltepin check confirms every node an edge names exists.
- Does the agent need to read my code?
- It helps. With the skill installed, ask the agent to read the services directory or the deployment manifests before writing; it names the real services and stores. chiltepin audit scans a codebase and recommends which documents to write, with evidence. Without code access the agent writes a plausible platform and says so in a callout, as the gallery example does.
- How is this different from asking ChatGPT for a diagram?
- The output is checkable. Each block has a strict schema, so chiltepin check proves the structure is right: every edge endpoint exists, every field is documented, every cross-reference resolves. A picture from a chat window has none of that, and it goes stale the week a service is renamed. These blocks live in the repository and fail CI when they drift.
- Can I keep it up to date automatically?
- Run chiltepin check in CI so a broken reference fails the build, and ask the agent to update docs/platform.md in the same pull request that adds a service. For API and schema sources, chiltepin sync openapi and chiltepin sync sql regenerate blocks from the spec and can fail on drift with --check.