Technical enablement · 01

Architecture overview

How {{product.name}} is put together: the system context, its main components, where data lives, how it connects to other systems, and the security and non-functional properties an architect needs to assess. Start here, then drill into the components catalogue and deployment models.

💡

Template guidance. This page is a skeleton. Replace the example boxes, tables and prompts with {{product.name}}'s real design. Keep each section short, link to source (repo paths, ADRs, runbooks) rather than copying it, and date any diagram that may drift. Delete this callout when done.

Executive summary

[Replace: three to five sentences. What {{product.name}} is, the architectural style (for example modular monolith, microservices, event-driven), the primary runtime platform, and the two or three decisions that most shape the design.]

Attribute	Summary
Architectural style	[Replace: e.g. services behind an API gateway, shared platform library]
Primary runtime	[Replace: cloud, container platform, serverless]
Tenancy model	[Replace: shared multi-tenant, dedicated per client, hybrid]
Key technologies	[Replace: languages, frameworks, data stores, AI/ML services]
Source of truth	[Replace: repository link and ADR index]

System context

The context diagram shows {{product.name}} as a single box surrounded by the people and systems it interacts with. Draw it first; every other diagram zooms into it.

Figure 1 — System context scaffold. Replace the placeholder boxes with real actors and external systems; label every arrow with protocol and direction.

Components

Break the product into deployable units. For each, state its single responsibility, its runtime and who owns it. Per-component detail belongs in the components catalogue; this table is the map.

Component	Responsibility	Runtime	Owner
Web client	User interface; talks only to the API gateway.	[Replace: framework, hosting]	[Replace: team]
API gateway	TLS termination, authentication, rate limiting, routing.	[Replace: gateway product]	[Replace: team]
Core service	Business logic and orchestration of the product's main workflows.	[Replace: language, container]	[Replace: team]
Worker / scheduler	Background jobs, ingestion, batch processing.	[Replace: queue or scheduler]	[Replace: team]
Shared platform library	Cross-cutting concerns: auth context, logging, telemetry, client SDKs.	[Replace: package]	[Replace: team]

Request lifecycle

Describe one representative request end to end. A short numbered list is usually enough; add a sequence diagram if the flow crosses more than three components.

Client request enters the gateway

The gateway validates the token, resolves the tenant and applies rate limits. [Replace: headers and claims used.]
Service executes the use case

The core service reads and writes through the data tier, calling downstream services or third parties as needed. [Replace: sync versus async behaviour, timeouts, retries.]
Response and telemetry

The result returns to the client; logs, metrics and traces are emitted with a correlation id.

Data tiers

Show where each kind of data lives, how it moves between tiers, and the retention and classification rules that apply.

Tier	Purpose	Technology	Retention / classification
Transactional store	System of record for application state.	[Replace: relational DB]	[Replace: retention, classification]
Analytical store	Aggregated or curated data for reporting and models.	[Replace: warehouse / lakehouse]	[Replace]
Object storage	Files, documents, generated artefacts.	[Replace: blob store]	[Replace]
Cache / queue	Ephemeral state, rate limits, job queues.	[Replace]	Non-durable; rebuildable.
Secrets store	Credentials and keys, never in code or config.	[Replace: vault]	Rotated per policy.

⚠

Regulated data. If {{product.name}} stores personal, health, payment or other regulated data, record it in the table above and involve the Data Privacy Officer before go-live. Do not paste client data into these pages.

Integration points

List every interface that crosses the product boundary. Detail on swapping providers lives in Integrations.

Interface	Direction	Protocol	Auth	Failure behaviour
Public REST API	Inbound	HTTPS / JSON	[Replace: OAuth2, API key]	Standard error envelope; idempotent retries.
Identity provider	Outbound	OIDC / SAML	Client credentials	[Replace: cached keys, grace period]
Third-party service A	Outbound	[Replace]	[Replace]	Circuit breaker; degrade gracefully.
Event / webhook feed	Outbound	HTTPS webhook / queue	Signed payloads	At-least-once; dead-letter queue.

Security & tenancy

Summarise the controls; link to the formal security documentation and to the Information Security team for approvals. This page is orientation, not a compliance statement.

Concern	Approach
Authentication	[Replace: SSO / OIDC, token lifetimes, service-to-service auth]
Authorisation	[Replace: roles, scopes, row-level policies]
Tenant isolation	[Replace: shared schema with row-level security, schema-per-tenant, or dedicated stack]
Encryption	TLS in transit; [Replace: at-rest encryption and key management]
Secrets	Held in a managed secret store; injected at runtime.
Audit logging	[Replace: what is logged, where, retention]
Supply chain	[Replace: dependency scanning, image signing, SBOM]

❗

Tenant isolation is the highest-impact control in a multi-tenant product. Document exactly where the tenant identifier is bound, which layer enforces it, and how it is tested.

Non-functional requirements

State targets, how they are measured and where the evidence lives. Remove rows that do not apply.

Quality	Target	How measured
Availability	[Replace: e.g. 99.5% monthly]	[Replace: uptime monitor]
Latency	[Replace: p95 per key endpoint]	[Replace: tracing / APM]
Scalability	[Replace: tenants, users, request volume]	[Replace: load tests]
Recovery	[Replace: RPO / RTO]	[Replace: DR exercise date]
Accessibility	[Replace: WCAG level]	[Replace: audit]
Cost	[Replace: unit-cost envelope]	See Operations: cost.

Key decisions & open risks

ADR index (template)

ADR-001  [Replace: decision title]        Status: Accepted   Date: [Replace]
ADR-002  [Replace: decision title]        Status: Proposed   Date: [Replace]
Risk-01  [Replace: risk and mitigation]   Owner: [Replace]

ⓘ

Next: the components catalogue and the deployment models.