A software architecture diagram should help someone answer a decision: where information lives, which system is responsible for an action, or how a failure is recovered. A page of technology logos rarely answers those questions on its own.
Start with the audience. A business owner needs to understand boundaries and responsibilities. A developer may need component interactions. An operator needs deployment and recovery information. Use separate views when combining them would make every reader work harder.
Choose the level of detail
The C4 model distinguishes views including system context, containers, components and code. Its vocabulary provides a useful way to separate levels of detail. A container in this model is a runnable application or data store; it does not necessarily mean a Docker container.
For a small project, a context view and an application/data view may answer the important questions. Add more detail when a decision needs it. The goal is a maintained explanation, not a diagram for every possible level.
| View | Main question | Typical reader |
|---|---|---|
| Context | Who uses the system and what else does it connect to? | Owner, delivery team, stakeholders |
| Application and data | Where do requests, logic and records live? | Developers and technical owners |
| Dynamic flow | What happens during a specific request? | Implementers and reviewers |
| Deployment | Where does the software run and how is it operated? | Operations and maintenance team |
A portal boundary in four parts
- 01CustomerRequests an authorised project record.
- 02PortalChecks identity and record permissions.
- 03Data sourceReturns permitted information.
- 04ResponseShows the current customer-facing state.
Example one a customer portal
Draw the customer, the portal application, its record store and the internal system that supplies project information. Label each connection with the information or action involved, such as “reads authorised project status.” Avoid an unlabeled arrow that could mean anything.
Mark the ownership boundary around customer data. The portal must check access on the server, even if the interface only displays projects the customer should see. OWASP recommends validating permissions on every request in its authorisation guidance.
A useful review question is whether the diagram shows where that check occurs. Another is which system wins if the portal and internal application disagree. A customer-facing copy of a record needs an update and reconciliation policy, not merely a connecting line.
Example two a CRM integration
Suppose a website enquiry creates a contact and a follow-up task. Draw the intake endpoint, a durable enquiry record, the CRM API and the notification service. Then annotate the submission identifier used to recognise a repeated event.
Walk through the case where the contact was created but the task was not. The architecture should make it possible to recover that partial result. If the diagram only shows a single arrow from website to CRM, it hides the distinction between receiving a request and completing the business process.
An enquiry crosses several boundaries
- 01WebsiteSends a uniquely identified submission.
- 02Intake recordPreserves received work and progress.
- 03CRMReturns contact and task identifiers.
- 04NotificationRecords the acknowledgement result.
Example three an automation with background work
Some tasks take longer than a browser request should wait. A document workflow might accept a file, record a job, send work to a queue and let a worker extract proposed fields. A reviewer later confirms the results before the accounting system is updated.
Show where the original file is stored, how the job references it and which step changes the business record. Label the review boundary separately from the extraction step. Include the exception queue or status so failed jobs do not disappear from the picture.
This is an illustrative architecture, not a required stack. A managed platform may supply several of these responsibilities. The diagram should still explain them, even when one vendor operates the implementation.
Use a compact diagram brief
Before drawing, complete the following brief with the team:
| Field | What to write |
|---|---|
| Decision | The question this diagram should answer |
| Audience | Who needs to read it without a presenter |
| Boundary | What belongs to this system and what is external |
| Records | The authoritative location for each important record |
| Connections | Direction, purpose and relevant trust boundary |
| Failure | Where interrupted work is visible and recoverable |
| Ownership | Who maintains the diagram and its review date |
Use names that match the application and operating notes. If the diagram says “gateway” but everyone calls the same service “intake,” explain the relationship. Consistent vocabulary helps people compare documentation with the actual system.
Review the diagram using one normal and one failed request
Ask a colleague to trace an ordinary request through the view. Then introduce one failure: an unavailable CRM, a duplicate upload or a customer requesting another account's record. The colleague should be able to identify which component decides what happens next.
Keep unresolved decisions visible as questions, not authoritative-looking boxes. An architecture diagram can describe a proposal, but it should be labelled as a proposal until the implementation has been checked against it.
Review the architecture with questions
Who owns each field and action?
Where can an operator see and resume it?
Keep the drawing close to the work
Store the editable diagram with the project documentation and review it when boundaries or data ownership change. Export a readable version for stakeholders who do not use the authoring tool. Record the diagram's purpose so future edits preserve its level of detail.
Use the process-modeling guide for the business workflow and the orchestration guide for execution and recovery. Anteomnio's software engineering work includes clarifying these responsibilities before choosing the implementation.
Sources and calculation notes
The workflow designs, checklists and evaluation suggestions are original Anteomnio guidance. Product statements are based on the linked documentation reviewed on 27 October 2026. No comparative performance test or client-result claim is made.
- C4 model — The C4 model defines levels and views for software architecture diagrams.
- authorisation guidance — OWASP recommends least privilege, default denial and checking permissions on every request.
External references checked on 27 October 2026.