Reference Architecture: [Domain or solution type]
Specification of a reference architecture: a reusable, approved
blueprint that solution teams instantiate for a recurring kind of
system. It covers purpose and applicability, drivers, principles,
architecture and solution building blocks, patterns with selection
rules, standard views, technology standards, conformance rules and how
compliance is assessed, variation points, instantiation examples and
governance. The description structure is aligned with the concepts of
ISO/IEC/IEEE 42010:2022 (stakeholders, concerns, viewpoints, views) and
uses the building block concepts of the TOGAF Standard, 10th Edition.
Replace every [bracketed] value and every row marked Example.
Document control
| Field | Value |
|---|
| Document ID | [RA-WEB-001] |
| Reference architecture name | [Customer-facing web service] |
| Version | [1.0] |
| Status | [Draft / Approved / Deprecated / Retired] |
| Owner | [@reference-architecture-owner] |
| Approvers / reviewers | [@architecture-board, @security-architect, @platform-lead] |
| Supported until | YYYY-MM-DD (or "until next major version plus 12 months") |
| Applies to | [Business units, environments, system types] |
| Last updated | YYYY-MM-DD |
| Classification | [Internal] |
Approvals
| Role | Name | Decision | Date |
|---|
| Architecture board chair | [@name] | [Approved / Approved with comments / Rejected] | YYYY-MM-DD |
| Security architect | [@name] | [Decision] | YYYY-MM-DD |
| Platform engineering lead | [@name] | [Decision] | YYYY-MM-DD |
| Representative adopting team | [@name] | [Decision] | YYYY-MM-DD |
Revision history
| Version | Date | Author | Change summary |
|---|
| 0.9 | YYYY-MM-DD | [@name] | Draft for review with two pilot teams |
| 1.0 | YYYY-MM-DD | [@name] | Example: Approved; conformance rules RA-CR-01 to RA-CR-10 mandatory |
| 1.1 | YYYY-MM-DD | [@name] | Example: Document store guidance added to PAT-SEL-03 and VAR-02 after INST-02 |
Contents
1. Purpose and applicability
1.1 Purpose
This reference architecture defines the approved way to build and run
[customer-facing web services] at [Organisation]. It exists so that
teams [start faster from proven building blocks, meet security and
reliability baselines by default, and stay operable by the platform
team], and so that reviewers can assess designs against one stated
baseline.
1.2 When to use it
| Condition | Applies |
|---|
| Example: New or substantially rebuilt service with a browser or mobile front end used by customers | Yes, mandatory |
| Example: Internal tool used only by staff | Recommended; conformance rules marked "Customer only" do not apply |
| Example: Batch or analytics workload with no interactive users | No; use [RA-DATA-001] |
| Example: Vendor SaaS configured but not built | No; use the SaaS onboarding standard |
| [Condition] | [Yes, mandatory / Recommended / No] |
1.3 Out of scope
[Mainframe workloads, edge devices, data platform pipelines, and
anything covered by another reference architecture such as [RA-DATA-001].]
2. Context and drivers
2.1 Business and technical context
[Two paragraphs: how many teams build this kind of system, what went
wrong without a common blueprint (for example inconsistent
authentication, unobservable services, duplicated platform work), and
which enterprise strategy or principles this reference architecture
implements.]
2.2 Drivers
| ID | Driver | Type | Source |
|---|
| DRV-01 (Example) | Reduce time from idea to first production release for new services | Business goal | Engineering strategy (dev/engineering-strategy) |
| DRV-02 (Example) | Every customer-facing service meets the security baseline before launch | Quality (security) | Security architecture standard |
| DRV-03 (Example) | Availability target of 99.9 percent per month for tier 1 services | Quality (availability) | Service tiering policy |
| DRV-04 (Example) | Run on the company container platform in two regions | Constraint | Infrastructure strategy |
| DRV-05 (Example) | Personal data stays in approved regions | Constraint (regulatory) | Data protection policy |
| [DRV-nn] | [Driver] | [Goal / Quality / Constraint] | [Source] |
3. Stakeholders, concerns and viewpoints
| ID | Stakeholder | Main concerns | Viewpoints used |
|---|
| SH-01 (Example) | Solution architects | Which building blocks to use, what may vary | VP-01, VP-02 |
| SH-02 (Example) | Development teams | How to structure code and interfaces | VP-02, VP-04 |
| SH-03 (Example) | Platform and SRE teams | Deployment, operations, observability | VP-03 |
| SH-04 (Example) | Security architects | Trust boundaries, identity, data protection | VP-01, VP-03, VP-04 |
| SH-05 (Example) | Architecture board | Conformance and exceptions | All |
| [SH-nn] | [Stakeholder] | [Concerns] | [VP IDs] |
| ID | Viewpoint | Concerns framed | Model kinds |
|---|
| VP-01 | Context | Scope, actors, external dependencies, trust boundaries | Context diagram |
| VP-02 | Logical structure | Building blocks and their responsibilities | Component diagram, building block table |
| VP-03 | Deployment | Runtime placement, regions, resilience | Deployment diagram |
| VP-04 | Behaviour | Key interactions, failure handling | Sequence diagram |
4. Architecture principles
Principles are taken from the Architecture Principles Catalogue
(architecture/architecture-principles) unless marked "RA-specific".
| ID | Principle | Origin | Implication in this reference architecture |
|---|
| PR-01 (Example) | Secure by default | Enterprise | Building blocks ship with authentication, encryption and logging on; teams cannot switch them off without an exception |
| PR-02 (Example) | Stateless services, state in managed stores | RA-specific | Service instances hold no session state; any instance can serve any request |
| PR-03 (Example) | Contract-first interfaces | Enterprise | Every API is described before implementation and versioned |
| PR-04 (Example) | Observable by design | Enterprise | Every service emits traces, metrics and structured logs in the standard format |
| PR-05 (Example) | Prefer managed platform services | Enterprise | Use the platform's database, queue and cache offerings before self-hosting |
| PR-06 (Example) | Asynchronous by default across team boundaries | RA-specific | Cross-domain side effects use events, not synchronous chains |
| [PR-nn] | [Principle] | [Enterprise / RA-specific] | [Implication] |
5. Building blocks
5.1 Architecture building blocks
| ID | Architecture building block | Responsibility | Mandatory | Key interfaces |
|---|
| ABB-01 (Example) | Edge entry | Terminate TLS, route requests, apply rate limits and web application firewall rules | Yes | HTTPS from clients |
| ABB-02 (Example) | Identity and access | Authenticate users and services, issue and validate tokens | Yes | OpenID Connect, OAuth 2.0 |
| ABB-03 (Example) | Web front end | Deliver the user interface | Yes (for UI services) | HTTPS to ABB-04 |
| ABB-04 (Example) | Service API | Business logic exposed through a versioned API | Yes | HTTP API, events |
| ABB-05 (Example) | Operational data store | Durable transactional storage for the service's own data | Yes | Database protocol |
| ABB-06 (Example) | Cache | Low-latency reads for hot data | Optional | Cache protocol |
| ABB-07 (Example) | Messaging | Asynchronous commands and events between services | Optional (mandatory for PR-06 cases) | Queue or topic |
| ABB-08 (Example) | Observability | Collect and query traces, metrics and logs | Yes | Telemetry export |
| ABB-09 (Example) | Secrets management | Store and rotate credentials and keys | Yes | Secrets API |
| ABB-10 (Example) | Delivery pipeline | Build, test, scan and deploy | Yes | Source repository, registry |
| [ABB-nn] | [Name] | [Responsibility] | [Yes / Optional] | [Interfaces] |
5.2 Solution building blocks
| ID | Realises | Solution building block | Status | Notes |
|---|
| SBB-01 (Example) | ABB-01 | [Platform API gateway with managed WAF] | Standard | Provisioned through the golden path |
| SBB-02 (Example) | ABB-02 | [Company identity provider] | Standard | Only approved issuer |
| SBB-03 (Example) | ABB-05 | [Managed PostgreSQL] | Standard | Default choice |
| SBB-04 (Example) | ABB-05 | [Managed document database] | Option | Use only per selection rule PAT-SEL-03 |
| SBB-05 (Example) | ABB-06 | [Managed in-memory cache] | Option | |
| SBB-06 (Example) | ABB-07 | [Managed message broker] | Standard | |
| SBB-07 (Example) | ABB-08 | [OpenTelemetry SDK plus platform collector] | Standard | Standard telemetry format |
| SBB-08 (Example) | ABB-10 | [Platform pipeline templates] | Standard | See Platform Golden Path (architecture/platform-golden-path) |
| [SBB-nn] | [ABB ID] | [Product or service] | [Standard / Option / Deprecated] | [Notes] |
6. Patterns and selection rules
6.1 Endorsed patterns
| ID | Pattern | Problem it solves | Consequences |
|---|
| PAT-01 (Example) | Backend for front end | Different clients need different API shapes | One more component per client type; simpler clients |
| PAT-02 (Example) | Transactional outbox | Publish events reliably with a database change | Requires an outbox relay; avoids dual writes |
| PAT-03 (Example) | Cache-aside | Read-heavy data with tolerance for short staleness | Cache invalidation rules needed |
| PAT-04 (Example) | Circuit breaker with fallback | Slow or failing dependencies | Degraded responses must be designed |
| PAT-05 (Example) | Strangler fig | Replacing a legacy system incrementally | Routing layer and dual running period |
| [PAT-nn] | [Pattern] | [Problem] | [Consequences] |
6.2 Selection rules
| ID | If | Then | Rationale |
|---|
| PAT-SEL-01 (Example) | The service changes data owned by another domain | Use events through ABB-07 with PAT-02; no direct database access | PR-06 |
| PAT-SEL-02 (Example) | Read to write ratio above an agreed level and staleness of seconds is acceptable | Add ABB-06 with PAT-03 | Performance at lower cost |
| PAT-SEL-03 (Example) | Data is document-shaped, schema varies per record, and no cross-record transactions are needed | SBB-04 may replace SBB-03 | Fit for data model |
| PAT-SEL-04 (Example) | Two or more client types with different needs | Use PAT-01 | Avoids a lowest-common-denominator API |
| PAT-SEL-05 (Example) | A synchronous dependency is outside the team's control | Apply PAT-04 and define the fallback behaviour | DRV-03 |
| [PAT-SEL-nn] | [Condition] | [Choice] | [Principle or driver] |
7. Standard views
7.1 Context view (VP-01)
The context view shows the service family as one box with its users,
the shared platform services it depends on and the trust boundaries.
7.2 Logical structure view (VP-02)
The logical view shows the building blocks inside one instantiation and
how they connect.
7.3 Deployment view (VP-03)
The deployment view shows the default runtime placement across two
regions.
7.4 Behaviour view (VP-04)
The behaviour view shows a state-changing request that publishes an
event reliably.
8. Technology standards and options
| Area | Standard | Allowed options | Not allowed | Radar ring |
|---|
| Runtime (Example) | [Company container platform] | [Serverless functions for event handlers] | Self-managed virtual machines | Adopt |
| Languages (Example) | [Java LTS, TypeScript on Node.js LTS] | [Go, with board approval] | Unsupported language versions | Adopt / Trial |
| API style (Example) | [HTTP APIs described in OpenAPI] | [gRPC for internal high-throughput calls] | Undocumented endpoints | Adopt |
| Data store (Example) | [Managed PostgreSQL] | [Managed document database per PAT-SEL-03] | Shared databases between services | Adopt |
| Telemetry (Example) | [OpenTelemetry] | | Vendor-specific agents without OpenTelemetry export | Adopt |
| [Area] | [Standard] | [Options] | [Not allowed] | [Ring] |
Technology statuses follow the Technology Radar (architecture/tech-radar).
New options enter through Technology Selection
(architecture/technology-selection) and a minor version of this
document.
9. Conformance rules and compliance assessment
9.1 Conformance rules
| ID | Rule | Level | Applies to | How it is checked |
|---|
| RA-CR-01 (Example) | All external traffic enters through ABB-01 | Mandatory | All | Platform policy blocks public endpoints elsewhere |
| RA-CR-02 (Example) | Users and services authenticate through ABB-02 only | Mandatory | All | Design review, token issuer check in pipeline |
| RA-CR-03 (Example) | No service reads or writes another service's data store | Mandatory | All | Network policy, design review |
| RA-CR-04 (Example) | Every API has a published, versioned contract | Mandatory | All | Pipeline fails without a contract file |
| RA-CR-05 (Example) | Traces, metrics and logs exported through SBB-07 | Mandatory | All | Telemetry presence check after deployment |
| RA-CR-06 (Example) | Secrets only in ABB-09; none in code or images | Mandatory | All | Secret scanning in pipeline |
| RA-CR-07 (Example) | Deployed in two regions with tested failover | Mandatory | Tier 1, Customer only | Failover test record each half-year |
| RA-CR-08 (Example) | Cross-domain side effects use events (PAT-SEL-01) | Mandatory | All | Design review |
| RA-CR-09 (Example) | Load test at expected peak before first release | Recommended | All | Test report |
| RA-CR-10 (Example) | Only SBBs with status Standard or Option | Mandatory | All | Dependency and image policy |
| [RA-CR-nn] | [Rule] | [Mandatory / Recommended] | [Scope] | [Check] |
Executable checks can be written as Fitness Functions
(architecture/fitness-functions).
9.2 Compliance assessment process
- Self-assessment: the solution team completes the checklist in 9.3
during design and links evidence.
- Design review: an architect from the reference architecture owner
team reviews the self-assessment at the design gate, using the
Architecture Review Request (
architecture/architecture-review-request).
- Automated verification: pipeline and platform checks enforce the
rules marked as automated before each production release.
- Periodic audit: [annually], a sample of instantiations is
reassessed; results feed the next version of this document.
9.3 Compliance outcomes and checklist
| Outcome | Meaning |
|---|
| Compliant | All mandatory rules met |
| Compliant with exceptions | One or more mandatory rules waived through an approved exception with an expiry date |
| Non-compliant | A mandatory rule is not met and no exception exists; the release gate blocks |
| Rule | Status | Evidence | Exception ID |
|---|
| RA-CR-01 | [Met / Not met / Not applicable] | [Link] | [EXC-nn or blank] |
| RA-CR-02 | [Status] | [Link] | [EXC-nn or blank] |
| [RA-CR-nn] | [Status] | [Link] | [EXC-nn or blank] |
9.4 Exceptions
| ID | Instantiation | Rule waived | Reason | Compensating control | Expiry | Approved by |
|---|
| EXC-01 (Example) | [Loyalty service] | RA-CR-07 | Tier 2 service; second region not justified | Backup restore tested quarterly | YYYY-MM-DD | [@board-chair] |
| [EXC-nn] | [Service] | [RA-CR ID] | [Reason] | [Control] | YYYY-MM-DD | [@approver] |
Grant exceptions as dispensations under the Architecture Board Charter
(architecture/architecture-governance-charter) and record the
dispensation ID next to the EXC ID, so that one register holds every
approved deviation.
10. Variation points
| ID | Variation point | Allowed variants | Default | Decided by | Constraint |
|---|
| VAR-01 (Example) | Front end rendering | Server-rendered, single-page application, static site with API | Server-rendered | Solution team | Must meet accessibility standard |
| VAR-02 (Example) | Data store type | SBB-03, SBB-04 | SBB-03 | Solution team per PAT-SEL-03 | One store type per service |
| VAR-03 (Example) | Caching | None, SBB-05 | None | Solution team per PAT-SEL-02 | Cache never system of record |
| VAR-04 (Example) | Regions | One region, two regions | Two regions for tier 1 | Service tier | RA-CR-07 |
| VAR-05 (Example) | Backend for front end | Present, absent | Absent | Solution team per PAT-SEL-04 | |
| [VAR-nn] | [Point] | [Variants] | [Default] | [Who decides] | [Constraint] |
11. Instantiation examples
| ID | Instantiation | Owner team | Variants chosen | Compliance outcome | Lessons for this document |
|---|
| INST-01 (Example) | [Online quote service] | [Team Quote] | VAR-01 server-rendered; VAR-02 SBB-03; VAR-03 SBB-05; VAR-04 two regions | Compliant | Selection rule PAT-SEL-02 needed a clearer threshold |
| INST-02 (Example) | [Loyalty service] | [Team Loyalty] | VAR-01 single-page application; VAR-02 SBB-04; VAR-04 one region | Compliant with exceptions (EXC-01) | Document store guidance added in v1.1 |
| [INST-nn] | [Service] | [Team] | [Variants] | [Outcome] | [Lessons] |
11.1 Traceability matrix
| Driver | Principles | Building blocks and patterns | Conformance rules |
|---|
| DRV-01 | PR-05 | ABB-10, SBB-08 | RA-CR-04, RA-CR-10 |
| DRV-02 | PR-01 | ABB-01, ABB-02, ABB-09 | RA-CR-01, RA-CR-02, RA-CR-06 |
| DRV-03 | PR-02, PR-06 | ABB-07, PAT-04 | RA-CR-07, RA-CR-08, RA-CR-09 |
| DRV-04 | PR-05 | SBB-01 to SBB-08 | RA-CR-10 |
| DRV-05 | PR-01 | ABB-05 | RA-CR-03 |
12. Governance and versioning
12.1 Ownership and change process
- Owner: [@reference-architecture-owner], accountable for content,
versions and the conformance checklist.
- Change requests: any team may propose a change through [RFC
process (
dev/rfc) or architecture board backlog]. Each change cites
the instantiations or incidents that motivate it.
- Approval: patch and minor versions by the owner with one board
member; major versions by the architecture board.
12.2 Versioning and support
| Change type | Version increment | Effect on existing instantiations |
|---|
| Clarification, no rule change | Patch (1.0.x) | None |
| New option, new recommended rule | Minor (1.x) | None; adopt at next major release |
| Changed or new mandatory rule, removed building block | Major (x.0) | Migrate within the support window |
Previous major versions stay supported for [12 months] after a new major
version. Each instantiation records the version it conforms to in its
solution architecture document.
12.3 Review cadence
[Review at least annually, after every major platform change, and when
three or more exceptions to the same rule have been approved, which
signals that the rule needs revisiting.]
13. Glossary and references
13.1 Glossary
| Term | Meaning in this document |
|---|
| Reference architecture | Generic, reusable architecture for a class of solutions, with rules for conformance |
| Architecture building block (ABB) | Technology-neutral unit of required capability |
| Solution building block (SBB) | Approved product, service or component that realises an ABB |
| Pattern | Proven solution to a recurring design problem, with known consequences |
| Variation point | Declared place where an instantiation may choose among allowed variants |
| Instantiation | A specific solution built according to this reference architecture |
| Conformance rule | Testable statement an instantiation must satisfy |
| Viewpoint, view | Conventions for a kind of view, and the view built with them |
13.2 References
- ISO/IEC/IEEE 42010:2022, Software, systems and enterprise:
Architecture description (second edition, November 2022): concepts
of stakeholder, concern, viewpoint and view.
- The Open Group, The TOGAF Standard, 10th Edition: concepts of
architecture building blocks, solution building blocks and the
Enterprise Continuum.
- Related templates: Architecture Description (
architecture/architecture-description-42010),
Solution Architecture (architecture/solution-architecture),
Architecture Principles Catalogue (architecture/architecture-principles),
Technology Radar (architecture/tech-radar), Platform Golden Path
(architecture/platform-golden-path), Fitness Functions
(architecture/fitness-functions), Architecture Governance Charter
(architecture/architecture-governance-charter), Architecture
Definition Document (architecture/architecture-definition-document).
Standard and licence note
Structure aligned with the concepts of ISO/IEC/IEEE 42010:2022
(stakeholders, concerns, viewpoints and views) and with the building
block concepts of The TOGAF Standard, 10th Edition (The Open Group).
Both are copyrighted; this template reproduces no text, definitions or
tables from them, and all wording, rules and examples are original.
Check the current official editions for their normative content. TOGAF
is a registered trademark of The Open Group.
Template licence: MIT.