Skip to content

Architecture diagram

Design question 2: What parts make up the system?

Where the software runs, its main parts and how they communicate.

What it explains and when it is useful

An architecture (deployment) diagram shows the main parts of the solution, the machines or services they run on and how they communicate: browser and server, app and database, your code and external APIs.

When to use it: Any solution with more than one running part: web apps, mobile apps with a backend, programs that call an API or use a cloud database, serverless functions.

Worked example

Illustrative: PracticePal is a fictional project used throughout this guide.

Architecture diagram for PracticePal: browsers on phones and laptops talk to the Flask web app on the school web server over HTTPS; a scheduler runs timed jobs; all data goes through one data-access module to an SQLite file; offer emails go to the school's SMTP server and usage reports are written as CSV filesClient devicesSchool web serverPython 3.12 · Flask 3Browserstudent's phone / laptopBrowserhead of music's laptopFlask web approutes · rules · waiting list · reportsSchedulerAPScheduler, every 5 minData accessdb.py: the only module with SQLCSV filesexports/SQLitepracticepal.dbSchool emailSMTP serverHTTPSoffer emailsweekly reportruns no-show andoffer-expiry jobsSQLDashed box = external service that PracticePal uses but does not control. Module-level detail: see the component dependency diagram.
PracticePal's architecture: client devices, the school web server, the database file and the external email server.

Scroll sideways to see the whole diagram.

Companion: component dependency diagram

Zooming in on the server, a dependency diagram shows which module depends on (imports) which. It makes design rules visible: here every module reaches the database only through db.py.

Component dependency diagram for PracticePal: arrows point from a module to the module it imports and depends on; every module reaches the database only through db.pyapp.pystarts Flaskviews.pyroutesscheduler.pytimed jobsauth.pyreports.pyrules.pywaitlist.pydb.pythe only module with SQLdashed arrow:“depends on”
PracticePal's Python modules and their dependencies.

Scroll sideways to see the whole diagram.

Companion: API request/response specification

Where components talk over an interface (your own JSON endpoints, an external API, a serverless function), specify each request and response. PracticePal's browser code calls two JSON endpoints:

EndpointRequestSuccess responseError responses
GET /api/week?room=P5&w=2026-11-02room code; Monday of the week (ISO date); session cookie200 {room, week, slots:[{start, state, mine}]}; state ∈ free, booked, blocked400 bad room or date · 401 not logged in
POST /api/bookJSON {room, start, loud}; session cookie; CSRF token201 {booking_id, room, start, end}409 {reason} (taken, weekly limit, noise clash, blocked) · 400 invalid · 401

Notation and legend

Symbol or partMeaning
Rounded groupA machine or environment (client devices, the school server)
BoxA component running there
Striped boxStored data (files, database)
Dashed boxExternal service you use but do not control
Arrow with labelCommunication and what it carries; two heads = both directions

Design decisions it communicates

A diagram earns marks when you explain the decisions it shows. In PracticePal's documentation these would each be one sentence:

  • All SQL is in one module, so the rules can be tested without a browser and the database could be swapped later.
  • The scheduler is a separate part because no-shows and expired offers must be handled even when nobody is using the site.
  • Email is external: the design depends on the school allowing it (this became a limitation in Criterion E).

Common mistakes

  • Mixing in screens: navigation belongs in a site map.
  • Unlabelled arrows.
  • Drawing every function: keep the architecture high level and use a structure chart or class diagram for detail.
  • Leaving out external services (APIs, email, authentication) that your solution depends on.
Often confused with: Site map. A site map shows screens and how the user moves between them. An architecture diagram shows where software runs and how machines and services communicate. A user never “navigates” to the database.

Checklist for your own version

Ticks are saved in this browser only, so you can use the list while you draft.