How to create architecture diagrams for a web app: what to include, a template, and the check against production

Start with a list, not a canvas: write down every deployed component, every third-party service and every place user data crosses a boundary, and only then draw. That is how to create architecture diagrams a new engineer can trust. For a typical SaaS the result is 7 boxes, and the last step is comparing each one with the live environment.

What is an architecture diagram for software, and what belongs on it

An architecture diagram for software is one picture of what is deployed and how the pieces talk. It needs 5 things to be useful to a reviewer: the deployed components, labeled data flows, authentication boundaries, third-party integrations with call direction, and the differences between environments.

In a handover, the diagram is one document among several, and it answers a new owner’s most basic question: what is running, and where? The rest of the set is part of what a developer handoff looks like.

A software system architecture diagram, in the sense I use here, describes the system as it runs today, not as it was planned. People say “system diagram” and “architecture diagram” for the same picture, and I treat the two names as one. Architectural diagrams in software engineering come in many kinds (context, container, data flow, sequence, entity-relationship), and later sections cover the ones a small team needs. The one to make first is this one.

In software engineering an architecture diagram earns its place by one test: a new engineer can find each box in a dashboard and each arrow in the code. The right-hand column is my list of where to look.

The architecture diagram best practices I would keep come from Microsoft’s guidance on architecture design diagrams: “Use directional arrows”, “Label everything clearly”, include metadata such as a “last updated date” and an “author”, provide a legend “If you introduce border or line semantics”, and “Store diagram source files in the same repository or documentation store as the workload’s other versioned assets.” I add one of my own: one audience per diagram. A picture drawn for a new engineer and a picture drawn for an investor’s reviewer answer different questions, and a single drawing that tries to serve both serves neither well.

Treat the five rows above as the architecture documentation checklist for the picture itself, and the six checks in the verify section as its test.

What goes wrong without it

Without a diagram, the knowledge of how the app fits together lives in one person’s head or in nobody’s. It shows up as a question at a bad moment:

An AI-built app adds one more problem, by my reading: the architecture may never have been chosen on purpose. When a builder tool adds an auth provider, a storage bucket or an email service because a prompt asked for a feature, no person picked that piece, so to map the application architecture you have to discover it first, from what is deployed. An architecture diagram for a software project still in planning can be a sketch of intent; once the app is live, the diagram has to describe what runs.

In one of my own apps that I audited, the README described a different application from the one in the repository: it named a different framework for both halves, a Redis queue tier the code’s own header says is disabled, and a monitoring stack with no trace in the code. Any new developer, or any AI session primed with the README, starts from wrong facts. The lesson I take from it: a description written from memory documents the app someone meant to build, so the inventory has to come from what is deployed.

Across the 21 third-party apps I audited, the Maintainability & Evolvability pillar averages 61.1 out of 100, scored on 21 of the 21, which ranks it 10th of 12 pillars counting from the weakest. Those 21 audits ran in June and July 2026 on a selected set of apps, so the number describes that set; it is not a random sample and not a rate for AI-built apps in general.

Runbooks lean on the diagram too. Every step in a runbook template that says “restart the worker” or “check the queue” assumes someone knows where the worker and the queue run.

How to create architecture diagrams: the list first, then the boxes

Creating an architecture diagram takes 7 steps: name the audience and question, build the inventory from the hosting dashboard and environment variables, draw one box per deployed thing, add third parties with call direction, mark authentication boundaries, label every arrow, then date it and commit it beside the code.

When you set out to draw a system architecture diagram, it is tempting to open a canvas and fill it from memory. I’d make the list first. Preparing an architecture diagram this way takes an afternoon or so for a small SaaS, by my working rule; a bigger system takes longer, mostly in step 2.

1. 01 Name the audience and the one question the diagram answers, for example: a new engineer asking what runs where.
2. 02 Build the inventory from the hosting dashboard, the environment variable names and the package manifest, not from memory. Write one line per service, database, bucket, queue, scheduled job and outside provider.
3. 03 Draw one box per deployed thing. A box you cannot point to in a dashboard does not go on the diagram.
4. 04 Add the third parties and the direction of every call and webhook: an arrow from the app to the provider for each call, and an arrow back in for each webhook.
5. 05 Draw the authentication boundaries as dashed lines and mark which side each box is on: public, signed-in user, or server-only.
6. 06 Label every arrow with what moves across it: a session token, a payment event, an email to send, a file.
7. 07 Date it, name an owner, and commit it next to the code, in the same repository.

The steps are my method. The arrows, the labels, the date and the repository step agree with Microsoft’s practices quoted above.

