Markdown template for documenting a software architecture view of any kind. Here's the template...
- Document your software architecture in multiple views:
- Views that focus on code (layers, modules and submodules, dependencies, etc.)
- Views that show the system at runtime
- Views that describe deployment and runtime infrastructure
- Domain model
- Etc.
- Name the views based on what they show, using terms the team is familiar with.
- Document a view iff it brings value to the dev team or other stakeholders.
- There's no need to fill up all sections of the view template.
- Use N/A for sections you will not fill up.
- Use TO-DO or TBD for sections you will work on later.
- Follow the seven tips for design diagrams.
- Complement structural diagrams with behavior diagrams when appropriate.
- Examples of behavior diagrams: sequence diagram, activity diagram, state machine diagram.
- The template has a placeholder for behavior diagrams.
- Record important design decisions using ADRs. Then add links to ADRs in the view.
- If content is out of date, delete it or visibly mark it as out-of-date.
- Creating an architecture view is a task that can be tracked in your backlog.
- This template is a suggestion that you may want to adopt or adapt. In any case, establishing and sharing a template for architecture views in your team or organization is a good idea.
- A microservice view
- An EDA view
- A DDD context map (yes, it can also be documented using this template)
- A hexagonal architecture
- A view showing deployment on AWS
This template is based on:
- The KISS architecture model, a set of precepts and guidelines presented at the OOP conference in 2022.
- Documenting Software Architectures, Second Edition. This book I co-authored years ago talks about the many benefits of having a template for technical documents, and suggests a (richer) template for architecture views in chapter 10.