To draw a web app architecture diagram, list every part of the system, the users, front-end apps, servers, databases and third-party APIs, then draw an arrow for each connection and label it with what moves along it. Choose the diagram type for the question you are answering: architecture for parts, user flow for steps, sequence for the order of messages and ER for data. Writing it in Mermaid keeps the diagram in plain text next to your code.
I draw these for client projects and for my own. Below is the method, with the real architecture of this site as the worked example. If you would rather describe your system and get the diagram back, use the free Architecture Diagram Generator.
Which type of diagram do you need?
The one that answers the question in front of you. Mixing them in one picture is the most common reason diagrams get confusing.
| Diagram | Answers | Use it for |
|---|---|---|
| Architecture | What are the parts and how do they connect? | Onboarding, reviews, planning a migration |
| User flow | What steps does a person take? | Sign-up, checkout, booking journeys |
| Sequence | In what order do parts talk during one action? | One request, such as login, payment or an API call |
| Database (ER) | What tables exist and how do they relate? | Data modelling, reviewing a schema |
How do you draw an architecture diagram step by step?
- 1
List the parts
Users, front-end apps, servers or functions, databases, file storage, queues and every third-party service.
- 2
Group them
Client side, your servers, your data, outside services. Groups make the boundaries visible.
- 3
Draw the connections
One arrow per real connection, pointing in the direction of the request.
- 4
Label every arrow
Say what moves: HTML, JSON over HTTPS, a webhook, a database query, a streamed response.
- 5
Mark the weak spots
Single points of failure, secrets, rate limits and anything you do not control.
What does a real architecture diagram look like?
Here is this portfolio, mohitgoyal.in. It is a server-rendered React app on TanStack Start behind Cloudflare. Project and profile data live in Firebase Firestore, case studies and posts are markdown files in the repo, images come from a dedicated assets subdomain, and the AI chat calls the Anthropic Claude API from a server route.
Every arrow carries a label, and every outside service sits at the edge of the picture. A new developer can see from this one image where content comes from, what the chat depends on and where an edit in the admin ends up.
When do you need a sequence diagram as well?
When the order of events matters. The architecture diagram shows that the chat route talks to Firestore and Claude. It does not show what happens first, or where a request can be refused. A sequence diagram of one chat message does:
This version shows the guardrails: the route only accepts requests from the site's own pages, limits how many messages one visitor can send in a window, and builds the system prompt from the server-side profile rather than from anything the visitor sends.
That is the kind of detail a reviewer looks for and an architecture diagram cannot show. Draw a sequence diagram for each flow where money, personal data or a third-party API is involved, such as checkout, sign-in or a webhook from a payment provider.
How detailed should an architecture diagram be?
Detailed enough for the reader in front of you, and no more. I keep two levels:
- A system overview for clients, founders and new team members. Boxes are whole services: the website, the API, the database, the payment provider. It fits on one screen and changes rarely.
- A component diagram for developers working on one part. It zooms into a single box, such as the API, and shows its routes, workers and the queues between them.
If a diagram needs scrolling to read, it is two diagrams. Split it at a boundary, such as everything behind the API, and link the two.
Keep the names identical to the names in the code and the hosting dashboard. If the diagram says "Orders API" and the repository says "backend-v2", the diagram has created a translation problem instead of solving one. The same goes for environments: draw production, and note in a line underneath where staging differs.
What mistakes make architecture diagrams hard to read?
- Unlabelled arrows. The label is the information. "Calls" is not a label; "JSON over HTTPS" is.
- Everything in one picture. Put the parts on the architecture diagram and the order of events on a sequence diagram.
- Missing third parties. Payment providers, email services, analytics and AI APIs are where outages and costs hide. Draw them.
- No boundaries. Group what runs in the browser, what runs on your servers and what you rent from others.
- Diagrams as images. A PNG goes stale the day the system changes. Text-based diagrams get updated in the same pull request as the code.
Why Mermaid
Mermaid diagrams are plain text, so they live in your repo, show up in code review and render in GitHub, GitLab, Notion and Obsidian. Paste the code into mermaid.live to edit it visually.
How does the Architecture Diagram Generator help?
Describe the system in plain English, naming each part and what talks to what, then pick architecture, user flow, sequence or database (ER). You get the diagram rendered on the page, the Mermaid code to copy, a component-by-component breakdown, the weak spots and single points of failure, and one suggestion to improve the design.
The more specific the connections in your description, the more accurate the diagram. It draws what you describe; it does not choose your architecture. For that, the Tech Stack Advisor recommends a stack, and my guide on how to choose a tech stack explains the reasoning.
If you need a system designed or reviewed, not just drawn, I build web apps through my web and mobile apps service. Send me your diagram, or your description, and I will reply with what I would change.