Step 2 is where the work is. To create a system architecture diagram that matches production, open three things side by side. The hosting dashboard lists what runs. The environment variable names (never the values) name the providers the app talks to, because an app cannot call a payment or email service without a key for it. The package manifest names the client libraries, which catches a provider whose key sits somewhere you did not look. Anything that appears in one source and not the others is a question to answer before drawing.

I’d give steps 4 and 5 extra care. The webhook arrow is easy to miss, because nothing in the app’s own code calls it: the provider does. The boundaries matter because a diagram without them cannot say which box holds the privileged keys.

Build the system architecture diagram from the inventory, never the inventory from the diagram. The same seven steps work whether you create a software architecture diagram for a new engineer or a technical architecture diagram for a security reviewer; only step 1 changes, and with it the level of detail. If a tool offers to generate the system architecture diagram from your cloud account, it can save time on step 3, but it can only draw what that account can see; the auth provider, the payment service and the email service still come from the variable names.

These steps describe a system that exists. To design a system architecture diagram for something not yet built, you start from requirements instead, and the check at the end waits until it ships. The quickest way to make a system architecture diagram that stays true is to keep it as text beside the code, which the drawing section below covers.

A system architecture diagram example and template for a typical SaaS

A typical SaaS fits in 7 boxes: browser, application host, managed Postgres, auth provider, payments, email and file storage. Three dashed boundaries separate the public, the signed-in user and the server-only zone reached with privileged keys. The payments webhook is the arrow pointing inward.

This is the system architecture diagram for a web application that I start from for a small SaaS: a browser, the web app and API on one application host, a managed Postgres database, an auth provider, Stripe with its webhook arrow pointing back in, an email provider and file storage. Copy the Mermaid below as your software architecture diagram template; it is written in Mermaid’s flowchart syntax (subgraphs, text on links, a dotted link for the webhook, and a dashed style on each boundary).

flowchart LR
  %% Title: production architecture of <your app>
  %% Last updated: YYYY-MM-DD. Owner: <name>. Commit: <short sha>

  subgraph PUBLIC [Public: no session]
    B[Browser]
    AUTH[Auth provider]
  end

  subgraph SIGNED_IN [Signed-in user: session checked]
    APP[Web app and API on the application host]
    FILES[File storage]
  end

  subgraph SERVER_ONLY [Server-only: reached with privileged keys]
    DB[(Managed Postgres)]
    PAY[Stripe]
    MAIL[Email provider]
  end

  B -->|sign in| AUTH
  AUTH -->|session token| B
  B -->|pages and API calls, with session| APP
  B -->|upload and download files| FILES
  APP -->|reads and writes, server key| DB
  APP -->|create checkout, secret key| PAY
  PAY -.->|webhook: payment events| APP
  APP -->|send email, API key| MAIL
  APP -->|grant file access| FILES

  style PUBLIC stroke-dasharray: 5 5
  style SIGNED_IN stroke-dasharray: 5 5
  style SERVER_ONLY stroke-dasharray: 5 5

Rendered, the template draws seven boxes in three dashed zones with nine labeled arrows, one of them dotted. The table below reads the same software application architecture diagram example box by box, for anyone who cannot render Mermaid.

Stripe apart, this sample software architecture diagram names roles, not vendors, so it becomes your system’s diagram once you write your own vendors in. Boxes that name roles rather than products also survive a change of framework. For a technical reader, add host names and regions to the boxes; that turns it into a technical architecture diagram for the web application without changing its shape. Update the diagram in the same pull request that changes what it shows.

To adapt it, delete what you do not have and add what you do: a queue and its worker, scheduled jobs, a model provider such as an LLM API, a search service. For a startup, I’d treat this example as the whole template until a second service appears; before that, one architecture diagram is enough. A business architecture diagram, for example one of capabilities and value streams, is a different artifact for a different audience and does not belong on this one.

Three-tier web application architecture, and how an AI-built app bends it

Three-tier web application architecture organizes an app into presentation, application and data tiers. When the browser queries the database directly, row level security policies are what stand between the tiers, and an honest diagram draws that arrow instead of hiding it behind an application box.

IBM describes three-tier architecture as organizing applications into “three logical and physical computing tiers”: “the presentation tier, or user interface; the application tier, where data is processed; and the data tier, where application data is stored and managed.” Martin Fowler on presentation, domain and data layering describes the same split inside the code: “a web layer that knows about handling HTTP requests and rendering HTML, a business logic layer that contains validations and calculations, and a data access layer that sorts out how to manage persistent data in a database or remote services.”

