How to Clearly Communicate and Evaluate Architecture: Views, Decision Records & Review Checklists

Many cement digitalization projects have a single overall architecture diagram showing devices, data platforms, and applications, but such diagrams cannot answer implementation questions like whether data comes from a historian or directly from DCS, where metric calculations run, what functions survive network outages, or which data is authoritative.

A useful architecture document must serve as a collaboration contract answering: what the system does, who is responsible, how components collaborate, where they run, what happens on failure, and how to prove the design works. If this information relies on verbal explanations, the document has not become a stable collaboration basis.

Different questions need different expression angles. Putting everything into one diagram either omits important details or becomes too complex to read. The better approach: let each diagram answer a specific set of questions, linked by common identifiers and constraints.

Views and Viewpoints: Define the Question First

Viewpoint is the rule for observing a concern (e.g., deployment viewpoint requires nodes, instances, network connections, failure scope). View is the concrete expression for a project (e.g., deployment diagram for a cement mill energy analysis system). This follows ISO/IEC/IEEE 42010, which also requires recording correspondences between views and the rationale behind choices — the latter addressed by architecture decision records.

Six Complementary Architecture Views

The article recommends six views, mapping to established models (Kruchten 4+1, Rozanski & Woods):

Business & System Context — Who uses it, system boundary. Typical content: roles, external systems, business goals.

Application & Responsibility — Which modules own which capabilities. Typical content: modules, interfaces, dependencies, responsibilities.

Data & Semantics — What data means, who publishes it. Typical content: objects, sources, versions, data flows.

Dynamic Interaction — How a task completes. Typical content: call sequences, events, states, failure paths.

Deployment & Operations — Where capabilities run, how they operate. Typical content: nodes, instances, resources, recovery mechanisms.

Security & Trust Boundaries — Who can access, which paths are controlled. Typical content: identities, permissions, zones, audit.

Small projects can merge views but must not omit the corresponding questions. Requirements, decisions, and verification plans should permeate all views, not sit isolated in appendices.

View Details with Concrete Examples

1. System Context Diagram (C4 Level 1)

Defines the system boundary. For the cement mill energy analysis case: roles (process engineer, energy manager, production manager), external systems (historian, MES, identity service), and explicit non-goals: does not modify production records, does not replace official energy accounting, does not send control commands to DCS.

2. Application View — Responsibilities Over Technology Names

Modules: Metric Calculation (rules & result versions), Deviation Assessment (reference conditions & judgment), Event Management (create/merge/confirm/close), Handling (investigation records & task linking), Evidence Query (information composition). Each module must state: what it owns, what it provides, what it depends on. Application modules ≠ deployment instances; a modular monolith can show multiple modules in application view but one deployment unit.

3. Data View — Beyond Database Arrows

Must express business meaning (meter readings, interval energy, output, energy index, deviation assessment, anomaly event, handling record) and provenance/transformation: source of raw measurements, when output is confirmed, how index is calculated, how rule versions are referenced, what re-calculation happens on historical revision. For key data, record: object ID, authoritative source, time semantics, unit & scope, quality status, version & effective rule, modification entry, downstream consumers. Distinguish source business records, synchronized copies, derived results, and display caches — presence in platform does not imply equal modification rights.

4. Dynamic View — Show Failure Paths

Use sequence, activity, or state diagrams. Example: deviation event generation — metric module reads qualified data, produces versioned result, deviation module checks product/conditions, submits assessment, event module decides create/update, user reviews evidence. Must include failure branches: missing output, unpublished rule, duplicate submission, result revision. Idempotency and versioning (covered in previous article) must appear in the diagram, not just textual conventions. Only drawing the happy path explains demos, not real operation.

5. Deployment View — Map Logic to Real Environments

Factory side runs collection & cache; factory business zone runs energy analysis app; group receives summaries & cross-factory queries. Must specify: which app instances on which node types, which storage, which paths cross network zones, which dependencies must stay online, shared resources. C4 "container" means runnable unit (app or data store), not Docker container. Non-production environments: can test verify real interfaces? Is trial data isolated? Do model experiments consume production query resources?

6. Security View — Concrete Access Relationships

Not just a perimeter "security system". Specify: can process engineer publish deviation rules? What identity does platform service use to read production data (service account, separate from human accounts)? Can ops restart app but not modify business records? Can group users access factory raw trends? For critical paths record: caller, target, allowed action, authorization basis, audit method, failure behavior. Distinguish data flow direction from connection establishment direction — an arrow "factory to group" does not prove factory initiates connection or satisfies isolation. IEC 62443 zones & conduits (covered in article 3) must be reflected.

Unified Naming & Identifiers for Cross-View Consistency

