Architecture

Document System Context and Critical Runtime Flows

Create architecture documentation that helps teams understand users, dependencies, deployment, and important runtime behavior.

Architecture documentation should answer practical questions: what is this system, who uses it, what does it depend on, and how does a critical request move through it?

Start with system context

Identify users, external systems, trust boundaries, and the responsibilities the application owns. A context diagram should show meaningful relationships rather than every internal class.

Describe containers and modules

Show deployable units, data stores, queues, and important internal modules. Explain ownership and the direction of dependencies. Keep names aligned with the repository so readers can find the corresponding implementation.

Document runtime flows

Choose a few critical scenarios such as login, checkout, content publication, or background processing. Show the sequence of components, important decisions, failure paths, and data changes.

Keep documentation close to reality

Store diagrams and decision records with the code when possible. Assign an owner and update documentation when a meaningful boundary or runtime flow changes.

Checklist

  • Explain system purpose and external actors.
  • Show deployable components and data stores.
  • Document critical success and failure flows.
  • Link diagrams to code and ownership.
  • Update documentation as part of architectural changes.
Share this page Help other developers discover this resource.