How the system fits together, and the decisions that shaped it.
An agent reading your code sees what exists, never why. The architecture document is where the reasons live, and it is the document most likely to have a stale second copy somewhere, written by somebody who could not find the first.
# Architecture ## Purpose Lets clinic staff book, move and cancel appointments, and sends reminders to patients. ## Main parts - Web app: React, talks only to the API - API: Express, owns all business rules - Worker: sends reminders on a schedule - PostgreSQL: the only store ## How it fits together The web app calls the API, which validates the request, writes to PostgreSQL in a transaction, and queues any reminder for the worker. ## Constraints - Patient data stays in the UK region - Must run on a single small server for the first year ## Architecture decisions - One database, not a database per service: the team is three people