Architectural viewpoints¶
What is the point unless you are understood?¶
You can produce a technically perfect architecture. If nobody understands it, it is worthless.
This is the trap that architects fall into. They do the work, gather the detail, arrive at good answers — and then communicate it in a way that lands with nobody. The result is hesitation to report back, presentations that generate no confidence, and decisions that get made without the architecture being properly considered.
The job of the architect is not just to find the right answer. It is to navigate a complex problem, identify potential solutions, remove confusion for stakeholders, and give a path or options forward. Communication is not the last step. It runs through everything.
Know your stakeholders¶
Before choosing a viewpoint, know who you are talking to.
A stakeholder is anyone with an interest, right, share, or claim in what you are building. That is a broader definition than most people assume. It is not just the business sponsor. It includes everyone who needs to understand, decide on, operate, or live with the result.
In this bank, your stakeholders will include:
- Business users and product owners
- Business and technology sponsors
- Senior management and executives
- Project managers and business analysts
- Developers and engineers
- Security, network, and infrastructure engineers
- Data engineers and data scientists
- Risk and compliance
- UX designers
- IT support
- Other architects
One picture cannot communicate everything to everyone. That list speaks different languages. An executive needs to understand the business impact and the risk. A developer needs to understand the interfaces and the data flows. A compliance officer needs to understand the control points and the audit trail. Trying to serve all of them with a single diagram produces a diagram that serves none of them.
Viewpoints are the solution. Rather than one document that satisfies nobody, you create multiple views — each targeted at a specific stakeholder or concern — that together tell the complete story.
What to use and when¶
Viewpoints typically move from high level to lower level. You start with the enterprise view — the big picture for the people who need to understand context and direction — and work down to the details that engineers and operators need.
Not all viewpoints are required for every solution. A small, self-contained change might need only a system view and a deployment view. A new system domain needs the full set. A major cross-cutting change needs current and future views for most of them. Use judgment — too many viewpoints is as unhelpful as too few.
When a solution involves a change to something that already exists, you will usually need both a Current view and a Future view. The gap between them is where the project lives. Getting that gap right — what changes, what does not, in what order — is often where the most valuable architectural work happens.
Composition of a viewpoint¶
Mostly a viewpoint is a picture. A diagram communicates a complex concept faster than a paragraph and stays in the audience's mind longer. The diagram should be self-explanatory. Words in the document provide context and clarification, but the diagram does the heavy lifting.
Some viewpoints are better as tables or text — particularly lower-level detail like network configurations or security control lists where the structure of a table communicates more clearly than a diagram would.
The format follows the audience. What does this stakeholder need to understand, decide, or do? Start there, and work backward to the most effective way to communicate it.
It is not all about the architect¶
As viewpoints move from high level to lower level, other members of the delivery team can and should contribute.
A deployment viewpoint may be better produced by a developer or infrastructure engineer who knows the deployment environment in detail. An operational viewpoint may be better produced by a business analyst who understands the operational processes. A security viewpoint may be better contributed to by the security engineer.
The architect owns the overall narrative and ensures the views are consistent with each other. But the architect does not have to produce every diagram personally. That becomes a bottleneck and often produces lower-quality output than the person closest to the detail would produce.
Caveats¶
Not all viewpoints are applicable to every solution. Do not produce a viewpoint for completeness — produce it because the stakeholder needs it.
A viewpoint that nobody reads is waste. A viewpoint that a stakeholder reads and does not understand is worse than waste — it creates false confidence. Every viewpoint produced should have a clear intended audience and a clear question it is answering for that audience.
The viewpoint set¶
Primary viewpoints¶
These are the viewpoints produced for most significant solutions. They form the core of any architecture deliverable.
Enterprise viewpoint¶
Audience: Executives, senior management, business sponsors, board
What it answers: What are we building, why are we building it, and how does it fit into the business?
Level: High. No technical detail. Business context only.
The enterprise viewpoint is the first thing an executive sees. It must convey the business purpose, the strategic fit, the key capabilities delivered, and the major dependencies — without requiring any technical knowledge to understand.
In this bank, an enterprise viewpoint would show the bank's products, the customers it serves, the regulatory environment it operates in, and how the platform enables the business. It does not show Postgres, Kafka, or Snowflake. It might show "real-time ledger," "automated compliance," and "cross-border payments" as capabilities.
Format: Usually a single-page diagram with minimal text. Context diagram or capability map. No swim lanes, no sequence flows, no technical notation.
Current and future: When presenting a change, show where the business is today and where it will be after the change. The business case lives in the gap between them.
Functional viewpoint¶
Audience: Product owners, business analysts, business sponsors, senior engineers
What it answers: What does the system do? What are the functional capabilities and how do they relate to each other?
Level: Medium. Functional, not technical. Shows capabilities, not implementations.
The functional viewpoint describes what the system does in terms that a non-engineer can understand. It maps capabilities to business domains and shows the relationships between them. It is the bridge between the enterprise view and the system view.
In this bank, a functional viewpoint for onboarding would show: identity capture, eIDV verification, CDD tier assignment, sanctions screening, risk decision, account activation. Not the modules. Not the database tables. The functions.
Format: Functional decomposition diagram or capability map. Can include swim lanes for processes that cross domain boundaries.
System viewpoint¶
Audience: Engineers, technical architects, technical leads, senior developers
What it answers: How is the system structured? What are the components, and how do they interact?
Level: Technical. Shows systems, services, APIs, and the key data flows between them.
The system viewpoint is the primary reference for engineers building the system. It shows the components that exist, the interfaces between them, and the data that flows through those interfaces. It is technical but not implementation-level — it does not show code structure or database schemas.
In this bank, a system viewpoint shows Postgres, Kafka, Snowflake, the API gateway, and the application — with the data flows and event topics between them. It shows which service owns which data and which services consume events from which topics. See platform-overview.md and data-architecture.md for the current system viewpoint of the platform.
Format: Component diagram or C4-style system context and container diagram. APIs and events labelled on connectors.
Current and future: Essential when adding a new service or changing an existing integration. The current view shows what exists; the future view shows what changes.
Information viewpoint¶
Audience: Data engineers, data architects, compliance, risk, technical architects
What it answers: What data exists in the system? Where does it live, how does it flow, and how is it governed?
Level: Technical but data-focused. Schema-level detail is appropriate here.
The information viewpoint covers data structures, data flows, data ownership, and data governance. In a bank, this is a critical viewpoint — the data architecture underpins everything from the ledger to the regulatory returns to the ML models.
In this bank, an information viewpoint for the transaction lifecycle would show: the ledger_entries table structure, the Kafka topic schema, the Snowflake dynamic table structure, and the write-back pattern to Postgres. It would show which fields are PII, who owns each data element, and what the retention period is. See data-architecture.md for the current information viewpoint of the platform.
Format: Data flow diagram, entity-relationship diagram (ERD for schema-level), or data lineage diagram. Can include a table of data elements with classification and ownership.
Infrastructure viewpoints¶
Infrastructure viewpoints cover the physical and operational reality of how the system runs. There are four distinct sub-views, each with a different audience.
Network viewpoint¶
Audience: Network engineers, infrastructure engineers, security engineers
What it answers: How does traffic flow through the network? What are the network boundaries, security zones, and connectivity requirements?
Shows network topology, security zones, firewall rules, VPC structure, load balancers, and connectivity to external services. In this bank: AWS regions, VPC structure, private subnets for Postgres and Kafka, public subnets for the API gateway, connectivity to payment partners and identity providers.
Format: Network diagram with security zones clearly delineated.
Security viewpoint¶
Audience: Security engineers, compliance, risk, auditors
What it answers: How is the system secured? What are the trust boundaries, authentication mechanisms, and control points?
Shows authentication and authorisation flows, trust boundaries between components, secrets management, encryption boundaries, and the audit trail. In this bank: zero-trust between services, JWT authentication at the API gateway, PAM for production access, vault for secrets, immutable audit log. See security-architecture.md for the current security viewpoint of the platform.
Format: Security architecture diagram or trust boundary diagram. Can include a controls table for compliance purposes.
Deployment viewpoint¶
Audience: Developers, DevOps engineers, infrastructure engineers
What it answers: How is the system deployed? What environments exist, and what is the deployment pipeline?
Shows the deployment topology — containers, pods, infrastructure-as-code, CI/CD pipeline, environment progression from development to production. In this bank: AWS infrastructure, Terraform, GitHub Actions, environment promotion from dev to staging to production, database migration approach.
Format: Deployment diagram or pipeline diagram. Can be produced by the engineering team rather than the architect.
Operational viewpoint¶
Audience: IT support, operations, business analysts, on-call engineers
What it answers: How is the system operated day-to-day? What does normal look like, and what happens when things go wrong?
Shows monitoring and alerting, runbook structure, escalation paths, health check endpoints, and the key operational metrics. In this bank: structured logging to SIEM, distributed tracing, Snowflake dashboards for capital and liquidity, on-call runbooks, the 2am test (see AP-009).
Format: Can be a diagram, but is often better as a structured document or table. Runbooks are separate documents referenced from here.
Other viewpoints¶
These viewpoints are created when the scenario demands them. They are not part of the standard set but are important when they are relevant.
Concurrent viewpoint¶
Audience: Engineers, performance engineers, technical architects
What it answers: How does the system behave when multiple things happen at the same time? What are the concurrency, locking, and race condition risks?
Important for high-throughput payment processing, ledger posting under load, and any system where concurrent writes to shared state could cause correctness problems.
Context viewpoint¶
Audience: New team members, external parties, integration partners
What it answers: Where does this system sit in the wider landscape? What are its external dependencies and interfaces?
A simple diagram showing the system in its context — what it talks to and what talks to it. Often the first diagram produced for a new system, before the internal detail is known.
Development viewpoint¶
Audience: Developers, tech leads
What it answers: How is the codebase structured? What are the development conventions, repository layout, and build process?
Lower level than a system viewpoint — covers the internal code structure, module organisation, and development workflow. Often produced by the tech lead rather than the architect.
Finance viewpoint¶
Audience: CFO, finance team, business sponsors
What it answers: What does this cost? What is the total cost of ownership and the cost model at scale?
Covers infrastructure cost, licensing cost, build cost, and ongoing operational cost. Includes the cost curve at different volumes. In this bank: AWS costs by service, Snowflake compute costs, payment partner transaction fees. Relates directly to AP-006 (Cost effective).
Stakeholder to viewpoint mapping¶
Use this as a starting point. The author decides which viewpoints a given stakeholder actually needs for the specific solution being communicated.
| Stakeholder | Likely viewpoints needed |
|---|---|
| Executives / board | Enterprise, Finance |
| Business sponsors | Enterprise, Functional, Finance |
| Product owners | Functional, System (overview) |
| Risk & compliance | Security, Information, Functional, Operational |
| Business analysts | Functional, Operational |
| Technical architects | All |
| Senior engineers | System, Information, Deployment, Concurrent |
| Developers | System, Development, Deployment |
| Data engineers | Information, System |
| Security engineers | Security, Network, Information |
| Infrastructure engineers | Network, Deployment, Operational |
| IT support / operations | Operational, Security |
| Auditors | Security, Information, Operational |
| Regulators (RBNZ/APRA) | Enterprise, Functional, Security, Information |
| Payment partners | Context, System (integration boundary only) |
Producing viewpoints for this bank¶
Every significant architectural decision in this wiki should have the relevant viewpoints documented. As the platform is built out, the viewpoints for each system domain are added to the relevant pages under systems/SD0N-[name]/.
The standard set for a new system domain is: Functional, System, Information, Deployment, and Security. Enterprise and Operational are added when the domain-level content warrants it.
When a module changes something significant, update the affected viewpoints. A change to the data schema needs the Information viewpoint updated. A new external integration needs the System viewpoint updated. A change to the deployment topology needs the Deployment viewpoint updated.
Viewpoints are living documents. They reflect the current state of the architecture, not the state at the time they were first produced.
Relationship to perspectives and principles¶
Viewpoints are descriptive — they communicate the architecture to stakeholders.
Perspectives are evaluative — they assess whether the architecture is good.
Principles are normative — they govern how the architecture should be built.
All three work together. A viewpoint shows the architecture as it is. A perspective tells you whether it is good. A principle tells you whether it was built the right way.