A good architecture document is not one diagram. It is a set of views that explain the same system at different levels of detail for different readers.
A product sponsor may need a simple overview. A developer may need class relationships. An operations team may need deployment boundaries. A business analyst may need a process flow. The skill is not just knowing diagramming tools. The skill is choosing the right view for the question you are trying to answer.
The Problem
Teams often start architecture design with boxes and arrows. That is useful for early brainstorming, but it becomes risky when the diagram mixes too many ideas at once.
A single sketch might show:
- applications
- classes
- users
- network zones
- databases
- protocols
- project phases
- business processes
That kind of diagram can start a conversation, but it is hard to maintain and easy to misunderstand. One box might represent an entire application, while another box represents a module or a database. One arrow might mean an API call, while another means ownership, data flow, or dependency.
The goal of architecture modeling is to make those meanings explicit.
Start with Marchitecture, but Do Not Stop There
A marchitecture is a polished, high-level architecture picture used to explain an idea quickly. It is useful when you need to pitch a solution, align stakeholders, or explain the rough shape of a product.
The danger is treating it as the real design.
User
|
v
Mobile App
|
v
Backend Platform
|
+--> Customer System
|
+--> Reporting
|
+--> Database
This kind of view is helpful because it shows the main actors and systems. But it does not define exact responsibilities, protocols, data ownership, deployment shape, or code structure.
Use marchitecture for orientation. Then create more precise diagrams for implementation decisions.
Use UML When You Need Object or Interaction Detail
Unified Modeling Language, usually called UML, is a long-standing modeling language built around object-oriented systems. It contains many diagram types, but two are especially practical for Java teams: class diagrams and sequence diagrams.
Class Diagrams
A class diagram shows classes, interfaces, fields, methods, and relationships. It is useful when you need to explain the static structure of a part of the codebase.
<<interface>> Auditable
+ verifySignature()
Payment
- id
- amount
- date
+ authorize()
+ verifySignature()
MobilePayment extends Payment
- deviceId
User
- id
- username
User 1 ---- n Payment
Payment ..> Auditable
This view helps developers understand the domain objects and their relationships before writing or refactoring code. It is especially useful for critical parts of a system, new team onboarding, and discussions about inheritance or composition.
Avoid documenting every class manually if the code changes quickly. For low-level class views, generate diagrams from the code where possible.
Sequence Diagrams
A sequence diagram shows interactions over time. It helps explain how actors and components cooperate to complete a use case.
User API Payment Service Database
| | | |
| request | | |
|---------->| | |
| | validate | |
| |------------->| |
| | | save payment |
| | |------------------->|
| | | saved |
| | |<-------------------|
| response | | |
|<----------| | |
Use sequence diagrams when a feature depends on ordering, conditions, retries, or multiple components. They are more useful than class diagrams when the main question is what happens first, and what happens next?
Use ArchiMate for Enterprise Architecture
ArchiMate is aimed at enterprise architecture. It is useful when you need to connect business capabilities, applications, and technology infrastructure.
Its core idea is to model architecture across layers:
Business Layer
Business services, capabilities, processes
Application Layer
Software systems and application services
Technology Layer
Infrastructure, networks, devices, runtime platforms
ArchiMate also classifies concepts by aspect: active structure, behavior, and passive structure. In simple terms:
- active structure performs actions
- behavior is the action being performed
- passive structure is the thing acted upon
This makes ArchiMate useful when the design question is bigger than one application. For example, it can help show how a business process is supported by several applications and how those applications rely on technology infrastructure.
Use ArchiMate when you need to explain an enterprise landscape, not when you only need to describe a few Java classes.
Use the C4 Model for Practical Software Architecture
The C4 model is a lightweight way to document architecture by zooming in step by step. It is popular because it is easier to apply than a full modeling language and works well for teams that want useful diagrams without too much notation.
C4 has four levels:
1. Context
The system, its users, and neighboring systems
2. Container
Deployable or runnable parts inside the system
3. Component
Major building blocks inside a container
4. Code
Low-level implementation detail, often represented with UML class diagrams
The main idea is zoom.
At the context level, you show the whole system as one box. At the container level, you open that box and show deployable parts such as a web app, backend service, database, or cache. At the component level, you open one container and show internal modules. At the code level, you show classes or code-level details.
Context:
Customer -> Payment System -> CRM
Container:
Payment System
- Mobile App
- Backend API
- Business Logic
- Database
Component:
Business Logic
- Payment Controller
- Payment Service
- Data Mapper
- Integration Adapter
C4 does not force a strict visual notation. The important rule is consistency. Use the same shapes and labels across diagrams, add a legend, and describe relationships clearly.
C4 is a strong default for developer-facing architecture documentation.
Use BPMN for Business Processes
Business Process Model and Notation, or BPMN, is designed to describe business workflows. It is useful when the process matters more than the internal code structure.
A BPMN-like flow can describe tasks, decisions, and handoffs:
Start
|
v
Customer submits payment
|
v
Validate recipient
|
+-- invalid --> Show error --> End
|
v
Authorize payment
|
v
Send confirmation
|
v
End
BPMN is especially helpful when business and technical people need a shared view of a process. It is more focused than UML because it is specifically about business workflows.
Use DMN for Business Rules
Decision Model and Notation, or DMN, is used to model decisions and rules. It complements BPMN well because workflows often contain business decisions.
A decision table is a practical example:
| Amount | Recipient valid | Result | |---:|---|---| | Less than limit | Yes | Allow payment | | Greater than limit | Yes | Require additional authorization | | Any amount | No | Reject payment |
This kind of table is easy for business stakeholders to review and easier for developers to translate into tests or rule logic.
Use DMN when the rules are more important than the sequence of steps.
Use arc42 as a Documentation Scaffold
Arc42 is not a diagramming language. It is a template for architecture documentation.
That distinction matters. UML, ArchiMate, C4, BPMN, and DMN help you create diagrams. arc42 helps you decide what to document.
A practical architecture document might include:
Introduction and goals
Constraints
Context view
Building block view
Runtime view
Deployment view
Cross-cutting concepts
Architecture decisions
Risks and technical debt
You can fill those sections with diagrams from other techniques. For example, use C4 for context and containers, UML for class details, BPMN for business workflows, and DMN for rules.
Practical Workflow
A good architecture documentation workflow can be simple:
- Start with a rough sketch to align everyone.
- Convert the sketch into a C4 context diagram.
- Add a C4 container diagram for deployable parts.
- Use sequence diagrams for important runtime flows.
- Use class diagrams only for important domain or code structures.
- Use BPMN when the business process needs review.
- Use DMN when rules need precise agreement.
- Organize the final documentation with an arc42-style structure.
- Keep diagrams focused on one purpose each.
- Update diagrams when they affect decisions, onboarding, or operations.
Common Mistakes
The most common mistake is mixing levels of detail. A diagram that combines business processes, network zones, classes, and deployment nodes will confuse readers.
Another mistake is creating diagrams without an audience. Before drawing, ask who will use the diagram and what decision it should support.
Teams also over-document low-level code. If a class diagram becomes stale after every commit, it is probably too detailed to maintain manually.
A final mistake is treating diagrams as decoration. Architecture diagrams should answer questions: what depends on what, what runs where, what happens during this use case, or which system owns this responsibility.
Checklist
Use this checklist before publishing an architecture diagram:
- The diagram has one clear purpose.
- Every shape type has a consistent meaning.
- Every arrow has a clear meaning.
- The level of detail is consistent.
- The target audience is obvious.
- Important relationships are labeled.
- Technical protocols are included only when useful.
- Business concepts use agreed terminology.
- The diagram can be understood without a long meeting.
- The diagram is stored where the team can maintain it.
Conclusion
Architectural design is not about choosing one perfect notation. It is about choosing the right view for the problem.
Use marchitecture to communicate the idea. Use UML for object and interaction details. Use ArchiMate for enterprise architecture. Use C4 as a lightweight default for software structure. Use BPMN for workflows, DMN for decisions, and arc42 to organize documentation.
The best architecture documentation is focused, consistent, and useful. It helps teams make decisions, communicate tradeoffs, and build software with fewer misunderstandings.