Skip to content
Documentation

Architecture Diagrams 101

This guide explains why architecture diagrams matter, the four diagram types every delivery team needs, what makes diagrams useful versus useless, and how to keep them accurate after the first sprint.

Junior and mid-level engineers on government delivery teams who need to create, review, or maintain architecture documentation will find it most useful — including teams preparing for ATO reviews, security assessments, or new-engineer onboarding.

TL;DR — What Every Delivery Team Needs

Diagram typeWhen you need itKey question it answers
Context diagramBefore you build anything; update at each major milestoneWho uses this system, and what does it connect to?
Container diagramWhen designing or reviewing the system’s technical componentsWhat are the major deployable pieces and how do they communicate?
Component diagramWhen a specific container is complex enough to warrant detailWhat are the internal parts of this container and how do they interact?
Data flow diagramFor any system handling PII, PHI, or sensitive government dataWhere does sensitive data enter, move through, and leave the system?

Why Architecture Diagrams Matter

Code tells you how a system works. Prose documentation tells you what decisions were made and why. Architecture diagrams tell you what the system’s shape is — how the pieces fit together, what talks to what, and where the boundaries lie.

A new engineer reading your code for the first time cannot easily see: Is this a monolith or microservices? Where does the user’s data go? Which parts are controlled by the government agency and which are operated by a vendor? What happens when the identity provider is unreachable?

These are the questions that architecture diagrams answer at a glance. They are not a substitute for code or documentation — they are the overview that makes code and documentation navigable.

In government contexts, architecture diagrams serve additional purposes beyond team communication. They are required artifacts in ATO packages, security assessments, data governance reviews, and incident investigations. A clear, accurate diagram at the start of a security review saves weeks of back-and-forth with agency security teams.

External Resources

The Four Diagram Types Every Delivery Team Needs

These four types are based on the C4 model, a widely adopted framework for software architecture documentation created by Simon Brown. C4 stands for Context, Container, Component, and Code — though in practice, teams rarely need the Code level.

Context Diagrams

A context diagram shows your system from the outside. It answers: who uses this system, and what external systems does it connect to? The system itself is a single box in the center. Everything around it — users, external agencies, identity providers, vendor APIs, shared platforms — is shown as external actors with labeled arrows showing what data or requests flow in each direction.

Use a context diagram when: onboarding new team members, briefing stakeholders who are not technical, starting a security review, documenting system boundaries for an ATO package, or planning an integration with another system. Create one before you build and update it at each major milestone.

Figure 1 (placeholder) — A C4 context diagram for a government web service. Center: a single ‘Government Web Service’ system box. Left: an end user labeled ‘Citizen or Agency Employee’ connected by an arrow labeled ‘Submits applications and views status via HTTPS’. Right top: an external box labeled ‘Login.gov (Identity Provider)’ connected by an arrow labeled ‘Authenticates user identity via OIDC — no PII stored in web service’. Right bottom: an external box labeled ‘State Agency Database’ connected by an arrow labeled ‘Reads case status data via internal API — contains PII [PII]’. Bottom: an external box labeled ‘Payment Vendor API’ connected by an arrow labeled ‘Processes fee payments via HTTPS — no PII passed [PII-free]’. Mark any connection carrying PII with a red [PII] label.

Container Diagrams

A container diagram zooms into the system and shows its major deployable parts — the web application, the API layer, the database, background job runners, caches, file stores. Each box is a separately deployable unit. Arrows between boxes show how they communicate and what protocol they use.

Use a container diagram when: designing the technical architecture of a new system, reviewing an existing system’s structure during a security or ATO review, planning where to deploy the system (which parts go in which hosting environment), or debugging a multi-service problem where the call path is unclear.

The container diagram is the most commonly useful diagram type for engineering teams. If you only have time to maintain one diagram, make it this one.

Figure 2 (placeholder) — A C4 container diagram zooming into the government web service from Figure 1. A dashed box labeled ‘Government Hosting Boundary (GovCloud or On-Premises)’ surrounds the government-controlled components. Inside the boundary: a ‘React Front End’ box (browser-rendered, served via CDN), connected by an HTTPS arrow to a ‘Node.js API’ box, which connects via TCP 5432 to a ‘PostgreSQL Database’ box, via TCP 6379 to a ‘Redis Cache’ box, and via an internal task queue to a ‘Background Job Runner’ box. The Background Job Runner also connects to the PostgreSQL database. Outside the boundary: ‘Login.gov’ connects to the Node.js API via OIDC/HTTPS. A ‘Payment Vendor API’ connects to the Node.js API via HTTPS. Label every arrow with the protocol used.

