Architecture Documentation

Types of Architecture Documentation

• Solution Concept
• System Concept(System Design)
• Change Concept(Design for Change request)

Template of Solution Concept

1. Introduction
   • Context, Stakeholders
   • Precondition
   • Scope / Constrains
2. Requirements
   • Business User cases (e.g. Use Case diagram)
   • Functional requirements
   • Non-Functional requirements
   • Addition requirements (e,g, Security, Compliance, etc.)
3. Solution description
   • Context View (e.g. Context diagram, data flow diagram)
   • Architecture View (e.g. Architecture diagram)
   • Domain Models (e.g. Domain Models diagram)
   • Runtime View (e.g. Sequence Diagram, flow chart on systems / services level.)
   • Interface description (e.g. communication model, protocol, input, output, etc.)
4. Deployment concept
5. Operation concept
6. Testing concept (e.g. E2E Test)

Template of System Design

1. Introduction
   • purpose, scope
   • Context, strategy, constrains.
   • Related document (Reference to solution concept, interface specifications)
2. Requirements
   • Overview of functionalities.
   • Functional aspect
   • Non-Functional aspects. (e.g. Data Volume, QPS, TPS, etc.)
3. IT-Architecture
   • Context View (Conceptual View)
   • Architecture View (Architecture diagram)
4. Implementation
   • Component Diagram
   • Database Models (e.g. Physical persistance models, RDBMS & NoSQL)
   • Runtime View (sequence diagram on components of this system)
   • Interfaces specifications
   • Error handling
   • Concurrency
   • Logging
   • Security (e.g. Authentication & Authorization, Encryption)
   • Tech stack
5. Testing (Component test)
6. Deployment View

Template of Change Concept

1. Background
   What is the motivation to do this change? add reference to the requirements, tickets, etc.

2. Current State
   Describe the current solution, what is the problem, weakness, etc.

3. Target State

   • Interface Change:
     Describe changes in interface, we could using OpenAPI, AsyncAPI, textual tables, etc.

   • Business Activities Change:
     Use sequence diagram, work flow diagram, etc to describe changed business logic.

   • Data model change:
     List the changed tables, columns, date types, etc

   • Integration of external System:
     Have we received the interface specification from the service provider?
     What are the connection protocol, and access credentials?

4. Concurrency:
   Check if the solution supports running with multiple threads, multiple instances.

5. Deployment:
   How to deploy and roll out this solution?
   Are there any dependencies or restrictions from external systems or timeline.