template: solution-architecture-design
system: "{system or solution name}"
project: "{project or programme name}"
lead-architect: "{name / role}"
version: "{1.0}"
status: "{draft | under review | approved}"
last-updated: "{YYYY-MM-DD}"

Solution Architecture Design (SAD): {system or solution name}

Document Control

Version History

Approvals

1. Executive Summary

1.1 Problem Statement

{The business problem or opportunity in two or three sentences: who is affected, what it costs them today, and why now.}

1.2 Proposed Solution Summary

{What the solution does and how it resolves the problem, in plain terms. Name capabilities rather than products.}

1.3 Target State Outcomes

1.4 Stakeholders and Concerns

2. Business Context & Requirements

2.1 Key Functional Requirements

2.2 Non-Functional Requirements (NFRs)

2.3 Scope Boundaries

• In scope: {what this solution delivers}
• Out of scope: {what it deliberately doesn't, and where that is handled instead}
• Constraints: {what the design is not free to change: organisational, technical, legal or contractual, each with its source}
• Assumptions: {what must be true for this design to hold; each is also a risk in section 10 until confirmed}

3. Architecture Decisions (ADR Linkage)

4. System & Component Model

4.1 Logical Architecture Diagram

{A diagram of channels, entry points, services, stores and external systems, and the flows between them, in the form below. It must be readable without colour.}

flowchart TB
  accTitle: {Title of the diagram}
  accDescr: {One or two sentences saying what is in the diagram and how the parts connect, for a reader who cannot see it.}

  subgraph Channels["{Channel or consumer boundary}"]
    Consumer["{Consumer or channel}"]
  end
  subgraph System["{System boundary}"]
    Entry["{Entry point, such as a gateway}"]
    Service["{Service}"]
    Store[("{Data store}")]
  end
  External["{External system}"]

  Consumer -->|"{protocol}"| Entry
  Entry --> Service
  Service -->|"{what it reads or writes}"| Store
  Service -->|"{what it sends or receives}"| External

  classDef external stroke-dasharray: 6 4
  class External external

4.2 Component Catalog

4.3 System Context & External Neighbours

{The system drawn as one box among the people and systems it deals with, so a reader sees its boundary before its insides.}

flowchart LR
  accTitle: {Title of the diagram}
  accDescr: {What is around the system, and what passes between them.}

  User(["{User or role}"]) --> System["<b>{System name}</b>"]
  System <-->|"{what passes in each direction}"| Provider["{External system}"]

  classDef external stroke-dasharray: 6 4
  class Provider external

4.4 Runtime View

{Scenario name}

• Trigger: {what starts it}
• Normal path: {numbered steps, naming the components from 4.2 in order}
• When {part} fails: {what the system does, what the user sees, and what is repaired afterwards}

{A sequence diagram of the scenario, with the normal path and the failure as alternatives. The steps above stay as the text version.}

sequenceDiagram
  accTitle: {Scenario name}
  accDescr: {The normal path and the failure case, in two or three sentences.}

  participant A as {Component}
  participant B as {Component}

  A->>B: {request}
  alt normal path
    B-->>A: {response}
  else a part fails
    B-->>A: {what the caller is told}
  end

5. Integration & Interface Design

5.1 Integration Patterns Used

5.2 API Specifications & Contracts

6. Data Architecture

6.1 Data Model / Schema

6.2 Data Storage Technology Map

6.3 Data Lifecycle & Security

• Personal information: {what is collected, and why}
• Retention: {how long, and what happens after}
• Residency: {where it is stored}
• Encryption: {at rest and in transit}

7. Security & Compliance Controls

7.1 Authentication & Authorization

{Who and what authenticates, how, and how access is scoped: users, administrators, services, external systems.}

7.2 Network Security

{What is reachable from where, and what protects each entry point.}

7.3 Threat Model & Mitigation

8. Deployment & Infrastructure

8.1 Target Environment Specifications

8.2 Disaster Recovery (DR) & Business Continuity

9. Cross-cutting Concerns

10. Risks, Assumptions & Technical Debt

11. Glossary

template: solution-architecture-design
system: Appointment Booking (sample)
project: Appointment Booking
lead-architect: Solution architect
version: "1.3"
status: approved
last-updated: 2026-10-03

Solution Architecture Design (SAD): Appointment Booking (sample)

Document Control

Version History

Approvals

1. Executive Summary

1.1 Problem Statement

Small service businesses (physiotherapists, clinics, salons, advisers) take most bookings by phone. Staff answer calls between clients, customers can't book outside opening hours, and bookings kept in several places produce clashes and no-shows. Existing booking tools either take customers away to another website or ask the business to move its staff onto a new calendar.

1.2 Proposed Solution Summary

A booking service that a business adds to its own website with one snippet. Customers see real availability, drawn from staff members' own calendars, and book, reschedule or cancel themselves. Staff keep using Google Calendar or Microsoft 365; bookings appear there automatically, and customers get confirmations and reminders by email and SMS. One service hosts many businesses, each isolated from the rest.

1.3 Target State Outcomes

1.4 Stakeholders and Concerns

2. Business Context & Requirements

Each requirement below is specified, with checkable scenarios, in requirements/: booking, availability and notifications.

2.1 Key Functional Requirements

2.2 Non-Functional Requirements (NFRs)

Where goals pull against each other, correctness comes first for a single booking and availability comes first when a third party fails: a provider outage may degrade a search, and never stops a booking (ADR-AB-0003).

2.3 Scope Boundaries

• In scope: the widget, the Booking API, availability and booking, calendar synchronisation, notifications, the admin console, multi-business hosting.
• Out of scope: payments and deposits, waiting lists, group classes, staff rostering, reporting and analytics, native mobile apps.
• Constraints:
  • Personal information is stored in Australia (the product owner's commitment to customers).
  • Staff calendars stay with their provider; businesses will not move staff onto a new calendar (the business owners' stated condition for adopting the product).
  • The widget runs on websites the platform does not control (the business model).
  • The platform is run by one small team on call 24×7 (head of engineering).
  • The widget and admin console meet WCAG 2.2 AA (product policy).
• Assumptions: staff calendars are in Google Calendar or Microsoft 365; businesses operate in Australia and New Zealand at launch. Each is a risk in section 10 until confirmed.

3. Architecture Decisions (ADR Linkage)

These are the decisions that shape the whole system: hard or costly to reverse, committing money or a vendor, or fixing a major quality. The no-overlap rule, the five-minute hold, the handling of time zones and the way notifications are delivered are requirements and design, not decisions: they say what must be true, with scenarios, in the booking, availability and notifications requirements. The decisions above are how the design makes them true.

4. System & Component Model

4.1 Logical Architecture Diagram

flowchart TB
  accTitle: Logical architecture of Appointment Booking
  accDescr {
    A customer's browser runs the booking widget in a frame inside the business's web page. The widget calls the API gateway over HTTPS, and so does the admin console. The gateway routes to the availability service and the booking service, which read and write the booking store. The booking service also asks the calendar connectors for a live check of one time when it confirms a booking. The store's outbox is relayed to an event stream, which feeds the calendar connectors and the notification worker. The connectors exchange busy times and booking events with Google Calendar or Microsoft 365, and the notification worker hands messages to an email and SMS provider.
  }

  subgraph Browser["Customer's browser"]
    Page["Business's web page"]
    Widget["Booking widget<br/>(iframe)"]
    Page --- Widget
  end
  Admin["Admin console"]

  subgraph Platform["Booking platform"]
    GW["API gateway"]
    Avail["Availability<br/>service"]
    Book["Booking<br/>service"]
    Store[("Booking store")]
    Stream[["Event stream"]]
    Conn["Calendar<br/>connectors"]
    Notif["Notification<br/>worker"]
  end

  subgraph External["External providers"]
    Cal["Google Calendar /<br/>Microsoft 365"]
    Msg["Email and SMS<br/>provider"]
  end

  Widget -->|HTTPS| GW
  Admin -->|HTTPS| GW
  GW --> Avail
  GW --> Book
  Avail -->|reads| Store
  Book -->|booking + outbox,<br/>one transaction| Store
  Book -->|live check at<br/>confirmation| Conn
  Store -->|outbox relay| Stream
  Stream --> Conn
  Stream --> Notif
  Conn -->|busy times| Store
  Conn <-->|change notifications,<br/>booking events| Cal
  Notif -->|messages| Msg

  classDef external stroke-dasharray: 6 4
  class Cal,Msg external

4.2 Component Catalog

4.3 System Context & External Neighbours

flowchart LR
  accTitle: System context of Appointment Booking
  accDescr {
    The booking platform sits among a customer, who books through the business's website; a business administrator; a staff member, who connects their calendar; Google Calendar or Microsoft 365, which exchange change notifications and booking events with it; an email and SMS provider, which receives messages and reports delivery status; and an identity provider, which signs administrators in.
  }

  Customer(["Customer"]) --> Site["Business's website"]
  Site -->|loads the widget| Platform
  Admin(["Business<br/>administrator"]) --> Platform
  Staff(["Staff member"]) -->|connects calendar,<br/>OAuth consent| Platform
  Platform["<b>Booking platform</b><br/>(this system)"]
  Platform <-->|change notifications,<br/>booking events| Cal["Google Calendar /<br/>Microsoft 365"]
  Platform -->|messages| Msg["Email and SMS provider"]
  Msg -->|delivery status| Platform
  Platform -->|administrator sign-in| IdP["Identity provider"]

  classDef external stroke-dasharray: 6 4
  class Site,Cal,Msg,IdP external

4.4 Runtime View

The three scenarios below are the ones the design most depends on. Each runs in the sample's working demo, whose "Behind the scenes" panel names each step's component and links to its record.

Book a time

• Trigger: a customer on a business's website chooses a service and a time.
• Normal path:
  1. The widget (in its frame) tells the API which page embeds it, and asks the API gateway for free times, with the business's widget key.
  2. The gateway checks the key and the embedding page, applies the rate limit, and passes the request to the availability service for that business only.
  3. The availability service builds the free times from working hours, the synchronised busy times, holds and bookings, and returns them as UTC instants.
  4. The customer picks one. The booking service holds it for five minutes; the database refuses the hold if it overlaps another.
  5. The customer enters their details and confirms, with an idempotency key. The booking service asks the calendar connector to check that one time against the staff member's own calendar.
  6. In one transaction the booking service turns the hold into a booking and writes the events to publish (the outbox). The relay publishes them.
  7. The calendar connector writes the booking into the staff member's calendar, once; the notification worker sends the confirmation, once.
• When two customers choose the same time: the database refuses the second hold, or the second confirmation. That customer is told the time is taken and is offered the next free times at once. No messages are queued for a booking that did not happen.
• When the calendar provider is unavailable at step 5: the check cannot be made, so the booking is confirmed anyway, the skipped check is logged, and the calendar is reconciled when the provider returns. A double booking against an event the platform had not seen is possible; it is accepted deliberately (ADR-AB-0003).
• When the customer is slow: the hold can be extended up to ten times, and the customer can let it go by going back. An expired hold frees the time.

sequenceDiagram
  accTitle: Confirming a booking
  accDescr {
    The widget sends a confirmation with an idempotency key. The booking service asks the calendar connector to check that one time against the staff member's own calendar. If the provider answers, the booking proceeds or is refused; if it cannot be reached the check is recorded as skipped and the booking proceeds. The booking and its outbox rows are written in one transaction and the widget is told it is confirmed. The outbox is relayed to the calendar connector, which writes the event once, and to the notification worker, which sends the confirmation once.
  }

  participant W as Booking widget
  participant G as API gateway
  participant B as Booking service
  participant S as Booking store
  participant K as Calendar connector
  participant P as Calendar provider
  participant N as Notification worker

  W->>G: POST confirm (Idempotency-Key)
  G->>B: confirm the hold
  B->>K: live check of this one time
  K->>P: is the time still free?
  alt provider answers
    P-->>K: free or busy
    K-->>B: free, or conflict
  else provider unavailable
    K-->>B: not checked (logged)
  end
  alt conflict
    B-->>W: 409, with the next free times
  else free, or not checked
    B->>S: booking and outbox rows, one transaction
    B-->>W: confirmed
    S-->>K: BookingConfirmed (outbox relay)
    K->>P: write the event, once
    S-->>N: BookingConfirmed (outbox relay)
    N->>N: send the confirmation, once
  end

A staff member's calendar changes

• Trigger: a staff member adds, moves or removes an appointment in their own calendar.
• Normal path:
  1. The provider sends a change notification to the platform.
  2. The calendar connector treats it as "something changed", asks the provider for the current state of that calendar, and replaces the stored busy times.
  3. The next search no longer offers the overlapping times, within 60 seconds.
• When a notification is lost, or the subscription has lapsed: the connector renews each subscription when less than a day of it remains. A subscription that lapses anyway raises an alert, is created again, and the calendar is re-synchronised in full. A full re-synchronisation also runs every 24 hours as the safety net.
• When the provider is unreachable: the connector retries with growing delays, and asks the provider once a minute whether it is back. When it answers, the calendar is re-synchronised and pending writes retried at once, so no one waits out a long delay.

sequenceDiagram
  accTitle: A staff calendar changes
  accDescr {
    A staff member changes their calendar. The provider notifies the connector, which asks the provider for the calendar's current state and replaces the stored busy times. The next search no longer offers the overlapping times. If the provider cannot be reached the connector retries with growing delays, asks once a minute whether it is back, and re-synchronises in full when it answers. A subscription is renewed when less than a day remains; if one lapses, the connector raises an alert, subscribes again and re-synchronises in full.
  }

  actor U as Staff member
  participant P as Calendar provider
  participant K as Calendar connector
  participant S as Booking store

  U->>P: add an appointment
  P->>K: change notification
  K->>P: delta query for the current state
  alt the provider answers
    P-->>K: current busy times
    K->>S: replace the busy times
    Note over K,S: the next search no longer offers the overlapping times, within 60 seconds
  else the provider cannot be reached
    K->>K: retry with growing delays, and ask once a minute whether it is back
    K->>S: re-synchronise in full when it answers
  end
  opt less than a day of the subscription is left
    K->>P: renew the subscription
  end
  opt the subscription lapsed anyway
    K->>K: alert, subscribe again, re-synchronise in full
  end

A booking changes while the messaging provider is down

• Trigger: a customer cancels, or reschedules, a booking.
• Normal path: the change and its events are committed together; the relay publishes them; the notification worker sends a message for each, keyed by event and channel so a repeat sends nothing.
• When the messaging provider is down: the booking change still succeeds. Messages wait in the queue and are retried; each is given up on only 24 hours after it was due. When the provider returns, the queue drains, a cancellation replaces any confirmation not yet sent, and a reminder whose time has passed is dropped rather than sent late.

sequenceDiagram
  accTitle: A booking changes while the messaging provider is down
  accDescr {
    A customer cancels a booking. The change and its events are committed together and relayed to the notification worker. While the messaging provider is down the worker retries with growing delays for up to 24 hours from when the message was due, and then dead-letters the message and raises an alert. If the provider returns in time the queue drains, a cancellation replaces any confirmation not yet sent, and a reminder whose time has passed is dropped.
  }

  participant B as Booking service
  participant S as Booking store
  participant N as Notification worker
  participant M as Messaging provider

  B->>S: cancel, with its events (one transaction)
  S-->>N: BookingCancelled (outbox relay)
  N->>M: send the cancellation
  alt the provider accepts
    M-->>N: accepted
  else the provider is down
    M--xN: unavailable
    loop retry with growing delays, up to 24 hours from due
      N->>M: send again
    end
    alt the provider returns in time
      M-->>N: accepted when it returns
      Note over N,M: an unsent confirmation is replaced by the cancellation, and a reminder whose time has passed is dropped
    else still failing 24 hours after it was due
      N->>N: dead-letter the message and alert
    end
  end

4.5 Alignment with the Reference Architectures

A reference architecture belongs to a domain, not to one system, so this system is placed on the site's enterprise-level Integration and Data Platform reference architectures, by their component ids.

Gaps. The availability and booking services are applications rather than integration or data capabilities, so the reference architectures place them only as producers.

5. Integration & Interface Design

5.1 Integration Patterns Used

5.2 API Specifications & Contracts

6. Data Architecture

6.1 Data Model / Schema

6.2 Data Storage Technology Map

6.3 Data Lifecycle & Security

• Personal information: customer name, email and mobile number, collected to confirm and remind; shared only with the booked business and, for delivery, the messaging provider.
• Retention: bookings and contact details are deleted 24 months after the appointment; past busy intervals nightly; message records after 12 months, without bodies.
• Residency: stored in Australia.
• Encryption: at rest by the database and secrets manager; in transit with TLS 1.2 or later everywhere.
• Isolation: row-level security by business on every table (ADR-AB-0005), tested on every build.

7. Security & Compliance Controls

7.1 Authentication & Authorization

• Customers don't sign in. Booking is authorised by the business's widget key plus a registered-origin check; changing a booking needs the per-booking token from the confirmation message.
• Business administrators sign in to the admin console with an identity provider, with multi-factor authentication required.
• Staff calendars are connected by each staff member through OAuth 2.0 consent, with the narrowest scopes each provider offers.
• Services authenticate to each other with workload identity, never shared secrets.

7.2 Network Security

• Only the API gateway and the admin console are reachable from the internet.
• Services, the database and the event stream sit in private networks; outbound calls to providers leave through a controlled egress.
• The widget sets a strict Content Security Policy inside its frame, and validates the origin of every message it exchanges with the loader.

7.3 Threat Model & Mitigation

8. Deployment & Infrastructure

8.1 Target Environment Specifications

8.2 Disaster Recovery (DR) & Business Continuity

9. Cross-cutting Concerns

10. Risks, Assumptions & Technical Debt

11. Glossary