Component Diagrams

A component diagram zooms further into one specific container and shows its internal structure. This is only necessary when a container is complex enough that its internals need documentation — for example, an API service that has multiple distinct modules handling authentication, data access, file processing, and external integrations.

Use a component diagram for: a container that has grown large and has multiple teams working on different parts, a container with complex internal routing or a plugin architecture, or when a security review specifically requires understanding the internals of a service.

Do not draw component diagrams for every container. They add maintenance burden. Draw them only when the container’s internal structure is genuinely confusing or where regulatory requirements demand it.

Data Flow Diagrams

A data flow diagram traces where sensitive data enters your system, how it moves through it, and where it exits. It is not primarily about system architecture — it is about data custody and control.

Data flow diagrams are required for any government system handling PII, PHI, financial data, or controlled unclassified information (CUI). They are core components of Privacy Impact Assessments (PIAs), System Security Plans (SSPs), and HIPAA compliance documentation.

A data flow diagram shows: where each category of sensitive data enters (user input, upstream system, file upload), which components it passes through, where it is stored (and in what form — encrypted, tokenized, plaintext), and where it exits the system (to another system, to a vendor, or to the user).

Elements of an Effective Diagram

A diagram that lacks these elements is likely to cause confusion or fail a security review.

Named Boxes with Role Descriptions

Every box must have a label that describes what it is and what it does. “Database” is insufficient. “PostgreSQL — stores case applications and audit events (PII)” is correct.

Labeled Arrows with Data and Direction

Every arrow must show the direction of the flow and what it carries. “Calls” or a plain arrow tells you nothing. “HTTPS POST — submits application form data [PII]” tells you the protocol, the direction, what data flows, and whether it is sensitive.

Data Classification Markers

Any connection or storage component that carries or holds PII, PHI, financial data, or CUI must be labeled as such. Use a consistent visual convention (for example, a red [PII] label on arrows, a lock icon on storage components). ATO reviewers will specifically look for this.

Trust Boundary Lines

Show clearly where the government-controlled environment ends and external systems begin. This is the hosting boundary — the fence around what your team operates and is responsible for. Anything outside that boundary is an external system, even if your team consumes it.

External System Callouts

External systems — vendor APIs, identity providers, shared agency platforms, legacy mainframes — should be visually distinct from components your team operates. Label them with the vendor or system name, not just “External API.”

Legend

If you use colors, shapes, or icons with specific meanings, include a legend. Diagrams that require tribal knowledge to interpret are not useful to new team members or security reviewers.

Last Updated Date

Stale diagrams are worse than no diagrams because they actively mislead. Put a date on every diagram. Put the date in the filename if you store diagrams as images.

Common Diagram Failures

Diagrams fail for predictable reasons. Knowing the failure modes helps you avoid them.

Too Much Detail at the Wrong Level

A context diagram that shows every database table, every API endpoint, and every configuration flag is unreadable. Each diagram type exists at a specific zoom level. Stay at that level and link to more detailed diagrams when needed.

Unlabeled Arrows

Unlabeled arrows convey nothing. Reviewers cannot tell whether an arrow means “reads data from,” “writes data to,” “calls an API on,” or “subscribes to events from.” Label every arrow.

Staleness After One Sprint

A diagram that was accurate at project launch and has not been updated since is a liability. New engineers learn the wrong architecture. Security reviewers cite the discrepancy. ATO renewal is delayed while you reconcile the diagram with reality.

Single-Owner Storage

A diagram in someone’s personal Miro account or a local Visio file is not a team asset. When that person leaves, the diagram goes with them. Store diagrams in version control or a shared, accessible location.

Aspirational Rather Than Actual Architecture

This is the most insidious failure. Teams draw how they planned to build the system, not how they actually built it. If the diagram is aspirational rather than descriptive, it is not documentation — it is a proposal.

Vendor Logos Without Text Labels

