Software Architecture Document: [System name]
Software architecture document (SAD) organised around Philippe
Kruchten's "4+1" view model: logical, process, development and physical
views, tied together and validated by a set of scenarios. Replace every
[bracketed] value and every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [SAD-SYSTEM-001] |
| System | [System name] |
| Release described | [vX.Y] |
| Version | [0.1] |
| Status | [Draft / In review / Approved] |
| Architect / owner | [@architect] |
| Classification | [Internal / Confidential / Public] |
| Last updated | YYYY-MM-DD |
Approvals
| Role | Name | Decision | Date |
|---|
| Chief architect | [@name] | [Approved / Approved with comments / Rejected] | YYYY-MM-DD |
| Development manager | [@name] | [Decision] | YYYY-MM-DD |
| Test manager | [@name] | [Decision] | YYYY-MM-DD |
| Operations manager | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.1 | YYYY-MM-DD | [@name] | Goals, constraints and scenarios |
| 0.2 | YYYY-MM-DD | [@name] | Example: Process view with concurrency model; physical view for two data centres |
| 1.0 | YYYY-MM-DD | [@name] | Example: Baseline after scenario walkthrough |
Contents
1. Introduction
1.1 Purpose
This document gives a comprehensive overview of the architecture of
[System name], using several views to describe different aspects. It
records the significant architectural decisions and is the reference for
[design, implementation, test planning and operations].
1.2 Scope
[What the document covers: the system, its release, and what is left to
other documents such as detailed designs or interface specifications.]
1.3 Views and their audiences
| View | Main concern | Primary readers | Section |
|---|
| Use-case (scenarios) | Architecturally significant behaviour | All | 3 |
| Logical | Functional decomposition, key abstractions | Analysts, designers | 4 |
| Process | Concurrency, distribution, performance, availability | Integrators, performance engineers | 5 |
| Development | Software organisation, reuse, build | Developers, managers | 6 |
| Physical | Mapping to hardware, topology, deployment | Operations, system engineers | 7 |
2. Architectural goals and constraints
2.1 Goals
| ID | Goal | Measure | Views most affected |
|---|
| AG-01 | Example: Process 500 claims per minute at peak | Throughput test | Process, physical |
| AG-02 | Example: Remain available during a single data centre outage | 99.95% monthly | Physical, process |
| AG-03 | Example: Allow three teams to release independently | Release frequency per team | Development, logical |
| [AG-nn] | [Goal] | [Measure] | [Views] |
2.2 Constraints
| ID | Constraint | Source | Views affected |
|---|
| AC-01 | Example: Must use the corporate Oracle database | IT standards | Physical, logical |
| AC-02 | Example: Personal data stays in the EU | GDPR | Physical |
| AC-03 | Example: Java 21 and the corporate CI toolchain | Engineering policy | Development |
| [AC-nn] | [Constraint] | [Source] | [Views] |
2.3 Significant architectural decisions
The decisions below shape more than one view. Each is recorded in full in
the decision log (REF-02); this table keeps the reasoning visible to
readers of the SAD.
| ID | Decision | Alternatives rejected | Goals / constraints served | Views |
|---|
| AD-001 | Example: Event-driven integration between claims and fraud scoring | Synchronous REST call from claims to fraud | AG-01 (throughput), AG-03 (independent releases) | Logical, process, development |
| AD-002 | Example: Active-passive data centres with synchronous database replication | Active-active with conflict resolution | AG-02 (availability), AC-01 (Oracle) | Physical, process |
| AD-003 | Example: Layered modules with architecture tests in the build | Convention only | AG-03 (maintainability) | Development |
| [AD-nnn] | [Decision] | [Alternatives] | [IDs] | [Views] |
3. Use-case view (scenarios)
3.1 Architecturally significant use cases
| ID | Scenario | Actor | Why significant | Exercises views |
|---|
| UC-01 | Example: Submit insurance claim with documents | Policyholder | Highest volume, touches every subsystem | All |
| UC-02 | Example: Automated fraud check | System | CPU-heavy, latency-sensitive | Process, physical |
| UC-03 | Example: Adjuster approves payout | Claims adjuster | Integrates with payment system | Logical, process |
| UC-04 | Example: Fail over to second data centre | Operations | Availability goal AG-02 | Physical, process |
| [UC-nn] | [Scenario] | [Actor] | [Reason] | [Views] |
3.2 Use-case realisation summary
[For each scenario, a few lines on how the architecture handles it, with a
reference to the sequence diagram in section 5 or the table in section 10.
Example: "UC-01: the portal uploads documents to object storage, the
claims service creates the claim and publishes ClaimSubmitted; fraud and
document services react asynchronously."]
4. Logical view
4.1 Overview
The system is decomposed into [three] layers and [five] subsystems. The
key abstractions of the claims domain are shown below.
4.2 Architecturally significant packages
| Package / subsystem | Responsibility | Key classes | Depends on |
|---|
| Example: Claims | Claim lifecycle and rules | Claim, ClaimService | Policies, Documents |
| Example: Policies | Policy lookup and coverage rules | Policy, Coverage | None |
| Example: Fraud | Scoring and explanations | FraudAssessment, RuleEngine | Claims (events only) |
| [Package] | [Responsibility] | [Classes] | [Dependencies] |
5. Process view
5.1 Processes and threads
| Process | Instances | Threads / concurrency model | Communication | Started by |
|---|
| Example: Portal web server | 4 | Event loop, non-blocking I/O | HTTPS to API gateway | Orchestrator |
| Example: Claims service | 3 | Thread pool of 200 request threads | REST in, events out | Orchestrator |
| Example: Fraud scorer | 2 to 8 | One consumer thread per partition | Consumes claims.submitted | Autoscaler |
| [Process] | [n] | [Model] | [Mechanism] | [Start] |
5.2 Interaction for UC-01 submit claim
The sequence below shows the processes involved when a policyholder
submits a claim.
5.3 Concurrency and synchronisation
[Shared resources and how access is controlled: optimistic locking on
claims (version column), idempotent event handlers keyed by event ID,
partitioning by claim ID so events for one claim are processed in order.]
5.4 Failure and recovery behaviour
Each process has a defined behaviour when it, or something it depends on,
fails. Operations uses this table to design alerts and runbooks.
| Failure | Detected by | Process behaviour | Recovery | Data at risk |
|---|
| Example: Fraud scorer down | Consumer lag alert above 5 minutes | Claims accepted; assessment delayed; adjusters see "pending score" | Autoscaler restarts pods; backlog drains | None (events retained 7 days) |
| Example: Event bus unavailable | Publish errors in claims service | Claims service writes events to outbox table and retries | Outbox relay resumes on recovery | None |
| Example: Database primary lost | Health check, replication monitor | Writes fail fast with 503; portal shows maintenance notice | Promote standby in data centre B (UC-04) | Zero with synchronous replication |
| [Failure] | [Signal] | [Behaviour] | [Recovery] | [Data] |
6. Development view
6.1 Layers
| Layer | Contents | May depend on |
|---|
| Presentation | Web portal, adjuster UI | Application |
| Application | Use-case services, API controllers | Domain, infrastructure interfaces |
| Domain | Entities, value objects, domain rules | Nothing outside the domain |
| Infrastructure | Database, messaging, external clients | Domain interfaces |
6.2 Modules and ownership
| Module / repository | Owner team | Build artefact | Release cadence |
|---|
| Example: claims-api | Team Claims | Container image | Weekly |
| Example: fraud-scorer | Team Risk | Container image | On demand |
| Example: shared-events | Platform | Library (semantic versioning) | When schemas change |
| [Module] | [Team] | [Artefact] | [Cadence] |
6.3 Development rules
[Build tools, dependency rules enforced by architecture tests, code
generation, shared libraries, and the policy for changing shared event
schemas (for example "additive changes only within a major version").]
7. Physical view
7.1 Deployment topology
The system runs in two data centres in active-passive configuration.
7.2 Nodes
| Node | Specification | Processes hosted | Count |
|---|
| Example: App node | 8 vCPU, 32 GB RAM | Portal, claims service, fraud scorer | 3 per data centre |
| Example: Database server | 32 vCPU, 256 GB RAM, SAN | Oracle | 1 per data centre |
| [Node] | [Spec] | [Processes] | [n] |
7.3 Environments
| Environment | Purpose | Topology | Data | Refresh |
|---|
| Example: Production | Live service | Two data centres as in 7.1 | Real customer data | n/a |
| Example: Pre-production | Release and failover rehearsal | Two small data centres, same topology | Masked copy of production | Monthly |
| Example: Test | Integration and performance tests | Single site | Synthetic | Per test run |
| [Environment] | [Purpose] | [Topology] | [Data] | [Refresh] |
8. Size and performance
Peak claim submission load is derived from annual volume and seasonal
peaks:
λpeak=365×8h×3600Vyear×kpeak=105120002400000×25≈5.7 claims/s | Characteristic | Target | Basis |
|---|
| Example: Claims per year | 2.4 million | Business forecast YYYY |
| Example: Peak submissions | 6 per second (storm events) | Formula above, peak factor 25 |
| Example: Claim submission latency | p95 under 2 s | AG-01 |
| Example: Document storage growth | 15 TB per year | 6 MB average per claim |
| [Characteristic] | [Target] | [Basis] |
9. Quality
| Quality attribute | Target | Architectural contribution | Views |
|---|
| Example: Availability | 99.95% monthly | Active-passive data centres, stateless app nodes, synchronous database replication | Physical, process |
| Example: Security | Personal data encrypted at rest and in transit | TLS everywhere, transparent database encryption, role-based access in claims service | Physical, logical |
| Example: Maintainability | Teams release independently | Separate modules and images, event contracts versioned | Development |
| [Attribute] | [Target] | [Contribution] | [Views] |
10. Mapping between views
10.1 Element mapping
| Logical element | Process | Development module | Physical node |
|---|
| Example: Claims package | Claims service | claims-api, claims-domain, claims-infra | App nodes |
| Example: Fraud package | Fraud scorer | fraud-scorer | App nodes |
| Example: Claim, Policy entities | Claims service (owner) | claims-domain | Oracle database |
| [Element] | [Process] | [Module] | [Node] |
10.2 Scenario walkthrough results
| Scenario | Walkthrough date | Views consistent | Issues found | Action |
|---|
| Example: UC-01 | YYYY-MM-DD | Yes | None | None |
| Example: UC-04 | YYYY-MM-DD | No | Event bus has no standby in data centre B | AD-007 opened |
| [UC-nn] | YYYY-MM-DD | [Yes / No] | [Issues] | [Action] |
11. Glossary and references
11.1 Glossary
| Term | Meaning |
|---|
| View | A description of the system from one perspective, for one set of concerns |
| Scenario | A sequence of interactions used to drive and validate the architecture |
| Process | A group of tasks forming an executable unit, possibly distributed |
| [Term] | [Meaning] |
11.2 References
| ID | Document | Version |
|---|
| REF-01 | [Requirements specification] | [x.y] |
| REF-02 | [Architecture decision log] | [Location] |
| REF-03 | Kruchten, P., "Architectural Blueprints: The 4+1 View Model of Software Architecture", IEEE Software 12(6), 1995 | 1995 |
Standard and licence note
Based on the "4+1" view model of software architecture described by
Philippe Kruchten (IEEE Software, 1995): logical, process, development and
physical views, plus scenarios that tie them together. This template is
original text written for this collection and reproduces no text from the
paper. Template licence: MIT.