Builder-generated apps bend that picture. Lovable apps enforce data access through Supabase row level security policies. My reading of what that means for the drawing: on those apps the browser can query the database directly, so that browser-to-database arrow carries the policy, and the diagram should draw the arrow and name the policy on it.

In web application architecture terms, a logical architecture diagram for a web application shows responsibilities: which part renders pages, which part decides, which part stores. A web application infrastructure architecture diagram shows hosts, regions and networks. An enterprise web application architecture diagram may need them apart, because there are many hosts; a small SaaS can put both on one page, as the template does. Patterns and styles are a separate subject from drawing, and they belong to software architecture for a small SaaS.

Context and container diagrams: the level above the boxes

An architectural context diagram shows your system as one box among its users and outside systems. It is the first of the C4 model’s four levels. The container diagram below it shows the high-level shape and the major technology choices, and a small SaaS rarely needs more than those two.

The C4 model, created by Simon Brown, names four levels: system context, containers, components and code. Its own pages say a system context diagram “is recommended for all software development teams”, and so is a container diagram, while for components the advice is “only create component diagrams if you feel they add value”. Microsoft’s guidance describes the same top level: a context diagram “presents the workload as a single black box in its external environment”.

The architecture context diagram is the one to hand a non-technical reader, and the one to put at the front of a due diligence pack: C4 lists its audience as “Everybody, both technical and non-technical people”. The seven-box example above is a container diagram.

What is a data flow diagram, and when to draw one instead

A data flow diagram shows how data moves, is stored and leaves a system: it follows data instead of deployment, through external entities, processes, data stores and flows, plus trust boundaries when drawn for threat modeling. Draw it when the question is where a customer’s data goes, and the architecture diagram when the question is what runs where.

Microsoft’s guidance puts the threat-modeling version this way: the diagram “shows processes, data stores, external entities, trust boundaries, and data flows crossing those boundaries.” Draw one for a privacy review, for the data annex of a customer’s DPA, or for a threat model. Both are built from the same inventory, so make the list once and draw two pictures from it. The privacy version of this picture is a GDPR data map, which adds, for each flow, the personal data it carries.

Drawing it: Mermaid in the repo, Excalidraw for the picture, and AI for the first draft

Mermaid keeps the diagram as text in the repository, where GitHub renders it and pull requests diff it. Excalidraw can import Mermaid for a picture people will look at. AI generators give a plausible first draft but see only what you describe or connect, so every box still gets checked.

Which tool for the architecture diagram you pick matters less than where its source lives, and any software architecture diagram tool that keeps its source as text in the repository passes that test. GitHub’s Mermaid support renders a fenced code block with the mermaid language identifier, and “Diagram rendering is available in GitHub Issues, GitHub Discussions, pull requests, wikis, and Markdown files.” A change to the text shows up in the pull request diff like any other change.

For the picture, Excalidraw’s Mermaid converter is “used in excalidraw to transform mermaid syntax to Excalidraw diagrams”, so Mermaid to Excalidraw is a supported path. Its docs say “Currently only flowcharts are supported. All other diagram types will be rendered as an image in Excalidraw”, and a cylinder shape falls back to a rectangle, so the template’s database box arrives as a plain rectangle. The other direction, Excalidraw to Mermaid, is not stated in Excalidraw’s docs. My working rule: the Mermaid text is the source, and the drawing is a view you regenerate.

If you want a tool to design the architecture diagram by placing shapes, draw.io is the free shape canvas. Its site says “Free forever” and “No sign-up required”, and it lists a GitHub integration, so it is a free system architecture diagram tool: you can create the diagram online without an account. You can build an architecture diagram online in any of these, but the copy that counts is the one in the repository.

The table sorts the tools into four types, with one example each and no winner; the last two columns are my reading.

Using AI to generate the architecture diagram is a fine start: describe the app, ask for Mermaid, and you get boxes and arrows to correct. Whichever assistant you use, it knows only what you tell it or connect it to, such as a repository or a hosting account, so its output goes through step 2’s inventory like any other draft. An AI draft is only as good as the description behind it, and a description written from memory is the problem the README example above showed.

Tools that visualize microservices from traces or a service catalog solve a different problem, one that starts at the second service. Until then, microservice visualization is this diagram with one more box.

How to generate an ERD from Postgres

An ERD from Postgres should be generated, never drawn, so it cannot drift. There are 3 routes: the host’s schema visualizer, a desktop client’s ERD view, or a schema-to-Mermaid script in the repository, rerun after every migration.