A diagram full of product logos and icons without text labels is hard to understand for anyone unfamiliar with those products. Always include the product name as text, even if you also use a logo.

Missing Trust Boundary Markings

In government systems especially, the boundary between government-operated components and vendor-operated components is legally and operationally significant. A diagram without this boundary fails the first question in most security reviews.

Government-Specific Requirements

Government architecture diagrams carry requirements that private-sector diagrams typically do not.

Hosting Boundary

The hosting boundary shows which components are physically and operationally controlled by the government or its authorized contractors, and which are operated by commercial vendors. This boundary is fundamental to your ATO package and cloud authorization.

Every architecture diagram should clearly show this line. Components inside the boundary are subject to your system’s security controls. Components outside the boundary are covered by the vendor’s own authorization (such as a FedRAMP authorization) and are inherited, not owned, by your team.

Data Authority

Data authority means: who has legal responsibility for the accuracy and protection of this data? In government systems, the agency is typically the data authority, even when a contractor operates the system. Make this explicit in your documentation. Annotate your data stores with the data authority designation.

PII and PHI Indicators

Every storage component, data flow, and integration point that involves PII or PHI must be labeled. This is not optional — it is required for Privacy Impact Assessments under the E-Government Act of 2002, for HIPAA Business Associate Agreements if health data is involved, and for FedRAMP documentation at any impact level.

Use a consistent, visible marking convention. Place PII and PHI labels on both the arrow that carries the data and the storage component that holds it.

ATO Boundary Documentation

The Authority to Operate (ATO) boundary defines exactly which system components are covered by a given security authorization. If your system uses a shared platform or inherited controls (for example, an agency-wide identity provider or a FedRAMP-authorized cloud platform), your architecture diagram must show what is inside your ATO boundary, what is outside it, and how you inherit security controls from external authorizations.

ATO reviewers will compare your architecture diagram to your system security plan. Discrepancies between the two are findings that delay authorization.

Vendor vs. Government-Operated Components

Clearly distinguish components that your team (or the agency) operates from components that a commercial vendor operates. The operating responsibility affects incident response, data breach notification requirements, contract scope, and security control ownership.

A simple convention: use a solid boundary box around government-operated components and a dashed or differently styled box around vendor-operated components. Label each boundary.

How to Keep Diagrams Current

The best diagram is one you will actually update. That means the update process must be easy enough that it happens as part of normal work.

Diagram as Code

Diagram-as-code tools let you write your architecture as text that renders as a diagram. Because the source is text, it lives in version control alongside your code. Changes to the architecture result in a pull request that includes both the code change and the diagram update. Reviewers can see the diff.

Mermaid

The simplest option. It is supported natively in GitHub, GitLab, and most documentation platforms. The syntax is readable and easy to learn. It does not produce publication-quality diagrams, but it produces accurate, maintainable ones.

Structurizr

A tool specifically designed for the C4 model. You write a DSL (domain-specific language) that describes your architecture, and Structurizr renders it as a set of C4 diagrams. It enforces the C4 model’s rules and produces consistent output. A free tier is available.

draw.io (diagrams.net)

Can save diagrams as XML files that can be stored in version control. It does not give you a pure-code workflow, but it is free, widely used, and produces clear output. Many teams use it as a compromise between the accessibility of a GUI tool and the version control benefits of text-based diagrams.

PlantUML

An older but widely supported option for generating diagrams from text. Good for teams already using Java ecosystems or tools that have PlantUML integration.

Diagram Ownership and Maintenance Cadence

Assign diagram ownership explicitly. Every diagram should have a named maintainer or owning team. That person is responsible for reviewing the diagram after every sprint and updating it when the system changes.

A practical rule: if a pull request changes how two services communicate, adds a new external dependency, or adds a new data store, the PR author is responsible for updating the relevant architecture diagram as part of the same PR. Reviewing teams should reject PRs that change the architecture without updating the documentation.

The New Engineer Test

A good architecture diagram passes this test: a new engineer who has never seen the system before can understand its shape, data flows, and trust boundaries within 30 minutes, using only the diagrams and without asking anyone for help.

Specifically, after 30 minutes they should be able to answer:

  • What does this system do, and who uses it?
  • What are the major deployable components and how do they communicate?
  • Where does PII enter and where is it stored?
  • What is the government-controlled hosting boundary?
  • What external systems does this depend on, and what happens if one of them is unavailable?
  • Which parts are the team’s responsibility versus the vendor’s?

