Solution architecture is a subset of your enterprise architecture. When you set out to develop and implement changes to your enterprise architecture, it’s practical to design and document the emerging changes in the context of a solution, which is edited into your enterprise architecture documentation as the new solution is implemented into your business and IT architecture.
The order of the chapters in the solution architecture document reflects the sequence of tasks in a practical and effective way of designing and documenting the solution.
Solution architecture documentation
I recommend that your solution architecture documentation covers the following topics:
Introduction
Summary
Summarize the solution’s intended changes in the enterprise architecture and the state of the design and this document. Update the summary before recirculating each major revision of the document.
Revision history
Maintain a list of recent changes. Purge old changes as new major revisions are completed.
Solution overview
Present a system context diagram [Wikipedia] and describe the solution’s key elements.
Processes
Provide an overview of new processes or process changes introduced in the enterprise architecture when this solution is implemented. Detail any processes that significantly shape the architecture, possibly using business process modelling [Wikipedia].
Information
Present an information model [Wikipedia] and explain the information entities and their relationships.
Design constraints
Life expectancy
The solution’s life expectancy must be taken into account in design decisions. Ideally, the business case states the required life expectancy.
Coexistence
If the solution is required to coexist – even for a limited time – with overlapping systems, describe how the design accounts for it.
Transition
Describe any short-term design impacts needed for handling migration of data from other systems or other activities in phasing in the new solution.
Compatibility
Explain any compatibility requirements and their consequences for the design. Remember that compatibility can be backward or forward or both.
Policies
Mention policies that impact the design, and how.
Standards
List standards that impact the design, and how.
Technologies
List mandatory technologies and explain how the design is impacted.
Design principles
List design principles and describe their impact on the design.
Design aspects
Auditability
Describe how the design provides auditability, including tracking of who views or changes data.
Compliance
Explain how the design ensures compliance with GDPR and other regulations.
Security
Describe how security [Wikipedia] mechanisms protect the system against malicious attacks and data theft.
Integrity
Explain how data is kept correct and complete, even across integrated systems.
Authentication
Describe how users (and integrated systems) are identified and authenticated [Wikipedia].
Authorization
Explain how the design ensures authorization [Wikipedia] to control which features and data are available to different users and integrated systems.
Non-repudiation
Describe design measures that ensure non-repudiation [Wikipedia].
Usability
Mention any design choices that contribute to usability [Wikipedia].
Localization
Describe any design measures to ensure localization [Wikipedia].
Concurrency
Highlight concurrency [Wikipedia] scenarios and describe which mechanisms are put in place to avoid problems.
Capacity
Mention capacity expectations and explain any related design measures to accommodate them.
Performance
Describe performance expectations and how any performance requirements are met.
Scalability
Explain how the architecture can be scales to meet significant changes in capacity or performance demands.
Observability
Describe how the design makes the system observable [Wikipedia].
Availability
Describe availability expectations and any requirements, and how the design ensures they a met.
Testability
Explain available approaches to testing the solution, and any design mechanisms utilized to enable them.
Operability
Describe any design measures that enable monitoring and control of the running solution.
Recoverability
Outline disaster scenarios, and describe how the solution recovers and returns to normal operations.
High-level design
Components
Illustrate the key components of the architecture, and describe them.
User interaction
Explain the structure of the user interface, and describe how the components work to respond to the user’s actions.
Integrations
List integrations with surrounding systems, and describe each integration in detail.
Scheduled tasks
List scheduled tasks, and describe how the components work to perform the scheduled tasks.
Development
Describe the necessary technical setup required to build, maintain, and deploy the solution.
Environments
Describe the necessary environments for testing and operating the solution.
Testing
Describe how the solution is tested.
Operations
Installation
Provide detailed instructions for installing the system in the production environment.
Configuration
Explain how the system can be configured.
Startup
List the sequence of steps for starting up the system.
Shutdown
List the sequence of steps for shutting the system down in a controlled manner.
Recovery
List the steps for recovery after an uncontrolled breakdown.
Monitoring
Explain how to monitor the operational system.
Control
List any available features available to control the running system without shutting it down.
Reoccurring tasks
List and detail the steps in reoccurring operations tasks.
Support
Explain the setup provided to users of the system, including how they can report incidents.
Incident handling
Describe the handling of reported incidents.
Maintenance
Provide instructions and guidance for properly maintaining the solution.
You can omit sections if they aren’t needed for your particular solution, but I recommend that you keep them. You may need them late in the design process due to unforeseen changes in the requirements or other circumstantial changes. Insert additional sections if necessary, and consider amending your solution architecture document template.