Architecture diagrams are the most common pictures in software engineering and the least standardised. This page gives a simple notation, two complete worked examples, the same diagram as code, and the mistakes that make architecture diagrams hard to read.
An architecture diagram shows the major parts of a system, where they run, and how they talk to each other: services, data stores, external systems, network boundaries, and the requests or data flowing between them. Engineers, architects, security reviewers and new team members read them to understand a system before reading any code. Unlike UML, there is no single official standard, so a clear legend and consistent conventions matter more than any particular symbol set.
Cloud vendors publish official icon sets (AWS, Azure, Google Cloud). Icons help recognition, but always put a text label on every icon: not every reader knows them.
Walkthrough. Start at the customer on the left. Static files are served by the CDN; API calls continue over HTTPS to the API gateway, the single entry point inside the private network, which handles authentication and rate limiting. The gateway routes to two services. Both use the same Postgres database (a deliberate simplification you might later challenge in review). The order service calls an external payment provider synchronously, because the customer waits for the result, then publishes an event to a queue. An email worker consumes events asynchronously, so a slow email system never slows checkout. The yellow boundary shows what lives inside the private network.
Walkthrough. Three external sources (dashed) feed an ingestion layer: change data capture from the application database, scheduled pulls from SaaS APIs, and a Kafka event stream. Data lands in a lakehouse account, refined from bronze to silver to gold, with an orchestrator running dbt models and tests. Gold tables feed three consumers on the right. The layout follows the direction of data, which is the single most helpful convention for data platform diagrams.
Keeping diagrams as text in the repository means they are reviewed and versioned with the code. The online shop in Mermaid, which renders natively in GitHub and GitLab Markdown:
%% Mermaid flowchart (renders in GitHub, GitLab, Notion, mermaid.live)
flowchart LR
user([Customer]) --> cdn[CDN]
cdn -->|HTTPS| gw[API gateway]
subgraph vpc [Cloud VPC]
gw --> orders[Order service]
gw --> catalog[Catalog service]
orders --> db[(Postgres)]
catalog --> db
orders -.->|event| q[[order queue]]
q -.-> email[Email worker]
end
orders -->|charge| pay[Payment provider]:::ext
classDef ext stroke-dasharray: 5 5The same system as a C4 container diagram in PlantUML using the C4-PlantUML library. The C4 model (by Simon Brown) defines four zoom levels: system context, containers, components and code, which answers the "how much detail?" question.
' C4-PlantUML container diagram (renders with PlantUML + the C4-PlantUML library)
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
Person(customer, "Customer")
System_Ext(pay, "Payment provider")
System_Boundary(shop, "Online shop") {
Container(gw, "API gateway", "Managed gateway")
Container(orders, "Order service", "Python / FastAPI")
ContainerDb(db, "Database", "PostgreSQL")
ContainerQueue(q, "Order queue", "SQS")
}
Rel(customer, gw, "Uses", "HTTPS")
Rel(gw, orders, "Routes to")
Rel(orders, db, "Reads/writes")
Rel(orders, q, "Publishes OrderPlaced")
Rel(orders, pay, "Charges card", "HTTPS")
@endumlOther options include Structurizr DSL (C4-native, one model generating many views), the Python diagrams library (cloud icons from code), and D2.
Pros
Cons
When to use: onboarding, design reviews, security and compliance reviews, incident write-ups, proposals for new systems. When not to: to explain the order of calls in one request (use a sequence diagram), to model data structure (use an ER diagram), or as a substitute for runbooks.