The data model is the companion picture to the architecture diagram, and every migration changes it. On Supabase, Supabase’s Visual Schema Designer is “an integral part of Supabase Studio” and offers “Visual relationship mapping” that “Clearly illustrates how tables are interconnected”; an export format is not stated in Supabase’s docs. In a desktop client, pgAdmin’s ERD tool can “generate an ERD from a database, schema or a table”, and saves the result with “Download image”. One limit to know: in a schema ERD, “If any table refers to a table in another schema, then that link/foreign key will be removed.”

The third route is a short script that reads the schema and writes a Mermaid erDiagram block into the repository, rerun after every migration so the committed picture matches the database. A data architecture diagram template drawn once goes stale after the first migration; a generated one does not. Whichever route you take, mark the tables that hold personal data, because those are the ones the data flow diagram has to follow. Reviewing the schema itself is a separate job, with the database review checklist.

How to verify it: compare the architecture diagram with the deployed environment

An architecture diagram is verified against the deployed environment in 6 checks: every running service has a box, every provider variable maps to one, every configured webhook is an inbound arrow, every outbound dependency appears, each boundary turns away a wrong-side request, and a second person traces one action.

Each check leaves evidence, so the next person can see the diagram was true on the day it was checked.

1. 01 Every service in the hosting and provider dashboards has a box, and every box has a running service. Evidence: the dashboard list, saved beside the diagram.
2. 02 Every production environment variable that names a provider maps to a box or an arrow. Evidence: the variable names, never the values.
3. 03 Every webhook endpoint configured at a provider appears as an inbound arrow. Evidence: the provider's webhook settings list.
4. 04 Every dependency in the package manifest that calls out to a service is on the diagram. Evidence: the manifest lines, matched to boxes.
5. 05 Each authentication boundary is tested once from the wrong side: a request without a session is refused, or, where row level security guards a table the browser queries directly, the request comes back without the rows the policy guards. Evidence: the status code and the response body.
6. 06 A person who did not draw it walks one user action across it, such as a signup or a payment, and ends where the data actually lands. Evidence: their notes.

Check 5 needs care on Supabase: a refused read does not always look like an error. In Supabase’s words, a using clause filtering the row out “raises nothing, matches zero rows”, so an empty result from the wrong side is the pass, as long as the same query from the right side returns the rows. When the checks are done, record the date, the commit the diagram was checked against, and every mismatch you fixed.

In the Production Hardening Sprint, deliverable 13.2, the system architecture diagram, is verified with the same kind of check: we compare the diagram with the delivered environment and repository.

The diagram is one document in a larger set; how to write technical documentation for a vibe-coded app lists the rest as a checklist. The API’s own reference is a separate job again, with its own tooling: an API documentation tool.

Where the sprint does this

In the sprint, deliverable 13.2 is a system architecture diagram that shows the deployed components, data flows, authentication boundaries, and third-party integrations. At handover it goes into the technical due diligence pack, which bundles the readiness report, architecture diagram, data model, security checklist, and capacity statement in one PDF. Building new product features or modules and completing unfinished core features or business workflows are outside the sprint, and they are separate work. Every deliverable, with how we verify it, is in the published scope.

Common questions about diagramming a web app

Can Chatgpt draw an architecture diagram?

Yes, as a first draft. ChatGPT can turn a description of your app into Mermaid text or a list of boxes and arrows, but it sees only what you describe or connect, such as a GitHub repository, so the draft is only as accurate as those inputs. Run the inventory and the six checks on it as you would on any other diagram.

What is the difference between a flowchart and a system architecture diagram?

A flowchart shows steps in order, with decisions between them; a system architecture diagram shows the parts of a system and how they connect. Microsoft’s guidance says “flowcharts illustrate process flow” and places flowcharts beside activity diagrams for “workflows, decision logic, and business processes”.

What are different types of architecture diagrams?

The six most useful for a web app are: a context diagram (the system as one box among users and outside systems), a container diagram (the main parts, their technology and how they communicate), a deployment diagram (what runs on which infrastructure), a data flow diagram (where data moves and is stored), a sequence diagram (the order of calls for one scenario) and an entity-relationship diagram (tables, keys and relationships). Microsoft lists more, including network, state and user-flow diagrams, and says “The list of diagram types isn’t exhaustive.”

What should an architecture diagram look like?

One page: a box for each deployed part, arrows that point one way and say what moves, dashed lines for authentication boundaries, a legend when a line style carries meaning, and a title, a date and an owner in the corner. Those are Microsoft’s practices for arrows, labels, legends and metadata, plus my boundary lines.

Is Drawio free to use?

Yes. The draw.io site says it is “Free forever” and open source, “Apache 2.0 licensed”, and it comes as an online tool and a desktop app: “Bring your storage to our online tool, or save locally with the desktop app.”