S/01 · Services
System architecture
The decisions that decide everything else.
Before anyone writes code, we work out what the system has to hold, how its parts talk and where it will break — and we write the reasons down, so the next team inherits a plan instead of a mystery.
- You get
- Architecture docs, data model, ADRs
- Fits
- New builds, rewrites, scaling pains
- Built for
- Ten years, not one release
- 01
You are about to build something big and want it right the first time.
- 02
The current system is slow to change and nobody can say why.
- 03
Two teams keep breaking each other’s work.
- 04
Growth is coming and you don’t know what will give first.
- D/01
Domain & data model
We map the business into entities, how they relate, and the rules that must always hold. It is the part of a system that is hardest to change later, so we get it right on paper first, and it stays the reference every screen and API is built against.
Included
- An entity–relationship model, with every field and what it means
- The rules that must always hold, written in plain language
- The lifecycle of the key records: their states, and who may change them
- Retention and privacy notes for every table
docs/data-model.dbml - D/02
Service boundaries
We decide which parts the system is made of, what each one owns, and how they talk: an API call where an answer is needed now, an event where it can wait. Clear boundaries let teams work in parallel without breaking each other’s work.
Included
- A context map: every service, and the data it owns
- API contracts between services, in OpenAPI or gRPC
- Events and queues, with who publishes and who listens
- What may never be shared directly, and why
docs/architecture/containers.mmd - D/03
Decision records
Every significant choice is written down as an architecture decision record: the problem, the options we considered, what each one costs, and why we picked the one we did. When someone asks “why is it like this?” in three years, the answer is in the repository.
Included
- One record per decision, numbered and dated
- The options with honest trade-offs, not just the winner
- Consequences: what it makes easy, and what it makes hard
- Its status kept current when a decision is revisited
docs/adr/0007-bookings-in-postgres.md ADR-0007 · Keep bookings in PostgreSQL
Accepted · 12 March
Context
- Bookings need strict consistency: no slot may be sold twice.
- Expected load: 40 writes a second at peak.
Options
- PostgreSQL with row locks: simple and proven.
- An event-sourced store: flexible, but more to run.
Decision
- PostgreSQL, with a unique index on (clinic_id, slot_at).
Consequences
- + One database to back up and reason about.
- − Reports read from a replica, a few seconds behind.
- D/04
Diagrams that stay true
We draw the system at the levels people actually need: the world it lives in, the containers it is made of, and the components inside the important ones. The diagrams are text in the repository, so they are reviewed and updated in the same change as the code.
Included
- C4 context, container and component views
- Diagrams as code, versioned with the repository
- Sequence diagrams for the flows that matter
- A one-page overview for anyone new to the system
repository - docs/
- overview.mdstart here
- architecture/
- context.mmdC4 · context
- containers.mmdC4 · containers
- booking-flow.mmdsequence
- adr/
- 0001-record-decisions.mdaccepted
- 0007-bookings-in-postgres.mdaccepted
- data-model.dbmldata model
- runbook.mdoperations
- D/05
Risk & scale review
We look for where the design will fail before production finds it: single points of failure, hot spots under load, data that grows without limit, gaps in security. Each risk gets a severity and a way out, so you decide what to fix now and what to watch.
Included
- Failure modes, and how far each one reaches
- Load estimates, and where the first bottleneck will be
- A security review of the data flows and access
- A watch list of the numbers that warn you early
docs/risk-register.md - A single database is a single point of failurehigh
- Slot search slows as clinics are addedmedium
- The notification queue has no dead-letter queuemedium
- Payment webhooks can be retried safelydone
- Personal data is encrypted at rest and in backupsdone
- D/06
A buildable roadmap
The design is cut into milestones in the order that makes sense to build. Each one ships something that works end to end, so you see progress early and can change course without throwing work away.
Included
- Milestones, each with a working result
- Dependencies, and what can be built in parallel
- Effort ranges, with the uncertainty shown honestly
- What to build later, and what not to build at all
docs/roadmap.md Weeks 1–3
Bookings core
→ book, cancel and reschedule
Weeks 4–6
Payments
→ online payment and refunds
Weeks 7–8
Notifications
→ SMS and email reminders
Weeks 9–11
Clinic dashboard
→ schedules and reports
- 01
Listen
Users, constraints, budgets, the legacy nobody wants to touch. We ask until the problem is clear.
- 02
Model
We model the domain and the data first; most architecture mistakes start there.
- 03
Decide
Options with honest trade-offs, written as decision records you can challenge.
- 04
Hand over
Docs, diagrams and a roadmap your team — or ours — can build from.
An architecture engagement usually takes four to six weeks, depending on the size of the system. You are involved throughout: nothing is designed behind a closed door, and every decision is one you have seen argued.
- Week 1
Workshops with your team: the users, the goals, the constraints, and the systems already in place.
- Week 2
The domain and data model drafted, and reviewed with the people who know the business best.
- Weeks 3–4
Service boundaries, integrations and the key decisions, each written as a decision record.
- Week 5
The risk and scale review, then the roadmap, cut into milestones.
- Week 6
Handover: we walk your team through everything and answer the hard questions.
The architecture document
One document that explains the system: its parts, its data and the reasoning behind them.
Decision records
Every choice and its trade-offs, in your repository and in plain language.
Diagrams as code
Diagrams your team edits alongside the code, so they never fall out of date.
The data model
The full model, with what every field means, its rules and its lifecycles.
The roadmap
Milestones and estimates that your team, or any team, can build from.
A check-in once building starts
A review of how the design holds up in practice, and what to adjust.
- C4 model
- ADRs
- Event storming
- PostgreSQL
- OpenAPI
- gRPC
- NATS / Kafka
- Threat modelling
Do we need this if we already have developers?
Usually more so. Good developers move fast in whatever direction they are pointed; architecture makes sure it is the right one.
Can you review an existing system?
Yes. We map what is actually there, document it, and give you a path forward that doesn’t start with a rewrite.
How long does it take?
Four to six weeks for most systems. A focused review of an existing system can take two.
What do you need from us?
A few hours a week from the people who know the business and the current systems, and access to whatever exists today.
Do you build it too?
If you want us to. The architecture stands on its own either way — that is the point of writing it down.
Tell us what you are building.
Every project starts with a consultation: you bring the idea and everything you know, we turn it into a design you can build on.
Book a consultation