Run this test periodically. Have a new team member (or someone from another team) read your diagrams and answer these questions without help. Where they get confused is where your diagrams need improvement.

Common Diagram Content Gaps

Drawing the Aspirational System

This is the most common mistake. The system was designed as clean microservices, but over time it grew a ball of shared database tables, direct service-to-service calls, and undocumented integrations. The diagram still shows the clean original design. Draw what is actually running.

Missing PII Annotations

Engineers sometimes draw diagrams focused on the request path and forget to annotate the data at rest. Your ATO reviewer will ask: where is PII stored? Your diagram should answer that question visually.

Omitted Caching Layers

Redis, Memcached, and other caching layers are often left out of architecture diagrams because they feel like an implementation detail. They are not — they are a place where sensitive data can persist unexpectedly. Include them.

Vendor Logos Without Text Labels

A diagram with a Snowflake logo and no label is only useful to someone who already knows what Snowflake is. Always include the product name as text.

Unlabeled Asynchronous Communication

Message queues, event buses, and pub/sub systems are often left out or shown with generic arrows that do not convey the asynchronous nature of the communication. Use a different arrow style or label to distinguish synchronous (request/response) from asynchronous (publish/subscribe) communication.

Omitted Background Jobs

Background job runners, scheduled tasks, and batch processors are frequently omitted from architecture diagrams. They often have their own database connections, external API calls, and data processing pipelines that are important to document.

Starter Template in Mermaid

This is a minimal architecture diagram for a government web service with a front end, API, database, cache, and two external dependencies. Copy this and modify it to match your actual system.

graph TD
    subgraph "Government Hosting Boundary"
        FE["React Front End\n(served via CDN or S3)"]
        API["Node.js API\n(Port 8080 · HTTPS)"]
        DB[("PostgreSQL Database\nContains PII [PII]")]
        CACHE[("Redis Cache\nSession data · TTL 30min")]
        JOBS["Background Job Runner\n(processes uploaded documents)"]
    end


    USER["Citizen or Agency Employee\n(web browser)"] -->|"HTTPS — submits forms,\nviews case status"| FE
    FE -->|"HTTPS / REST\nor GraphQL"| API
    API -->|"TCP 5432\nencrypted at rest"| DB
    API -->|"TCP 6379\nno PII stored in cache"| CACHE
    API -->|"Internal task queue"| JOBS
    JOBS -->|"TCP 5432"| DB


    IDP["Login.gov\n(Identity Provider)"] -->|"OIDC / HTTPS\nreturns user identifier only"| API
    VENDORAPI["State Benefits API\n(External)"] -->|"HTTPS / REST\nreturns case status [PII]"| API

How to use this template

  1. Replace each label with your actual component names and roles
  2. Replace each arrow label with the actual protocol and data description
  3. Add [PII] annotations to any arrow or component that carries or stores PII
  4. Update the Government Hosting Boundary label to match your actual hosting environment (GovCloud, Azure Government, on-premises)
  5. Add additional external systems for every real external dependency

Store this file as docs/architecture/system-architecture.md (or .mermaid) in your repository. Update it with every sprint that changes the system structure.

Next Steps

  • Data Flow Diagrams 101 — A deeper guide to documenting data movement through a system, specifically for PII and PHI compliance requirements in federal systems.
  • System Inventory — Before you can draw an accurate architecture diagram, you need to know what is running. A system inventory is the foundation: a list of every component, its owner, its hosting environment, and its data classification.
  • C4 Model — c4model.com — The original source for the four-level C4 approach. Includes diagram examples, tooling recommendations, and a FAQ.
  • FedRAMP System Security Plan (SSP) template — Architecture diagrams are required components of an SSP. This template shows exactly what format and content the reviewers expect.
  • NIST SP 800-18 — Guide for Developing Security Plans — The federal standard for system security planning, which architecture diagrams directly support.
  • Structurizr — A C4-model-first diagramming tool with a free tier, especially well-suited for teams that want to enforce consistent diagram structure across a large system.
  • Mermaid documentation — Reference for the Mermaid syntax used in the starter template above.