Common problem: each view looks fine alone but cannot be correlated (e.g., "Metric Service" in app view, "Analysis Node" in deployment, "Energy Calc API" in interface list). Establish stable identifiers: APP-01 Energy Analysis App, MOD-01 Metric Calculation Module, DAT-01 Confirmed Production Output, IF-01 Production Output Query Interface, NODE-01 Factory App Node, ADR-01 Local Analysis Deployment Decision. Identifiers need not be complex but relationships must stay stable. This is the correspondence relation in ISO/IEC/IEEE 42010. Practical tip: maintain element catalog and diagrams in version control using text-based tools like Structurizr DSL (architecture as code) so changing one identifier updates all diagrams. Each diagram should note: project scope, view name, version, date, owner, legend, and whether it depicts current, target, or transitional state — do not draw未建设能力和已运行能力 identically.

Cross-View Check to Detect Contradictions

Walk a scenario across all six views. Example: historical output revision triggers re-calculation. Business view: is revision allowed? Who confirms? Application view: which module receives revision and triggers re-calc? Data view: how are old/new output and index versions identified? Dynamic view: does duplicate notification cause duplicate processing? (Idempotency). Deployment view: do components have connectivity & capacity? Security view: does receiver have permission? If business doc requires history retention but DB design only allows overwrite, or if local continuous operation is promised but deployment shows calculation fully depends on group service — cross-view conflict exists. Architecture quality depends not on each diagram being correct, but on them describing the same system.

Non-Functional Requirements Back into Views, Not Slogans

"High performance, high availability, scalable" cannot guide design. Each significant requirement must map to: concrete scenario, design measure, dependency conditions, verification method. Use ISO/IEC 25010 quality characteristics and quality attribute scenarios (stimulus source, stimulus, environment, artifact, response, response measure). Example: group network down, factory must still do energy analysis. Impacts: data view (necessary data locally available), application view (calculation & event handling run locally), deployment view (necessary components deployed at factory), security view (offline authorization handling), dynamic view (post-recovery sync & deduplication), test plan (simulate outage & verify recovery). RTO/RPO (from article 2) go into response measures. Deploying an edge gateway alone does not prove offline operation — need full support chain.

Architecture Decision Records (ADR): Capture "Why"

Months later teams ask: why local calculation? Why no ML anomaly detection? Why not split event module as separate service? Final diagrams alone lose the context. ADR (Michael Nygard 2011, MADR template) records: title, status, context, decision, consequences. One record per major decision. Must let reader understand: constraints faced, alternatives compared, costs accepted.

ADR Example: ADR-01 First-Phase Energy Analysis Deployed in Factory Business Environment

Status: Proposed, awaiting network, ops, and business owner confirmation. Context: Field personnel need to view necessary data and handle anomalies during group connectivity loss. Existing data interfaces mainly at factory; group-side run conditions not yet ready. Alternatives: A) Centralized in group, factory accesses via network. B) Core analysis at factory, group receives summaries & events. Decision: Adopt B for first phase. Metric calculation, anomaly events, investigation records run at factory; group receives agreed data scope. Benefits: Reduces daily analysis dependency on group link, shortens local data access path. Accepted Costs: Must maintain factory runtime environment, adding version distribution, monitoring, data sync work. Preconditions: Local data interfaces, compute resources, auth mechanisms, recovery capabilities meet confirmed requirements. Verification: Network outage, source data interruption, recovery replay, local user operation tests. Re-assessment Triggers: Factory ops model, group network assurance, or business continuity requirements change.

The key is recording the conditions under which the decision holds, not just the conclusion.

When Decisions Change, Preserve History

Architecture evolves. Local calculation may later move to group; modular monolith may split services. Add new ADR explaining why, mark old as superseded (reference new one). Do not rewrite old doc to pretend new choice was original. History helps explain: why past versions ran that way, what to watch during migration, which constraints changed. Link decisions to affected requirements, views, tests so a decision change triggers doc updates & verification.

Reviews: Start with Scenario Walkthroughs, Not Slide Decks

Typical review: architect presents many slides, participants only comment on naming, colors, tech preferences. Better: pick key scenarios, walk through system. Aligns with SEI ATAM: use key quality attribute scenarios to drive review, check architecture support, record sensitivity & tradeoff points. Example scenarios: "Interval output missing — how does system handle?" "Metric revised — what happens to closed anomaly events?" "Group link down — can local auth still work?" "Platform accepts request but times out — user retries, what happens?" Each demands: responsible component, data state, interaction path, failure behavior, verification method. Reviewers need not memorize all modules but must check critical scenarios close.

Review Must Cover Four Scenario Categories

Normal Business Scenarios — User completes goal, business state complete.

Data Anomaly Scenarios — Missing, late, duplicate, revision, object mapping errors.

System Failure Scenarios — Service unavailable, network down, task backlog, storage full — degradation & recovery (degraded modes from article 3).

