Draw the view your reader needs
Use context, container, and dynamic views to answer different architectural questions.
BY THE END, YOU CAN
- Choose a diagram level for its audience
- Label responsibilities and relationships unambiguously
- Use a dynamic view to expose runtime failures
Diagram description: Developer → API (submits); API → SQLite; Worker → SQLite; Worker → Email provider (sends)
Start outside the system
A context view places Relay among people and neighboring systems.
It should answer who uses it, what it provides, and where external dependencies sit. For example, a product backend submits jobs and an email provider performs an external effect. Avoid implementation details at this level.
A stakeholder should be able to locate the system’s boundary without learning a framework. Include a legend for any notation that could be ambiguous, especially trust boundaries and data ownership.
Zoom into applications and stores
A C4 container view describes the major running applications and data stores inside a system.
“Container” here is an architectural abstraction, not necessarily a Docker container. Relay might contain an API application, a worker process, and a job database. Label each responsibility and each interaction: “submits validated job over HTTPS” is more informative than an unlabeled arrow.
Add a component view only when it answers a question that the broader view cannot. More detail is not automatically more useful.
Show a scenario unfolding in time
A static diagram cannot show when a worker commits a result relative to acknowledging a job.
Acknowledging means the worker tells the queue the job is finished, so the queue will not hand it out again. Use a sequence or other dynamic view for that scenario. Walk through a crash between the external effect and the acknowledgement.
Who retries? Where is the idempotency key checked? An idempotency key is a unique identifier for one intended operation, so a repeat of that operation can be recognized and not performed twice.
A deployment view can separately show where processes run and which failures they share. Keep names consistent across views and review diagrams when the implementation changes. Treat each diagram as a claim to check against the system.
COMMON FAILURE MODE
Mixing users, classes, cloud regions, and database tables into one unlabeled picture. Readers cannot tell which level of abstraction an arrow represents.
TRY IT YOURSELF
Sketch a context view for a nontechnical Relay stakeholder and a container view for a developer. Explain what you intentionally left out of each.
Make the call in the laboratory.
The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.
Open in the laboratory ↗CONNECT IT TO RELAY
Create Relay context and container views, then a failure sequence for “effect succeeds, worker crashes before acknowledgement”.