Permission & Change Scenarios — Unauthorized access, permission revocation, rule upgrade, version incompatibility.

Not all detail in first review, but high-risk issues must surface early. Avoid only checking "can it be built" without checking "can it fail, stop, recover, and explain correctly".

Review Findings as Actionable, Closable Issues

"Suggest enhance reliability" is not specific. Rewrite: "Current deployment has event handling depend on group identity service, but requirement says factory must handle during group outage. Define offline auth scope, validity period, revocation risk handling, and add tests." Each issue item: ID, linked requirements & views, specific gap/contradiction, risk & impact, owner, deadline, closure evidence (updated design, test results, or formal risk acceptance). This is standard issue tracking; undecided risks can start in risk register (probability, impact, mitigation). Closure must point to evidence, not just "modified".

Review Pass ≠ Proven Production Ready

Different phases, different conclusions: Pass — current phase requirements met. Conditional Pass — limited subsequent work allowed, but specific remediation items mandatory. Not Pass — key boundaries, risks, dependencies unresolved; proceeding risks rework or runtime risk. Conditional pass must state: what is allowed, what is not, who owns remediation, by which milestone. Example: allow interface dev, but no production connection until access path confirmed. Like stage-gate reviews with explicit entry/exit criteria. Design review approves solution & rationale; performance, recovery, permissions, business outcomes still need test & trial-run evidence. Review conclusion cannot replace operational validation.

Reusable Architecture Review Checklist

Structured in six sections:

Business & Scope

Target users & key scenarios clear?

Out-of-scope items listed?

Any business responsibility unowned?

Application & Responsibility

Each module has clear responsibility?

Unnecessary cyclic dependencies?

Independent services have real benefit & ops owner?

Data & Interfaces

Key records have authoritative source?

Modify, publish, historical revision paths clear?

Time, unit, object, version definitions consistent?

Timeout, duplicate request, partial failure handling rules?

Deployment & Operations

Each logical capability mapped to actual run location?

Capacity estimates state input assumptions?

Fault isolation, degradation, recovery verifiable?

Shared DB, network, identity services creating hidden dependencies?

Security & Permissions

Human vs service identities managed separately?

Read, write, approve, control execute distinguished?

Cross-zone access via approved paths?

Key operations traceable?

Implementation & Verification

Important requirements have verification methods?

Environments, data, external interfaces test-ready?

Migration, rollback, data compatibility planned?

Open items have owner & deadline?

Checklist prevents omissions, not a substitute for project-specific judgment. When trimming, mark removed items "N/A" with reason — deleted items are often skipped risks.

Suggested Architecture Document Structure

Aligns with ISO/IEC/IEEE 42010: stakeholders & concerns, views & models, rationale & consistency.

Project Goals & Scope: business problem, goals, non-goals.

Stakeholders & Glossary: roles, responsibilities, core concepts.

Requirements & Constraints Summary: key functions, quality attributes, assumptions, dependencies.

System Context: users, external systems, boundary.

Application & Module Design: responsibilities, interfaces, dependencies.

Data & Semantics Design: objects, sources, flows, versions, lifecycles.

Key Dynamic Scenarios: normal, anomaly, recovery paths.

Deployment & Capacity Design: run locations, resources, network dependencies.

Security & Permission Design: identities, authorization, trust boundaries, audit.

Architecture Decision Records: major choices, alternatives, consequences.

Implementation & Verification Plan: migration, test, trial run, acceptance.

Risks & Action Items: issues, owners, deadlines, closure criteria.

Large interface specs, field definitions, test cases can live separately, linked by identifiers. Core requirement: information findable, relationships traceable, versions aligned.

Keep Architecture Docs Evolving with the System

Most common failure: docs written once, never updated after go-live. Define explicit update triggers: new external system, changed authoritative data source, added write permission, adjusted deployment location, swapped key storage, modified control boundary, service split out. Changes may not need full rewrite but must check affected views, decisions, tests. Integrate doc check into change/release process: does this change affect architecture? Which elements? Related materials updated? Actual deployment matches doc? Deeper: put architecture description in version control alongside code (docs as code), use architecture fitness functions (from previous article) to automate key constraint checks — drift detected continuously, not at next review. Distinguish: current running state, approved target state, transitional migration state. Transitional states may last long and need formal description, not just tribal knowledge.

Conclusion

Good architecture docs are not about most diagrams, most jargon, or thickest content. They create shared understanding across roles: business goals map to capabilities, app modules map to data & interfaces, deployment supports runtime needs, security constrains real access, decisions explain tradeoffs, review issues close with evidence. Summary method: separate concerns with views, link with identifiers, verify completeness with scenarios, preserve rationale with ADRs, back conclusions with verification evidence. When these align, architecture is not just "looks reasonable" but guides implementation, supports delivery, and remains useful as the system changes.