├── 1. Files Tree ├── 01 Introduction and Goals │ ├── 1.1 Requirements Overview │ │ └── Requirements Overview.md │ ├── 1.2 Quality Goals │ │ └── Quality Goals.md │ ├── 1.3 Stakeholders │ │ └── Stakeholders.md │ └── Introduction and Goals.md ├── 02. Architecture Constraints │ └── Architecture Constraints.md ├── 03. Context and scope │ ├── 3.1 Bussiness context │ │ └── Business context.md │ ├── 3.2 Technical context │ │ └── Technical context.md │ └── Context and scope.md ├── 04. Solution Strategy │ └── Solution Strategy.md ├── 05. Building Block View │ ├── 5.1 Whitebox Overall System │ │ └── Whitebox Overall System.md │ ├── 5.2 Level 2 │ │ ├── 5.2.1 White Box building block 1 │ │ │ └── White Box building block 1.md │ │ ├── 5.2.2 White Box building block 2 │ │ │ └── White Box building block 2.md │ │ ├── 5.2.n White Box building block n │ │ │ └── White Box building block n.md │ │ └── Level 2.md │ ├── 5.3 Level 3 │ │ ├── 5.3.1. White Box building block x.1 │ │ │ └── White Box building block x.1.md │ │ ├── 5.3.2. White Box building block x.2 │ │ │ └── White Box building block x.2.md │ │ ├── 5.3.n. White Box building block y.1 │ │ │ └── White Box building block y.1.md │ │ └── Level 3.md │ └── Building Block View.md ├── 06. Runtime View │ └── Runtime View.md ├── 07. Deployment View │ ├── 7.1 Infrastructure Level 1 │ │ └── Infrastructure Level 1.md │ ├── 7.2 Infrastructure Level 2 │ │ └── Infrastructure Level 2.md │ └── Deployment View.md ├── 08. Crosscutting Concepts │ └── Crosscutting Concepts.md ├── 09. Architecture Decisions │ └── Architecture Decisions.md ├── 10. Quality Requirements │ ├── 10.1 Quality Tree │ │ └── Quality Tree.md │ ├── 10.2 Quality Scenarios │ │ └── Quality Scenarios.md │ └── Quality Requirements.md ├── 11. Risks and Technical Debt │ └── Risks and Technical Debt.md ├── 12. Glossary │ └── Glossary.md ├── About arc42.md └── images │ ├── 01-intro-and-goals.png │ ├── 02-constraints-overview.png │ ├── 03-context-overview.png │ ├── 04-solution-strategy-overview.png │ ├── 05-building-block-overview.png │ ├── 05_building_blocks-DE.png │ ├── 05_building_blocks-EN.png │ ├── 06-runtime-overview.png │ ├── 07-deployment-overview.png │ ├── 08-Crosscutting-Concepts-Structure-DE.png │ ├── 08-Crosscutting-Concepts-Structure-EN.png │ ├── 08-concepts-overview.png │ ├── 09-decision-overview.png │ ├── 10-q-scenario-overview.png │ ├── 10_stimulus.png │ ├── 11-risk-overview.png │ ├── 12-glossary-overview.png │ └── arc42-logo.png ├── 2. Single File ├── Arc42 Template in Markdown.md └── images │ ├── 05_building_blocks-DE.png │ ├── 05_building_blocks-EN.png │ ├── 08-Crosscutting-Concepts-Structure-DE.png │ ├── 08-Crosscutting-Concepts-Structure-EN.png │ ├── 10_stimulus.png │ └── arc42-logo.png ├── 3. Flat Structure ├── 01. Introduction and Goals.md ├── 02. Architecture Constraints.md ├── 03. Context and scope.md ├── 04. Solution Strategy.md ├── 05. Building Block View.md ├── 06. Runtime View.md ├── 07. Deployment View.md ├── 08. Crosscutting Concepts.md ├── 09. Architecture Decisions.md ├── 10. Quality Requirements.md ├── 11. Risks and Technical Debt.md ├── 12. Glossary.md ├── About arc42.md └── images │ ├── 01-intro-and-goals.png │ ├── 02-constraints-overview.png │ ├── 03-context-overview.png │ ├── 04-solution-strategy-overview.png │ ├── 05-building-block-overview.png │ ├── 05_building_blocks-DE.png │ ├── 05_building_blocks-EN.png │ ├── 06-runtime-overview.png │ ├── 07-deployment-overview.png │ ├── 08-Crosscutting-Concepts-Structure-DE.png │ ├── 08-Crosscutting-Concepts-Structure-EN.png │ ├── 08-concepts-overview.png │ ├── 09-decision-overview.png │ ├── 10-q-scenario-overview.png │ ├── 10_stimulus.png │ ├── 11-risk-overview.png │ ├── 12-glossary-overview.png │ └── arc42-logo.png └── README.md /1. Files Tree/01 Introduction and Goals/1.1 Requirements Overview/Requirements Overview.md: -------------------------------------------------------------------------------- 1 | Requirements Overview 2 | --------------------- 3 | 4 | **Contents.** 5 | 6 | Short description of the functional requirements, driving forces, 7 | extract (or abstract) of requirements. Link to (hopefully existing) 8 | requirements documents (with version number and information where to 9 | find it). 10 | 11 | **Motivation.** 12 | 13 | From the point of view of the end users a system is created or modified 14 | to improve support of a business activity and/or improve the quality. 15 | 16 | **Form.** 17 | 18 | Short textual description, probably in tabular use-case format. If 19 | requirements documents exist this overview should refer to these 20 | documents. 21 | 22 | Keep these excerpts as short as possible. Balance readability of this 23 | document with potential redundancy w.r.t to requirements documents. 24 | -------------------------------------------------------------------------------- /1. Files Tree/01 Introduction and Goals/1.2 Quality Goals/Quality Goals.md: -------------------------------------------------------------------------------- 1 | Quality Goals 2 | ------------- 3 | 4 | **Contents.** 5 | 6 | The top three (max five) quality goals for the architecture whose 7 | fulfillment is of highest importance to the major stakeholders. We 8 | really mean quality goals for the architecture. Don’t confuse them with 9 | project goals. They are not necessarily identical. 10 | 11 | **Motivation.** 12 | 13 | You should know the quality goals of your most important stakeholders, 14 | since they will influence fundamental architectural decisions. Make sure 15 | to be very concrete about these qualities, avoid buzzwords. If you as an 16 | architect do not know how the quality of your work will be judged … 17 | 18 | **Form.** 19 | 20 | A table with quality goals and concrete scenarios, ordered by priorities -------------------------------------------------------------------------------- /1. Files Tree/01 Introduction and Goals/1.3 Stakeholders/Stakeholders.md: -------------------------------------------------------------------------------- 1 | Stakeholders 2 | ------------ 3 | 4 | **Contents.** 5 | 6 | Explicit overview of stakeholders of the system, i.e. all person, roles 7 | or organizations that 8 | 9 | - should know the architecture 10 | 11 | - have to be convinced of the architecture 12 | 13 | - have to work with the architecture or with code 14 | 15 | - need the documentation of the architecture for their work 16 | 17 | - have to come up with decisions about the system or its development 18 | 19 | **Motivation.** 20 | 21 | You should know all parties involved in development of the system or 22 | affected by the system. Otherwise, you may get nasty surprises later in 23 | the development process. These stakeholders determine the extent and the 24 | level of detail of your work and its results. 25 | 26 | **Form.** 27 | 28 | Table with role names, person names, and their expectations with respect 29 | to the architecture and its documentation. 30 | 31 | | Role/Name | Contact | Expectations | 32 | | ----------- | ------------------------- | ------------------------- | 33 | | Role-1 | Contact-1 | *<Expectation-1*> | 34 | | Role-2 | Contact-2 | *<Expectation-2*> | 35 | -------------------------------------------------------------------------------- /1. Files Tree/01 Introduction and Goals/Introduction and Goals.md: -------------------------------------------------------------------------------- 1 | Introduction and Goals 2 | ====================== 3 | 4 | Describes the relevant requirements and the driving forces that software 5 | architects and development team must consider. These include 6 | 7 | - underlying business goals, essential features and functional 8 | requirements for the system 9 | 10 | - quality goals for the architecture 11 | 12 | - relevant stakeholders and their expectations 13 | 14 | -------------------------------------------------------------------------------- /1. Files Tree/02. Architecture Constraints/Architecture Constraints.md: -------------------------------------------------------------------------------- 1 | Architecture Constraints 2 | ======================== 3 | 4 | **Contents.** 5 | 6 | Any requirement that constrains software architects in their freedom of 7 | design and implementation decisions or decision about the development 8 | process. These constraints sometimes go beyond individual systems and 9 | are valid for whole organizations and companies. 10 | 11 | **Motivation.** 12 | 13 | Architects should know exactly where they are free in their design 14 | decisions and where they must adhere to constraints. Constraints must 15 | always be dealt with; they may be negotiable, though. 16 | 17 | **Form.** 18 | 19 | Simple tables of constraints with explanations. If needed you can 20 | subdivide them into technical constraints, organizational and political 21 | constraints and conventions (e.g. programming or versioning guidelines, 22 | documentation or naming conventions) -------------------------------------------------------------------------------- /1. Files Tree/03. Context and scope/3.1 Bussiness context/Business context.md: -------------------------------------------------------------------------------- 1 | Business Context 2 | ---------------- 3 | 4 | **Contents.** 5 | 6 | Specification of **all** communication partners (users, IT-systems, …) 7 | with explanations of domain specific inputs and outputs or interfaces. 8 | Optionally you can add domain specific formats or communication 9 | protocols. 10 | 11 | **Motivation.** 12 | 13 | All stakeholders should understand which data are exchanged with the 14 | environment of the system. 15 | 16 | **Form.** 17 | 18 | All kinds of diagrams that show the system as a black box and specify 19 | the domain interfaces to communication partners. 20 | 21 | Alternatively (or additionally) you can use a table. The title of the 22 | table is the name of your system, the three columns contain the name of 23 | the communication partner, the inputs, and the outputs. 24 | 25 | **<Diagram or Table>** 26 | 27 | **<optionally: Explanation of external domain interfaces>** 28 | 29 | -------------------------------------------------------------------------------- /1. Files Tree/03. Context and scope/3.2 Technical context/Technical context.md: -------------------------------------------------------------------------------- 1 | Technical Context 2 | ----------------- 3 | 4 | **Contents.** 5 | 6 | Technical interfaces (channels and transmission media) linking your 7 | system to its environment. In addition a mapping of domain specific 8 | input/output to the channels, i.e. an explanation with I/O uses which 9 | channel. 10 | 11 | **Motivation.** 12 | 13 | Many stakeholders make architectural decision based on the technical 14 | interfaces between the system and its context. Especially infrastructure 15 | or hardware designers decide these technical interfaces. 16 | 17 | **Form.** 18 | 19 | E.g. UML deployment diagram describing channels to neighboring systems, 20 | together with a mapping table showing the relationships between channels 21 | and input/output. 22 | 23 | **<Diagram or Table>** 24 | 25 | **<optionally: Explanation of technical interfaces>** 26 | 27 | **<Mapping Input/Output to Channels>** 28 | -------------------------------------------------------------------------------- /1. Files Tree/03. Context and scope/Context and scope.md: -------------------------------------------------------------------------------- 1 | System Scope and Context 2 | ======================== 3 | 4 | **Contents.** 5 | 6 | System scope and context - as the name suggests - delimits your system 7 | (i.e. your scope) from all its communication partners (neighboring 8 | systems and users, i.e. the context of your system). It thereby 9 | specifies the external interfaces. 10 | 11 | If necessary, differentiate the business context (domain specific inputs 12 | and outputs) from the technical context (channels, protocols, hardware). 13 | 14 | **Motivation.** 15 | 16 | The domain interfaces and technical interfaces to communication partners 17 | are among your system’s most critical aspects. Make sure that you 18 | completely understand them. 19 | 20 | **Form.** 21 | 22 | Various options: 23 | 24 | - Context diagrams 25 | 26 | - Lists of communication partners and their interfaces. 27 | -------------------------------------------------------------------------------- /1. Files Tree/04. Solution Strategy/Solution Strategy.md: -------------------------------------------------------------------------------- 1 | Solution Strategy 2 | ================= 3 | 4 | **Contents.** 5 | 6 | A short summary and explanation of the fundamental decisions and 7 | solution strategies, that shape the system’s architecture. These include 8 | 9 | - technology decisions 10 | 11 | - decisions about the top-level decomposition of the system, e.g. 12 | usage of an architectural pattern or design pattern 13 | 14 | - decisions on how to achieve key quality goals 15 | 16 | - relevant organizational decisions, e.g. selecting a development 17 | process or delegating certain tasks to third parties. 18 | 19 | **Motivation.** 20 | 21 | These decisions form the cornerstones for your architecture. They are 22 | the basis for many other detailed decisions or implementation rules. 23 | 24 | **Form.** 25 | 26 | Keep the explanation of these key decisions short. 27 | 28 | Motivate what you have decided and why you decided that way, based upon 29 | your problem statement, the quality goals and key constraints. Refer to 30 | details in the following sections. 31 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.1 Whitebox Overall System/Whitebox Overall System.md: -------------------------------------------------------------------------------- 1 | Whitebox Overall System 2 | ----------------------- 3 | 4 | Here you describe the decomposition of the overall system using the 5 | following white box template. It contains 6 | 7 | - an overview diagram 8 | 9 | - a motivation for the decomposition 10 | 11 | - black box descriptions of the contained building blocks. For these 12 | we offer you alternatives: 13 | 14 | - use *one* table for a short and pragmatic overview of all 15 | contained building blocks and their interfaces 16 | 17 | - use a list of black box descriptions of the building blocks 18 | according to the black box template (see below). Depending on 19 | your choice of tool this list could be sub-chapters (in text 20 | files), sub-pages (in a Wiki) or nested elements (in a modeling 21 | tool). 22 | 23 | - (optional:) important interfaces, that are not explained in the 24 | black box templates of a building block, but are very important for 25 | understanding the white box. Since there are so many ways to specify 26 | interfaces why do not provide a specific template for them. In the 27 | worst case you have to specify and describe syntax, semantics, 28 | protocols, error handling, restrictions, versions, qualities, 29 | necessary compatibilities and many things more. In the best case you 30 | will get away with examples or simple signatures. 31 | 32 | ***<Overview Diagram>*** 33 | 34 | Motivation 35 | 36 | : *<text explanation>* 37 | 38 | Contained Building Blocks 39 | 40 | : *<Description of contained building block (black boxes)>* 41 | 42 | Important Interfaces 43 | 44 | : *<Description of important interfaces>* 45 | 46 | Insert your explanations of black boxes from level 1: 47 | 48 | If you use tabular form you will only describe your black boxes with 49 | name and responsibility according to the following schema: 50 | 51 | | **Name** | **Responsibility** | 52 | | -------------------- | -------------------------------------------- | 53 | | Black Box 1 |  *<Text>* | 54 | | Black Box 2 |  *<Text>* | 55 | 56 | If you use a list of black box descriptions then you fill in a separate 57 | black box template for every important building block . Its headline is 58 | the name of the black box. 59 | 60 | ### <Name black box 1> 61 | 62 | Here you describe <black box 1> according the the following black 63 | box template: 64 | 65 | - Purpose/Responsibility 66 | 67 | - Interface(s), when they are not extracted as separate paragraphs. 68 | This interfaces may include qualities and performance 69 | characteristics. 70 | 71 | - (Optional) Quality-/Performance characteristics of the black box, 72 | e.g.availability, run time behavior, …. 73 | 74 | - (Optional) directory/file location 75 | 76 | - (Optional) Fulfilled requirements (if you need traceability to 77 | requirements). 78 | 79 | - (Optional) Open issues/problems/risks 80 | 81 | *<Purpose/Responsibility>* 82 | 83 | *<Interface(s)>* 84 | 85 | *<(Optional) Quality/Performance Characteristics>* 86 | 87 | *<(Optional) Directory/File Location>* 88 | 89 | *<(Optional) Fulfilled Requirements>* 90 | 91 | *<(optional) Open Issues/Problems/Risks>* 92 | 93 | ### <Name black box 2> 94 | 95 | *<black box template>* 96 | 97 | ### <Name black box n> 98 | 99 | *<black box template>* 100 | 101 | ### <Name interface 1> 102 | 103 | … 104 | 105 | ### <Name interface m> 106 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.2 Level 2/5.2.1 White Box building block 1/White Box building block 1.md: -------------------------------------------------------------------------------- 1 | ### White Box *<building block 1>* 2 | 3 | …describes the internal structure of *building block 1*. 4 | 5 | *<white box template>* 6 | 7 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.2 Level 2/5.2.2 White Box building block 2/White Box building block 2.md: -------------------------------------------------------------------------------- 1 | ### White Box *<building block 2>* 2 | 3 | *<white box template>* 4 | 5 | … 6 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.2 Level 2/5.2.n White Box building block n/White Box building block n.md: -------------------------------------------------------------------------------- 1 | ### White Box *<building block m>* 2 | 3 | *<white box template>* 4 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.2 Level 2/Level 2.md: -------------------------------------------------------------------------------- 1 | Level 2 2 | ------- 3 | 4 | Here you can specify the inner structure of (some) building blocks from 5 | level 1 as white boxes. 6 | 7 | You have to decide which building blocks of your system are important 8 | enough to justify such a detailed description. Please prefer relevance 9 | over completeness. Specify important, surprising, risky, complex or 10 | volatile building blocks. Leave out normal, simple, boring or 11 | standardized parts of your system 12 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.3 Level 3/5.3.1. White Box building block x.1/White Box building block x.1.md: -------------------------------------------------------------------------------- 1 | ### White Box <\_building block x.1\_> 2 | 3 | Specifies the internal structure of *building block x.1*. 4 | 5 | *<white box template>* 6 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.3 Level 3/5.3.2. White Box building block x.2/White Box building block x.2.md: -------------------------------------------------------------------------------- 1 | ### White Box <\_building block x.2\_> 2 | 3 | *<white box template>* 4 | 5 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.3 Level 3/5.3.n. White Box building block y.1/White Box building block y.1.md: -------------------------------------------------------------------------------- 1 | ### White Box <\_building block y.1\_> 2 | 3 | *<white box template>* 4 | 5 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/5.3 Level 3/Level 3.md: -------------------------------------------------------------------------------- 1 | Level 3 2 | ------- 3 | 4 | Here you can specify the inner structure of (some) building blocks from 5 | level 2 as white boxes. 6 | 7 | When you need more detailed levels of your architecture please copy this 8 | part of arc42 for additional levels. 9 | -------------------------------------------------------------------------------- /1. Files Tree/05. Building Block View/Building Block View.md: -------------------------------------------------------------------------------- 1 | Building Block View 2 | =================== 3 | 4 | **Content.** 5 | 6 | The building block view shows the static decomposition of the system 7 | into building blocks (modules, components, subsystems, classes, 8 | interfaces, packages, libraries, frameworks, layers, partitions, tiers, 9 | functions, macros, operations, datas structures, …) as well as their 10 | dependencies (relationships, associations, …) 11 | 12 | This view is mandatory for every architecture documentation. In analogy 13 | to a house this is the *floor plan*. 14 | 15 | **Motivation.** 16 | 17 | Maintain an overview of your source code by making its structure 18 | understandable through abstraction. 19 | 20 | This allows you to communicate with your stakeholder on an abstract 21 | level without disclosing implementation details. 22 | 23 | **Form.** 24 | 25 | The building block view is a hierarchical collection of black boxes and 26 | white boxes (see figure below) and their descriptions. 27 | 28 | ![Hierarchy of building blocks](../images/05_building_blocks-EN.png) 29 | 30 | **Level 1** is the white box description of the overall system together 31 | with black box descriptions of all contained building blocks. 32 | 33 | **Level 2** zooms into some building blocks of level 1. Thus it contains 34 | the white box description of selected building blocks of level 1, 35 | together with black box descriptions of their internal building blocks. 36 | 37 | **Level 3** zooms into selected building blocks of level 2, and so on. 38 | -------------------------------------------------------------------------------- /1. Files Tree/06. Runtime View/Runtime View.md: -------------------------------------------------------------------------------- 1 | Runtime View 2 | ============ 3 | 4 | **Contents.** 5 | 6 | The runtime view describes concrete behavior and interactions of the 7 | system’s building blocks in form of scenarios from the following areas: 8 | 9 | - important use cases or features: how do building blocks execute 10 | them? 11 | 12 | - interactions at critical external interfaces: how do building blocks 13 | cooperate with users and neighboring systems? 14 | 15 | - operation and administration: launch, start-up, stop 16 | 17 | - error and exception scenarios 18 | 19 | Remark: The main criterion for the choice of possible scenarios 20 | (sequences, workflows) is their **architectural relevance**. It is 21 | **not** important to describe a large number of scenarios. You should 22 | rather document a representative selection. 23 | 24 | **Motivation.** 25 | 26 | You should understand how (instances of) building blocks of your system 27 | perform their job and communicate at runtime. You will mainly capture 28 | scenarios in your documentation to communicate your architecture to 29 | stakeholders that are less willing or able to read and understand the 30 | static models (building block view, deployment view). 31 | 32 | **Form.** 33 | 34 | There are many notations for describing scenarios, e.g. 35 | 36 | - numbered list of steps (in natural language) 37 | 38 | - activity diagrams or flow charts 39 | 40 | - sequence diagrams 41 | 42 | - BPMN or EPCs (event process chains) 43 | 44 | - state machines 45 | 46 | - … 47 | 48 | <Runtime Scenario 1> 49 | -------------------------- 50 | 51 | - *<insert runtime diagram or textual description of the 52 | scenario>* 53 | 54 | - *<insert description of the notable aspects of the interactions 55 | between the building block instances depicted in this diagram.>* 56 | 57 | <Runtime Scenario 2> 58 | -------------------------- 59 | 60 | ... 61 | 62 | <Runtime Scenario n> 63 | -------------------------- 64 | 65 | ... 66 | -------------------------------------------------------------------------------- /1. Files Tree/07. Deployment View/7.1 Infrastructure Level 1/Infrastructure Level 1.md: -------------------------------------------------------------------------------- 1 | Infrastructure Level 1 2 | ---------------------- 3 | 4 | Describe (usually in a combination of diagrams, tables, and text): 5 | 6 | - the distribution of your system to multiple locations, environments, 7 | computers, processors, .. as well as the physical connections 8 | between them 9 | 10 | - important justification or motivation for this deployment structure 11 | 12 | - Quality and/or performance features of the infrastructure 13 | 14 | - the mapping of software artifacts to elements of the infrastructure 15 | 16 | For multiple environments or alternative deployments please copy that 17 | section of arc42 for all relevant environments. 18 | 19 | ***<Overview Diagram>*** 20 | 21 | Motivation 22 | 23 | : *<explanation in text form>* 24 | 25 | Quality and/or Performance Features 26 | 27 | : *<explanation in text form>* 28 | 29 | Mapping of Building Blocks to Infrastructure 30 | 31 | : *<description of the mapping>* 32 | -------------------------------------------------------------------------------- /1. Files Tree/07. Deployment View/7.2 Infrastructure Level 2/Infrastructure Level 2.md: -------------------------------------------------------------------------------- 1 | 2 | Infrastructure Level 2 3 | ---------------------- 4 | 5 | Here you can include the internal structure of (some) infrastructure 6 | elements from level 1. 7 | 8 | Please copy the structure from level 1 for each selected element. 9 | 10 | ### *<Infrastructure Element 1>* 11 | 12 | *<diagram + explanation>* 13 | 14 | ### *<Infrastructure Element 2>* 15 | 16 | *<diagram + explanation>* 17 | 18 | … 19 | 20 | ### *<Infrastructure Element n>* 21 | 22 | *<diagram + explanation>* 23 | 24 | -------------------------------------------------------------------------------- /1. Files Tree/07. Deployment View/Deployment View.md: -------------------------------------------------------------------------------- 1 | Deployment View 2 | =============== 3 | 4 | **Content.** 5 | 6 | The deployment view describes: 7 | 8 | 1. the technical infrastructure used to execute your system, with 9 | infrastructure elements like geographical locations, environments, 10 | computers, processors, channels and net topologies as well as other 11 | infrastructure elements and 12 | 13 | 2. the mapping of (software) building blocks to that infrastructure 14 | elements. 15 | 16 | Often systems are executed in different environments, e.g. development 17 | environment, test environment, production environment. In such cases you 18 | should document all relevant environments. 19 | 20 | Especially document the deployment view when your software is executed 21 | as distributed system with more then one computer, processor, server or 22 | container or when you design and construct your own hardware processors 23 | and chips. 24 | 25 | From a software perspective it is sufficient to capture those elements 26 | of the infrastructure that are needed to show the deployment of your 27 | building blocks. Hardware architects can go beyond that and describe the 28 | infrastructure to any level of detail they need to capture. 29 | 30 | **Motivation.** 31 | 32 | Software does not run without hardware. This underlying infrastructure 33 | can and will influence your system and/or some cross-cutting concepts. 34 | Therefore, you need to know the infrastructure. 35 | 36 | Maybe the highest level deployment diagram is already contained in 37 | section 3.2. as technical context with your own infrastructure as ONE 38 | black box. In this section you will zoom into this black box using 39 | additional deployment diagrams: 40 | 41 | - UML offers deployment diagrams to express that view. Use it, 42 | probably with nested diagrams, when your infrastructure is more 43 | complex. 44 | 45 | - When your (hardware) stakeholders prefer other kinds of diagrams 46 | rather than the deployment diagram, let them use any kind that is 47 | able to show nodes and channels of the infrastructure. 48 | -------------------------------------------------------------------------------- /1. Files Tree/08. Crosscutting Concepts/Crosscutting Concepts.md: -------------------------------------------------------------------------------- 1 | Cross-cutting Concepts 2 | ====================== 3 | 4 | **Content.** 5 | 6 | This section describes overall, principal regulations and solution ideas 7 | that are relevant in multiple parts (= cross-cutting) of your system. 8 | Such concepts are often related to multiple building blocks. They can 9 | include many different topics, such as 10 | 11 | - domain models 12 | 13 | - architecture patterns or design patterns 14 | 15 | - rules for using specific technology 16 | 17 | - principal, often technical decisions of overall decisions 18 | 19 | - implementation rules 20 | 21 | **Motivation.** 22 | 23 | Concepts form the basis for *conceptual integrity* (consistency, 24 | homogeneity) of the architecture. Thus, they are an important 25 | contribution to achieve inner qualities of your system. 26 | 27 | Some of these concepts cannot be assigned to individual building blocks 28 | (e.g. security or safety). This is the place in the template that we 29 | provided for a cohesive specification of such concepts. 30 | 31 | **Form.** 32 | 33 | The form can be varied: 34 | 35 | - concept papers with any kind of structure 36 | 37 | - cross-cutting model excerpts or scenarios using notations of the 38 | architecture views 39 | 40 | - sample implementations, especially for technical concepts 41 | 42 | - reference to typical usage of standard frameworks (e.g. using 43 | Hibernate for object/relational mapping) 44 | 45 | **Structure.** 46 | 47 | A potential (but not mandatory) structure for this section could be: 48 | 49 | - Domain concepts 50 | 51 | - User Experience concepts (UX) 52 | 53 | - Safety and security concepts 54 | 55 | - Architecture and design patterns 56 | 57 | - "Under-the-hood" 58 | 59 | - development concepts 60 | 61 | - operational concepts 62 | 63 | Note: it might be difficult to assign individual concepts to one 64 | specific topic on this list. 65 | 66 | ![Possible topics for crosscutting concepts](../images/08-Crosscutting-Concepts-Structure-EN.png) 67 | 68 | *<Concept 1>* 69 | ------------------- 70 | 71 | *<explanation>* 72 | 73 | *<Concept 2>* 74 | ------------------- 75 | 76 | *<explanation>* 77 | 78 | … 79 | 80 | *<Concept n>* 81 | ------------------- 82 | 83 | *<explanation>* 84 | -------------------------------------------------------------------------------- /1. Files Tree/09. Architecture Decisions/Architecture Decisions.md: -------------------------------------------------------------------------------- 1 | Design Decisions 2 | ================ 3 | 4 | **Contents.** 5 | 6 | Important, expensive, large scale or risky architecture decisions 7 | including rationals. With "decisions" we mean selecting one alternative 8 | based on given criteria. 9 | 10 | Please use your judgement to decide whether an architectural decision 11 | should be documented here in this central section or whether you better 12 | document it locally (e.g. within the white box template of one building 13 | block). 14 | 15 | Avoid redundancy. Refer to section 4, where you already captured the 16 | most important decisions of your architecture. 17 | 18 | **Motivation.** 19 | 20 | Stakeholders of your system should be able to comprehend and retrace 21 | your decisions. 22 | 23 | **Form.** 24 | 25 | Various options: 26 | 27 | - List or table, ordered by importance and consequences or: 28 | 29 | - more detailed in form of separate sections per decision 30 | 31 | - ADR (architecture decision record) for every important decision 32 | -------------------------------------------------------------------------------- /1. Files Tree/10. Quality Requirements/10.1 Quality Tree/Quality Tree.md: -------------------------------------------------------------------------------- 1 | Quality Tree 2 | ------------ 3 | 4 | **Content.** 5 | 6 | The quality tree (as defined in ATAM – Architecture Tradeoff Analysis 7 | Method) with quality/evaluation scenarios as leafs. 8 | 9 | **Motivation.** 10 | 11 | The tree structure with priorities provides an overview for a sometimes 12 | large number of quality requirements. 13 | 14 | **Form.** 15 | 16 | The quality tree is a high-level overview of the quality goals and 17 | requirements: 18 | 19 | - tree-like refinement of the term "quality". Use "quality" or 20 | "usefulness" as a root 21 | 22 | - a mind map with quality categories as main branches 23 | 24 | In any case the tree should include links to the scenarios of the 25 | following section. 26 | -------------------------------------------------------------------------------- /1. Files Tree/10. Quality Requirements/10.2 Quality Scenarios/Quality Scenarios.md: -------------------------------------------------------------------------------- 1 | Quality Scenarios 2 | ----------------- 3 | 4 | **Contents.** 5 | 6 | Concretization of (sometimes vague or implicit) quality requirements 7 | using (quality) scenarios. 8 | 9 | These scenarios describe what should happen when a stimulus arrives at 10 | the system. 11 | 12 | For architects, two kinds of scenarios are important: 13 | 14 | - Usage scenarios (also called application scenarios or use case 15 | scenarios) describe the system’s runtime reaction to a certain 16 | stimulus. This also includes scenarios that describe the system’s 17 | efficiency or performance. Example: The system reacts to a user’s 18 | request within one second. 19 | 20 | - Change scenarios describe a modification of the system or of its 21 | immediate environment. Example: Additional functionality is 22 | implemented or requirements for a quality attribute change. 23 | 24 | **Motivation.** 25 | 26 | Scenarios make quality requirements concrete and allow to more easily 27 | measure or decide whether they are fulfilled. 28 | 29 | Especially when you want to assess your architecture using methods like 30 | ATAM you need to describe your quality goals (from section 1.2) more 31 | precisely down to a level of scenarios that can be discussed and 32 | evaluated. 33 | 34 | **Form.** 35 | 36 | Tabular or free form text. 37 | -------------------------------------------------------------------------------- /1. Files Tree/10. Quality Requirements/Quality Requirements.md: -------------------------------------------------------------------------------- 1 | Quality Requirements 2 | ==================== 3 | 4 | **Content.** 5 | 6 | This section contains all quality requirements as quality tree with 7 | scenarios. The most important ones have already been described in 8 | section 1.2. (quality goals) 9 | 10 | Here you can also capture quality requirements with lesser priority, 11 | which will not create high risks when they are not fully achieved. 12 | 13 | **Motivation.** 14 | 15 | Since quality requirements will have a lot of influence on architectural 16 | decisions you should know for every stakeholder what is really important 17 | to them, concrete and measurable. 18 | 19 | -------------------------------------------------------------------------------- /1. Files Tree/11. Risks and Technical Debt/Risks and Technical Debt.md: -------------------------------------------------------------------------------- 1 | Risks and Technical Debts 2 | ========================= 3 | 4 | **Contents.** 5 | 6 | A list of identified technical risks or technical debts, ordered by 7 | priority 8 | 9 | **Motivation.** 10 | 11 | “Risk management is project management for grown-ups” (Tim Lister, 12 | Atlantic Systems Guild.) 13 | 14 | This should be your motto for systematic detection and evaluation of 15 | risks and technical debts in the architecture, which will be needed by 16 | management stakeholders (e.g. project managers, product owners) as part 17 | of the overall risk analysis and measurement planning. 18 | 19 | **Form.** 20 | 21 | List of risks and/or technical debts, probably including suggested 22 | measures to minimize, mitigate or avoid risks or reduce technical debts. 23 | 24 | -------------------------------------------------------------------------------- /1. Files Tree/12. Glossary/Glossary.md: -------------------------------------------------------------------------------- 1 | Glossary 2 | ======== 3 | 4 | **Contents.** 5 | 6 | The most important domain and technical terms that your stakeholders use 7 | when discussing the system. 8 | 9 | You can also see the glossary as source for translations if you work in 10 | multi-language teams. 11 | 12 | **Motivation.** 13 | 14 | You should clearly define your terms, so that all stakeholders 15 | 16 | - have an identical understanding of these terms 17 | 18 | - do not use synonyms and homonyms 19 | 20 | **Form.** 21 | 22 | A table with columns <Term> and <Definition>. 23 | 24 | Potentially more columns in case you need translations. 25 | 26 | | Term | Definition | 27 | | --------------------------------- | --------------------------------- | 28 | | Term 1 | <definition-1> | 29 | | Term 2 | <definition-2> | 30 | 31 | 32 | -------------------------------------------------------------------------------- /1. Files Tree/About arc42.md: -------------------------------------------------------------------------------- 1 | # About arc42 2 | 3 | arc42, the Template for documentation of software and system 4 | architecture. 5 | 6 | By Dr. Gernot Starke, Dr. Peter Hruschka and contributors. 7 | 8 | Template Revision: 7.0 EN (based on asciidoc), January 2017 9 | 10 | © We acknowledge that this document uses material from the arc 42 11 | architecture template, . Created by Dr. Peter 12 | Hruschka & Dr. Gernot Starke. 13 | 14 | > **Note** 15 | > 16 | > This version of the template contains some help and explanations. It 17 | > is used for familiarization with arc42 and the understanding of the 18 | > concepts. For documentation of your own system you use better the 19 | > *plain* version. 20 | 21 | 22 | ## 1. Introduction and Goals 23 | Short description of the requirements, driving forces, extract (or abstract) of requirements. Top three (max five) quality goals for the architecture which have highest priority for the major stakeholders. A table of important stakeholders with their expectation regarding architecture. 24 | ![Introduction and Goals](images/01-intro-and-goals.png) 25 | 26 | 27 | ## 2. Architecture Constraints 28 | Anything that constrains teams in design and implementation decisions or decision about related processes. Can sometimes go beyond individual systems and are valid for whole organizations and companies. 29 | ![Architecture Constraints](images/02-constraints-overview.png) 30 | 31 | ## 3. Context and scope 32 | Delimits your system from its (external) communication partners (neighboring systems and users). Specifies the external interfaces. Shown from a business/domain perspective (always) or a technical perspective (optional). 33 | ![Context and scope](images/03-context-overview.png) 34 | 35 | ## 4. Solution Strategy 36 | Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions. 37 | ![Solution Strategy](images/04-solution-strategy-overview.png) 38 | 39 | ## 5. Building Block View 40 | Static decomposition of the system, abstractions of source-code, shown as hierarchy of white boxes (containing black boxes), up to the appropriate level of detail. 41 | ![Building Block View](images/05-building-block-overview.png) 42 | 43 | ## 6. Runtime View 44 | Behavior of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration plus error and exception behavior. 45 | ![Runtime View](images/06-runtime-overview.png) 46 | 47 | ## 7. Deployment View 48 | Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure elements. 49 | ![Deployment View](images/07-deployment-overview.png) 50 | 51 | ## 8. Crosscutting Concepts 52 | Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architectur patterns and -styles, rules for using specific technology and inmplementation rules. 53 | ![Crosscutting Concepts](images/08-concepts-overview.png) 54 | 55 | ## 9. Architecture Decisions 56 | Important, expensive, critical, large scale or risky architecture decisions including rationals. 57 | ![Architecture Decisions](images/09-decision-overview.png) 58 | 59 | ## 10. Quality Requirements 60 | Quality requirements as scenarios, with quality tree to provide high-level overview. The most important quality goals should have been described in section 1.2. (quality goals). 61 | ![Quality Requirements](images/10-q-scenario-overview.png) 62 | 63 | ## 11. Risks and Technical Debt 64 | Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about? 65 | ![Risks and Technical Debt](images/11-risk-overview.png) 66 | 67 | ## 12. Glossary 68 | Important domain and technical terms that stakeholders use when discussing he system. Also: translation reference if you work in a multi-language environment. 69 | ![Risks and Technical Debt](images/12-glossary-overview.png) 70 | -------------------------------------------------------------------------------- /1. Files Tree/images/01-intro-and-goals.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/01-intro-and-goals.png -------------------------------------------------------------------------------- /1. Files Tree/images/02-constraints-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/02-constraints-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/03-context-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/03-context-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/04-solution-strategy-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/04-solution-strategy-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/05-building-block-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/05-building-block-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/05_building_blocks-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/05_building_blocks-DE.png -------------------------------------------------------------------------------- /1. Files Tree/images/05_building_blocks-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/05_building_blocks-EN.png -------------------------------------------------------------------------------- /1. Files Tree/images/06-runtime-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/06-runtime-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/07-deployment-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/07-deployment-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/08-Crosscutting-Concepts-Structure-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/08-Crosscutting-Concepts-Structure-DE.png -------------------------------------------------------------------------------- /1. Files Tree/images/08-Crosscutting-Concepts-Structure-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/08-Crosscutting-Concepts-Structure-EN.png -------------------------------------------------------------------------------- /1. Files Tree/images/08-concepts-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/08-concepts-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/09-decision-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/09-decision-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/10-q-scenario-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/10-q-scenario-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/10_stimulus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/10_stimulus.png -------------------------------------------------------------------------------- /1. Files Tree/images/11-risk-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/11-risk-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/12-glossary-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/12-glossary-overview.png -------------------------------------------------------------------------------- /1. Files Tree/images/arc42-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/1. Files Tree/images/arc42-logo.png -------------------------------------------------------------------------------- /2. Single File/Arc42 Template in Markdown.md: -------------------------------------------------------------------------------- 1 | **About arc42** 2 | 3 | arc42, the Template for documentation of software and system 4 | architecture. 5 | 6 | By Dr. Gernot Starke, Dr. Peter Hruschka and contributors. 7 | 8 | Template Revision: 7.0 EN (based on asciidoc), January 2017 9 | 10 | © We acknowledge that this document uses material from the arc 42 11 | architecture template, . Created by Dr. Peter 12 | Hruschka & Dr. Gernot Starke. 13 | 14 | > **Note** 15 | > 16 | > This version of the template contains some help and explanations. It 17 | > is used for familiarization with arc42 and the understanding of the 18 | > concepts. For documentation of your own system you use better the 19 | > *plain* version. 20 | 21 | Introduction and Goals 22 | ====================== 23 | 24 | Describes the relevant requirements and the driving forces that software 25 | architects and development team must consider. These include 26 | 27 | - underlying business goals, essential features and functional 28 | requirements for the system 29 | 30 | - quality goals for the architecture 31 | 32 | - relevant stakeholders and their expectations 33 | 34 | Requirements Overview 35 | --------------------- 36 | 37 | **Contents.** 38 | 39 | Short description of the functional requirements, driving forces, 40 | extract (or abstract) of requirements. Link to (hopefully existing) 41 | requirements documents (with version number and information where to 42 | find it). 43 | 44 | **Motivation.** 45 | 46 | From the point of view of the end users a system is created or modified 47 | to improve support of a business activity and/or improve the quality. 48 | 49 | **Form.** 50 | 51 | Short textual description, probably in tabular use-case format. If 52 | requirements documents exist this overview should refer to these 53 | documents. 54 | 55 | Keep these excerpts as short as possible. Balance readability of this 56 | document with potential redundancy w.r.t to requirements documents. 57 | 58 | Quality Goals 59 | ------------- 60 | 61 | **Contents.** 62 | 63 | The top three (max five) quality goals for the architecture whose 64 | fulfillment is of highest importance to the major stakeholders. We 65 | really mean quality goals for the architecture. Don’t confuse them with 66 | project goals. They are not necessarily identical. 67 | 68 | **Motivation.** 69 | 70 | You should know the quality goals of your most important stakeholders, 71 | since they will influence fundamental architectural decisions. Make sure 72 | to be very concrete about these qualities, avoid buzzwords. If you as an 73 | architect do not know how the quality of your work will be judged … 74 | 75 | **Form.** 76 | 77 | A table with quality goals and concrete scenarios, ordered by priorities 78 | 79 | Stakeholders 80 | ------------ 81 | 82 | **Contents.** 83 | 84 | Explicit overview of stakeholders of the system, i.e. all person, roles 85 | or organizations that 86 | 87 | - should know the architecture 88 | 89 | - have to be convinced of the architecture 90 | 91 | - have to work with the architecture or with code 92 | 93 | - need the documentation of the architecture for their work 94 | 95 | - have to come up with decisions about the system or its development 96 | 97 | **Motivation.** 98 | 99 | You should know all parties involved in development of the system or 100 | affected by the system. Otherwise, you may get nasty surprises later in 101 | the development process. These stakeholders determine the extent and the 102 | level of detail of your work and its results. 103 | 104 | **Form.** 105 | 106 | Table with role names, person names, and their expectations with respect 107 | to the architecture and its documentation. 108 | 109 | | Role/Name | Contact | Expectations | 110 | | ----------- | ------------------------- | ------------------------- | 111 | | Role-1 | Contact-1 | *<Expectation-1*> | 112 | | Role-2 | Contact-2 | *<Expectation-2*> | 113 | 114 | Architecture Constraints 115 | ======================== 116 | 117 | **Contents.** 118 | 119 | Any requirement that constrains software architects in their freedom of 120 | design and implementation decisions or decision about the development 121 | process. These constraints sometimes go beyond individual systems and 122 | are valid for whole organizations and companies. 123 | 124 | **Motivation.** 125 | 126 | Architects should know exactly where they are free in their design 127 | decisions and where they must adhere to constraints. Constraints must 128 | always be dealt with; they may be negotiable, though. 129 | 130 | **Form.** 131 | 132 | Simple tables of constraints with explanations. If needed you can 133 | subdivide them into technical constraints, organizational and political 134 | constraints and conventions (e.g. programming or versioning guidelines, 135 | documentation or naming conventions) 136 | 137 | System Scope and Context 138 | ======================== 139 | 140 | **Contents.** 141 | 142 | System scope and context - as the name suggests - delimits your system 143 | (i.e. your scope) from all its communication partners (neighboring 144 | systems and users, i.e. the context of your system). It thereby 145 | specifies the external interfaces. 146 | 147 | If necessary, differentiate the business context (domain specific inputs 148 | and outputs) from the technical context (channels, protocols, hardware). 149 | 150 | **Motivation.** 151 | 152 | The domain interfaces and technical interfaces to communication partners 153 | are among your system’s most critical aspects. Make sure that you 154 | completely understand them. 155 | 156 | **Form.** 157 | 158 | Various options: 159 | 160 | - Context diagrams 161 | 162 | - Lists of communication partners and their interfaces. 163 | 164 | Business Context 165 | ---------------- 166 | 167 | **Contents.** 168 | 169 | Specification of **all** communication partners (users, IT-systems, …) 170 | with explanations of domain specific inputs and outputs or interfaces. 171 | Optionally you can add domain specific formats or communication 172 | protocols. 173 | 174 | **Motivation.** 175 | 176 | All stakeholders should understand which data are exchanged with the 177 | environment of the system. 178 | 179 | **Form.** 180 | 181 | All kinds of diagrams that show the system as a black box and specify 182 | the domain interfaces to communication partners. 183 | 184 | Alternatively (or additionally) you can use a table. The title of the 185 | table is the name of your system, the three columns contain the name of 186 | the communication partner, the inputs, and the outputs. 187 | 188 | **<Diagram or Table>** 189 | 190 | **<optionally: Explanation of external domain interfaces>** 191 | 192 | Technical Context 193 | ----------------- 194 | 195 | **Contents.** 196 | 197 | Technical interfaces (channels and transmission media) linking your 198 | system to its environment. In addition a mapping of domain specific 199 | input/output to the channels, i.e. an explanation with I/O uses which 200 | channel. 201 | 202 | **Motivation.** 203 | 204 | Many stakeholders make architectural decision based on the technical 205 | interfaces between the system and its context. Especially infrastructure 206 | or hardware designers decide these technical interfaces. 207 | 208 | **Form.** 209 | 210 | E.g. UML deployment diagram describing channels to neighboring systems, 211 | together with a mapping table showing the relationships between channels 212 | and input/output. 213 | 214 | **<Diagram or Table>** 215 | 216 | **<optionally: Explanation of technical interfaces>** 217 | 218 | **<Mapping Input/Output to Channels>** 219 | 220 | Solution Strategy 221 | ================= 222 | 223 | **Contents.** 224 | 225 | A short summary and explanation of the fundamental decisions and 226 | solution strategies, that shape the system’s architecture. These include 227 | 228 | - technology decisions 229 | 230 | - decisions about the top-level decomposition of the system, e.g. 231 | usage of an architectural pattern or design pattern 232 | 233 | - decisions on how to achieve key quality goals 234 | 235 | - relevant organizational decisions, e.g. selecting a development 236 | process or delegating certain tasks to third parties. 237 | 238 | **Motivation.** 239 | 240 | These decisions form the cornerstones for your architecture. They are 241 | the basis for many other detailed decisions or implementation rules. 242 | 243 | **Form.** 244 | 245 | Keep the explanation of these key decisions short. 246 | 247 | Motivate what you have decided and why you decided that way, based upon 248 | your problem statement, the quality goals and key constraints. Refer to 249 | details in the following sections. 250 | 251 | Building Block View 252 | =================== 253 | 254 | **Content.** 255 | 256 | The building block view shows the static decomposition of the system 257 | into building blocks (modules, components, subsystems, classes, 258 | interfaces, packages, libraries, frameworks, layers, partitions, tiers, 259 | functions, macros, operations, datas structures, …) as well as their 260 | dependencies (relationships, associations, …) 261 | 262 | This view is mandatory for every architecture documentation. In analogy 263 | to a house this is the *floor plan*. 264 | 265 | **Motivation.** 266 | 267 | Maintain an overview of your source code by making its structure 268 | understandable through abstraction. 269 | 270 | This allows you to communicate with your stakeholder on an abstract 271 | level without disclosing implementation details. 272 | 273 | **Form.** 274 | 275 | The building block view is a hierarchical collection of black boxes and 276 | white boxes (see figure below) and their descriptions. 277 | 278 | ![Hierarchy of building blocks](images/05_building_blocks-EN.png) 279 | 280 | **Level 1** is the white box description of the overall system together 281 | with black box descriptions of all contained building blocks. 282 | 283 | **Level 2** zooms into some building blocks of level 1. Thus it contains 284 | the white box description of selected building blocks of level 1, 285 | together with black box descriptions of their internal building blocks. 286 | 287 | **Level 3** zooms into selected building blocks of level 2, and so on. 288 | 289 | Whitebox Overall System 290 | ----------------------- 291 | 292 | Here you describe the decomposition of the overall system using the 293 | following white box template. It contains 294 | 295 | - an overview diagram 296 | 297 | - a motivation for the decomposition 298 | 299 | - black box descriptions of the contained building blocks. For these 300 | we offer you alternatives: 301 | 302 | - use *one* table for a short and pragmatic overview of all 303 | contained building blocks and their interfaces 304 | 305 | - use a list of black box descriptions of the building blocks 306 | according to the black box template (see below). Depending on 307 | your choice of tool this list could be sub-chapters (in text 308 | files), sub-pages (in a Wiki) or nested elements (in a modeling 309 | tool). 310 | 311 | - (optional:) important interfaces, that are not explained in the 312 | black box templates of a building block, but are very important for 313 | understanding the white box. Since there are so many ways to specify 314 | interfaces why do not provide a specific template for them. In the 315 | worst case you have to specify and describe syntax, semantics, 316 | protocols, error handling, restrictions, versions, qualities, 317 | necessary compatibilities and many things more. In the best case you 318 | will get away with examples or simple signatures. 319 | 320 | ***<Overview Diagram>*** 321 | 322 | Motivation 323 | 324 | : *<text explanation>* 325 | 326 | Contained Building Blocks 327 | 328 | : *<Description of contained building block (black boxes)>* 329 | 330 | Important Interfaces 331 | 332 | : *<Description of important interfaces>* 333 | 334 | Insert your explanations of black boxes from level 1: 335 | 336 | If you use tabular form you will only describe your black boxes with 337 | name and responsibility according to the following schema: 338 | 339 | | **Name** | **Responsibility** | 340 | | -------------------- | -------------------------------------------- | 341 | | Black Box 1 |  *<Text>* | 342 | | Black Box 2 |  *<Text>* | 343 | 344 | If you use a list of black box descriptions then you fill in a separate 345 | black box template for every important building block . Its headline is 346 | the name of the black box. 347 | 348 | ### <Name black box 1> 349 | 350 | Here you describe <black box 1> according the the following black 351 | box template: 352 | 353 | - Purpose/Responsibility 354 | 355 | - Interface(s), when they are not extracted as separate paragraphs. 356 | This interfaces may include qualities and performance 357 | characteristics. 358 | 359 | - (Optional) Quality-/Performance characteristics of the black box, 360 | e.g.availability, run time behavior, …. 361 | 362 | - (Optional) directory/file location 363 | 364 | - (Optional) Fulfilled requirements (if you need traceability to 365 | requirements). 366 | 367 | - (Optional) Open issues/problems/risks 368 | 369 | *<Purpose/Responsibility>* 370 | 371 | *<Interface(s)>* 372 | 373 | *<(Optional) Quality/Performance Characteristics>* 374 | 375 | *<(Optional) Directory/File Location>* 376 | 377 | *<(Optional) Fulfilled Requirements>* 378 | 379 | *<(optional) Open Issues/Problems/Risks>* 380 | 381 | ### <Name black box 2> 382 | 383 | *<black box template>* 384 | 385 | ### <Name black box n> 386 | 387 | *<black box template>* 388 | 389 | ### <Name interface 1> 390 | 391 | … 392 | 393 | ### <Name interface m> 394 | 395 | Level 2 396 | ------- 397 | 398 | Here you can specify the inner structure of (some) building blocks from 399 | level 1 as white boxes. 400 | 401 | You have to decide which building blocks of your system are important 402 | enough to justify such a detailed description. Please prefer relevance 403 | over completeness. Specify important, surprising, risky, complex or 404 | volatile building blocks. Leave out normal, simple, boring or 405 | standardized parts of your system 406 | 407 | ### White Box *<building block 1>* 408 | 409 | …describes the internal structure of *building block 1*. 410 | 411 | *<white box template>* 412 | 413 | ### White Box *<building block 2>* 414 | 415 | *<white box template>* 416 | 417 | … 418 | 419 | ### White Box *<building block m>* 420 | 421 | *<white box template>* 422 | 423 | Level 3 424 | ------- 425 | 426 | Here you can specify the inner structure of (some) building blocks from 427 | level 2 as white boxes. 428 | 429 | When you need more detailed levels of your architecture please copy this 430 | part of arc42 for additional levels. 431 | 432 | ### White Box <\_building block x.1\_> 433 | 434 | Specifies the internal structure of *building block x.1*. 435 | 436 | *<white box template>* 437 | 438 | ### White Box <\_building block x.2\_> 439 | 440 | *<white box template>* 441 | 442 | ### White Box <\_building block y.1\_> 443 | 444 | *<white box template>* 445 | 446 | Runtime View 447 | ============ 448 | 449 | **Contents.** 450 | 451 | The runtime view describes concrete behavior and interactions of the 452 | system’s building blocks in form of scenarios from the following areas: 453 | 454 | - important use cases or features: how do building blocks execute 455 | them? 456 | 457 | - interactions at critical external interfaces: how do building blocks 458 | cooperate with users and neighboring systems? 459 | 460 | - operation and administration: launch, start-up, stop 461 | 462 | - error and exception scenarios 463 | 464 | Remark: The main criterion for the choice of possible scenarios 465 | (sequences, workflows) is their **architectural relevance**. It is 466 | **not** important to describe a large number of scenarios. You should 467 | rather document a representative selection. 468 | 469 | **Motivation.** 470 | 471 | You should understand how (instances of) building blocks of your system 472 | perform their job and communicate at runtime. You will mainly capture 473 | scenarios in your documentation to communicate your architecture to 474 | stakeholders that are less willing or able to read and understand the 475 | static models (building block view, deployment view). 476 | 477 | **Form.** 478 | 479 | There are many notations for describing scenarios, e.g. 480 | 481 | - numbered list of steps (in natural language) 482 | 483 | - activity diagrams or flow charts 484 | 485 | - sequence diagrams 486 | 487 | - BPMN or EPCs (event process chains) 488 | 489 | - state machines 490 | 491 | - … 492 | 493 | <Runtime Scenario 1> 494 | -------------------------- 495 | 496 | - *<insert runtime diagram or textual description of the 497 | scenario>* 498 | 499 | - *<insert description of the notable aspects of the interactions 500 | between the building block instances depicted in this diagram.>* 501 | 502 | <Runtime Scenario 2> 503 | -------------------------- 504 | 505 | … {#_} 506 | - 507 | 508 | <Runtime Scenario n> 509 | -------------------------- 510 | 511 | Deployment View 512 | =============== 513 | 514 | **Content.** 515 | 516 | The deployment view describes: 517 | 518 | 1. the technical infrastructure used to execute your system, with 519 | infrastructure elements like geographical locations, environments, 520 | computers, processors, channels and net topologies as well as other 521 | infrastructure elements and 522 | 523 | 2. the mapping of (software) building blocks to that infrastructure 524 | elements. 525 | 526 | Often systems are executed in different environments, e.g. development 527 | environment, test environment, production environment. In such cases you 528 | should document all relevant environments. 529 | 530 | Especially document the deployment view when your software is executed 531 | as distributed system with more then one computer, processor, server or 532 | container or when you design and construct your own hardware processors 533 | and chips. 534 | 535 | From a software perspective it is sufficient to capture those elements 536 | of the infrastructure that are needed to show the deployment of your 537 | building blocks. Hardware architects can go beyond that and describe the 538 | infrastructure to any level of detail they need to capture. 539 | 540 | **Motivation.** 541 | 542 | Software does not run without hardware. This underlying infrastructure 543 | can and will influence your system and/or some cross-cutting concepts. 544 | Therefore, you need to know the infrastructure. 545 | 546 | Maybe the highest level deployment diagram is already contained in 547 | section 3.2. as technical context with your own infrastructure as ONE 548 | black box. In this section you will zoom into this black box using 549 | additional deployment diagrams: 550 | 551 | - UML offers deployment diagrams to express that view. Use it, 552 | probably with nested diagrams, when your infrastructure is more 553 | complex. 554 | 555 | - When your (hardware) stakeholders prefer other kinds of diagrams 556 | rather than the deployment diagram, let them use any kind that is 557 | able to show nodes and channels of the infrastructure. 558 | 559 | Infrastructure Level 1 560 | ---------------------- 561 | 562 | Describe (usually in a combination of diagrams, tables, and text): 563 | 564 | - the distribution of your system to multiple locations, environments, 565 | computers, processors, .. as well as the physical connections 566 | between them 567 | 568 | - important justification or motivation for this deployment structure 569 | 570 | - Quality and/or performance features of the infrastructure 571 | 572 | - the mapping of software artifacts to elements of the infrastructure 573 | 574 | For multiple environments or alternative deployments please copy that 575 | section of arc42 for all relevant environments. 576 | 577 | ***<Overview Diagram>*** 578 | 579 | Motivation 580 | 581 | : *<explanation in text form>* 582 | 583 | Quality and/or Performance Features 584 | 585 | : *<explanation in text form>* 586 | 587 | Mapping of Building Blocks to Infrastructure 588 | 589 | : *<description of the mapping>* 590 | 591 | Infrastructure Level 2 592 | ---------------------- 593 | 594 | Here you can include the internal structure of (some) infrastructure 595 | elements from level 1. 596 | 597 | Please copy the structure from level 1 for each selected element. 598 | 599 | ### *<Infrastructure Element 1>* 600 | 601 | *<diagram + explanation>* 602 | 603 | ### *<Infrastructure Element 2>* 604 | 605 | *<diagram + explanation>* 606 | 607 | … 608 | 609 | ### *<Infrastructure Element n>* 610 | 611 | *<diagram + explanation>* 612 | 613 | Cross-cutting Concepts 614 | ====================== 615 | 616 | **Content.** 617 | 618 | This section describes overall, principal regulations and solution ideas 619 | that are relevant in multiple parts (= cross-cutting) of your system. 620 | Such concepts are often related to multiple building blocks. They can 621 | include many different topics, such as 622 | 623 | - domain models 624 | 625 | - architecture patterns or design patterns 626 | 627 | - rules for using specific technology 628 | 629 | - principal, often technical decisions of overall decisions 630 | 631 | - implementation rules 632 | 633 | **Motivation.** 634 | 635 | Concepts form the basis for *conceptual integrity* (consistency, 636 | homogeneity) of the architecture. Thus, they are an important 637 | contribution to achieve inner qualities of your system. 638 | 639 | Some of these concepts cannot be assigned to individual building blocks 640 | (e.g. security or safety). This is the place in the template that we 641 | provided for a cohesive specification of such concepts. 642 | 643 | **Form.** 644 | 645 | The form can be varied: 646 | 647 | - concept papers with any kind of structure 648 | 649 | - cross-cutting model excerpts or scenarios using notations of the 650 | architecture views 651 | 652 | - sample implementations, especially for technical concepts 653 | 654 | - reference to typical usage of standard frameworks (e.g. using 655 | Hibernate for object/relational mapping) 656 | 657 | **Structure.** 658 | 659 | A potential (but not mandatory) structure for this section could be: 660 | 661 | - Domain concepts 662 | 663 | - User Experience concepts (UX) 664 | 665 | - Safety and security concepts 666 | 667 | - Architecture and design patterns 668 | 669 | - "Under-the-hood" 670 | 671 | - development concepts 672 | 673 | - operational concepts 674 | 675 | Note: it might be difficult to assign individual concepts to one 676 | specific topic on this list. 677 | 678 | ![Possible topics for crosscutting concepts](images/08-Crosscutting-Concepts-Structure-EN.png) 679 | 680 | *<Concept 1>* 681 | ------------------- 682 | 683 | *<explanation>* 684 | 685 | *<Concept 2>* 686 | ------------------- 687 | 688 | *<explanation>* 689 | 690 | … 691 | 692 | *<Concept n>* 693 | ------------------- 694 | 695 | *<explanation>* 696 | 697 | Design Decisions 698 | ================ 699 | 700 | **Contents.** 701 | 702 | Important, expensive, large scale or risky architecture decisions 703 | including rationals. With "decisions" we mean selecting one alternative 704 | based on given criteria. 705 | 706 | Please use your judgement to decide whether an architectural decision 707 | should be documented here in this central section or whether you better 708 | document it locally (e.g. within the white box template of one building 709 | block). 710 | 711 | Avoid redundancy. Refer to section 4, where you already captured the 712 | most important decisions of your architecture. 713 | 714 | **Motivation.** 715 | 716 | Stakeholders of your system should be able to comprehend and retrace 717 | your decisions. 718 | 719 | **Form.** 720 | 721 | Various options: 722 | 723 | - List or table, ordered by importance and consequences or: 724 | 725 | - more detailed in form of separate sections per decision 726 | 727 | - ADR (architecture decision record) for every important decision 728 | 729 | Quality Requirements 730 | ==================== 731 | 732 | **Content.** 733 | 734 | This section contains all quality requirements as quality tree with 735 | scenarios. The most important ones have already been described in 736 | section 1.2. (quality goals) 737 | 738 | Here you can also capture quality requirements with lesser priority, 739 | which will not create high risks when they are not fully achieved. 740 | 741 | **Motivation.** 742 | 743 | Since quality requirements will have a lot of influence on architectural 744 | decisions you should know for every stakeholder what is really important 745 | to them, concrete and measurable. 746 | 747 | Quality Tree 748 | ------------ 749 | 750 | **Content.** 751 | 752 | The quality tree (as defined in ATAM – Architecture Tradeoff Analysis 753 | Method) with quality/evaluation scenarios as leafs. 754 | 755 | **Motivation.** 756 | 757 | The tree structure with priorities provides an overview for a sometimes 758 | large number of quality requirements. 759 | 760 | **Form.** 761 | 762 | The quality tree is a high-level overview of the quality goals and 763 | requirements: 764 | 765 | - tree-like refinement of the term "quality". Use "quality" or 766 | "usefulness" as a root 767 | 768 | - a mind map with quality categories as main branches 769 | 770 | In any case the tree should include links to the scenarios of the 771 | following section. 772 | 773 | Quality Scenarios 774 | ----------------- 775 | 776 | **Contents.** 777 | 778 | Concretization of (sometimes vague or implicit) quality requirements 779 | using (quality) scenarios. 780 | 781 | These scenarios describe what should happen when a stimulus arrives at 782 | the system. 783 | 784 | For architects, two kinds of scenarios are important: 785 | 786 | - Usage scenarios (also called application scenarios or use case 787 | scenarios) describe the system’s runtime reaction to a certain 788 | stimulus. This also includes scenarios that describe the system’s 789 | efficiency or performance. Example: The system reacts to a user’s 790 | request within one second. 791 | 792 | - Change scenarios describe a modification of the system or of its 793 | immediate environment. Example: Additional functionality is 794 | implemented or requirements for a quality attribute change. 795 | 796 | **Motivation.** 797 | 798 | Scenarios make quality requirements concrete and allow to more easily 799 | measure or decide whether they are fulfilled. 800 | 801 | Especially when you want to assess your architecture using methods like 802 | ATAM you need to describe your quality goals (from section 1.2) more 803 | precisely down to a level of scenarios that can be discussed and 804 | evaluated. 805 | 806 | **Form.** 807 | 808 | Tabular or free form text. 809 | 810 | Risks and Technical Debts 811 | ========================= 812 | 813 | **Contents.** 814 | 815 | A list of identified technical risks or technical debts, ordered by 816 | priority 817 | 818 | **Motivation.** 819 | 820 | “Risk management is project management for grown-ups” (Tim Lister, 821 | Atlantic Systems Guild.) 822 | 823 | This should be your motto for systematic detection and evaluation of 824 | risks and technical debts in the architecture, which will be needed by 825 | management stakeholders (e.g. project managers, product owners) as part 826 | of the overall risk analysis and measurement planning. 827 | 828 | **Form.** 829 | 830 | List of risks and/or technical debts, probably including suggested 831 | measures to minimize, mitigate or avoid risks or reduce technical debts. 832 | 833 | Glossary 834 | ======== 835 | 836 | **Contents.** 837 | 838 | The most important domain and technical terms that your stakeholders use 839 | when discussing the system. 840 | 841 | You can also see the glossary as source for translations if you work in 842 | multi-language teams. 843 | 844 | **Motivation.** 845 | 846 | You should clearly define your terms, so that all stakeholders 847 | 848 | - have an identical understanding of these terms 849 | 850 | - do not use synonyms and homonyms 851 | 852 | **Form.** 853 | 854 | A table with columns <Term> and <Definition>. 855 | 856 | Potentially more columns in case you need translations. 857 | 858 | | Term | Definition | 859 | | --------------------------------- | --------------------------------- | 860 | | Term 1 | <definition-1> | 861 | | Term 2 | <definition-2> | 862 | 863 | 864 | 865 | -------------------------------------------------------------------------------- /2. Single File/images/05_building_blocks-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/05_building_blocks-DE.png -------------------------------------------------------------------------------- /2. Single File/images/05_building_blocks-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/05_building_blocks-EN.png -------------------------------------------------------------------------------- /2. Single File/images/08-Crosscutting-Concepts-Structure-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/08-Crosscutting-Concepts-Structure-DE.png -------------------------------------------------------------------------------- /2. Single File/images/08-Crosscutting-Concepts-Structure-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/08-Crosscutting-Concepts-Structure-EN.png -------------------------------------------------------------------------------- /2. Single File/images/10_stimulus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/10_stimulus.png -------------------------------------------------------------------------------- /2. Single File/images/arc42-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/2. Single File/images/arc42-logo.png -------------------------------------------------------------------------------- /3. Flat Structure/01. Introduction and Goals.md: -------------------------------------------------------------------------------- 1 | Introduction and Goals 2 | ====================== 3 | 4 | Describes the relevant requirements and the driving forces that software 5 | architects and development team must consider. These include 6 | 7 | - underlying business goals, essential features and functional 8 | requirements for the system 9 | 10 | - quality goals for the architecture 11 | 12 | - relevant stakeholders and their expectations 13 | 14 | 15 | Requirements Overview 16 | --------------------- 17 | 18 | **Contents.** 19 | 20 | Short description of the functional requirements, driving forces, 21 | extract (or abstract) of requirements. Link to (hopefully existing) 22 | requirements documents (with version number and information where to 23 | find it). 24 | 25 | **Motivation.** 26 | 27 | From the point of view of the end users a system is created or modified 28 | to improve support of a business activity and/or improve the quality. 29 | 30 | **Form.** 31 | 32 | Short textual description, probably in tabular use-case format. If 33 | requirements documents exist this overview should refer to these 34 | documents. 35 | 36 | Keep these excerpts as short as possible. Balance readability of this 37 | document with potential redundancy w.r.t to requirements documents. 38 | 39 | Quality Goals 40 | ------------- 41 | 42 | **Contents.** 43 | 44 | The top three (max five) quality goals for the architecture whose 45 | fulfillment is of highest importance to the major stakeholders. We 46 | really mean quality goals for the architecture. Don’t confuse them with 47 | project goals. They are not necessarily identical. 48 | 49 | **Motivation.** 50 | 51 | You should know the quality goals of your most important stakeholders, 52 | since they will influence fundamental architectural decisions. Make sure 53 | to be very concrete about these qualities, avoid buzzwords. If you as an 54 | architect do not know how the quality of your work will be judged … 55 | 56 | **Form.** 57 | 58 | A table with quality goals and concrete scenarios, ordered by priorities 59 | 60 | Stakeholders 61 | ------------ 62 | 63 | **Contents.** 64 | 65 | Explicit overview of stakeholders of the system, i.e. all person, roles 66 | or organizations that 67 | 68 | - should know the architecture 69 | 70 | - have to be convinced of the architecture 71 | 72 | - have to work with the architecture or with code 73 | 74 | - need the documentation of the architecture for their work 75 | 76 | - have to come up with decisions about the system or its development 77 | 78 | **Motivation.** 79 | 80 | You should know all parties involved in development of the system or 81 | affected by the system. Otherwise, you may get nasty surprises later in 82 | the development process. These stakeholders determine the extent and the 83 | level of detail of your work and its results. 84 | 85 | **Form.** 86 | 87 | Table with role names, person names, and their expectations with respect 88 | to the architecture and its documentation. 89 | 90 | | Role/Name | Contact | Expectations | 91 | | ----------- | ------------------------- | ------------------------- | 92 | | Role-1 | Contact-1 | *<Expectation-1*> | 93 | | Role-2 | Contact-2 | *<Expectation-2*> | 94 | -------------------------------------------------------------------------------- /3. Flat Structure/02. Architecture Constraints.md: -------------------------------------------------------------------------------- 1 | Architecture Constraints 2 | ======================== 3 | 4 | **Contents.** 5 | 6 | Any requirement that constrains software architects in their freedom of 7 | design and implementation decisions or decision about the development 8 | process. These constraints sometimes go beyond individual systems and 9 | are valid for whole organizations and companies. 10 | 11 | **Motivation.** 12 | 13 | Architects should know exactly where they are free in their design 14 | decisions and where they must adhere to constraints. Constraints must 15 | always be dealt with; they may be negotiable, though. 16 | 17 | **Form.** 18 | 19 | Simple tables of constraints with explanations. If needed you can 20 | subdivide them into technical constraints, organizational and political 21 | constraints and conventions (e.g. programming or versioning guidelines, 22 | documentation or naming conventions) -------------------------------------------------------------------------------- /3. Flat Structure/03. Context and scope.md: -------------------------------------------------------------------------------- 1 | System Scope and Context 2 | ======================== 3 | 4 | **Contents.** 5 | 6 | System scope and context - as the name suggests - delimits your system 7 | (i.e. your scope) from all its communication partners (neighboring 8 | systems and users, i.e. the context of your system). It thereby 9 | specifies the external interfaces. 10 | 11 | If necessary, differentiate the business context (domain specific inputs 12 | and outputs) from the technical context (channels, protocols, hardware). 13 | 14 | **Motivation.** 15 | 16 | The domain interfaces and technical interfaces to communication partners 17 | are among your system’s most critical aspects. Make sure that you 18 | completely understand them. 19 | 20 | **Form.** 21 | 22 | Various options: 23 | 24 | - Context diagrams 25 | 26 | - Lists of communication partners and their interfaces. 27 | 28 | 29 | Business Context 30 | ---------------- 31 | 32 | **Contents.** 33 | 34 | Specification of **all** communication partners (users, IT-systems, …) 35 | with explanations of domain specific inputs and outputs or interfaces. 36 | Optionally you can add domain specific formats or communication 37 | protocols. 38 | 39 | **Motivation.** 40 | 41 | All stakeholders should understand which data are exchanged with the 42 | environment of the system. 43 | 44 | **Form.** 45 | 46 | All kinds of diagrams that show the system as a black box and specify 47 | the domain interfaces to communication partners. 48 | 49 | Alternatively (or additionally) you can use a table. The title of the 50 | table is the name of your system, the three columns contain the name of 51 | the communication partner, the inputs, and the outputs. 52 | 53 | **<Diagram or Table>** 54 | 55 | **<optionally: Explanation of external domain interfaces>** 56 | 57 | 58 | Technical Context 59 | ----------------- 60 | 61 | **Contents.** 62 | 63 | Technical interfaces (channels and transmission media) linking your 64 | system to its environment. In addition a mapping of domain specific 65 | input/output to the channels, i.e. an explanation with I/O uses which 66 | channel. 67 | 68 | **Motivation.** 69 | 70 | Many stakeholders make architectural decision based on the technical 71 | interfaces between the system and its context. Especially infrastructure 72 | or hardware designers decide these technical interfaces. 73 | 74 | **Form.** 75 | 76 | E.g. UML deployment diagram describing channels to neighboring systems, 77 | together with a mapping table showing the relationships between channels 78 | and input/output. 79 | 80 | **<Diagram or Table>** 81 | 82 | **<optionally: Explanation of technical interfaces>** 83 | 84 | **<Mapping Input/Output to Channels>** 85 | -------------------------------------------------------------------------------- /3. Flat Structure/04. Solution Strategy.md: -------------------------------------------------------------------------------- 1 | Solution Strategy 2 | ================= 3 | 4 | **Contents.** 5 | 6 | A short summary and explanation of the fundamental decisions and 7 | solution strategies, that shape the system’s architecture. These include 8 | 9 | - technology decisions 10 | 11 | - decisions about the top-level decomposition of the system, e.g. 12 | usage of an architectural pattern or design pattern 13 | 14 | - decisions on how to achieve key quality goals 15 | 16 | - relevant organizational decisions, e.g. selecting a development 17 | process or delegating certain tasks to third parties. 18 | 19 | **Motivation.** 20 | 21 | These decisions form the cornerstones for your architecture. They are 22 | the basis for many other detailed decisions or implementation rules. 23 | 24 | **Form.** 25 | 26 | Keep the explanation of these key decisions short. 27 | 28 | Motivate what you have decided and why you decided that way, based upon 29 | your problem statement, the quality goals and key constraints. Refer to 30 | details in the following sections. 31 | -------------------------------------------------------------------------------- /3. Flat Structure/05. Building Block View.md: -------------------------------------------------------------------------------- 1 | Building Block View 2 | =================== 3 | 4 | **Content.** 5 | 6 | The building block view shows the static decomposition of the system 7 | into building blocks (modules, components, subsystems, classes, 8 | interfaces, packages, libraries, frameworks, layers, partitions, tiers, 9 | functions, macros, operations, datas structures, …) as well as their 10 | dependencies (relationships, associations, …) 11 | 12 | This view is mandatory for every architecture documentation. In analogy 13 | to a house this is the *floor plan*. 14 | 15 | **Motivation.** 16 | 17 | Maintain an overview of your source code by making its structure 18 | understandable through abstraction. 19 | 20 | This allows you to communicate with your stakeholder on an abstract 21 | level without disclosing implementation details. 22 | 23 | **Form.** 24 | 25 | The building block view is a hierarchical collection of black boxes and 26 | white boxes (see figure below) and their descriptions. 27 | 28 | ![Hierarchy of building blocks](../images/05_building_blocks-EN.png) 29 | 30 | **Level 1** is the white box description of the overall system together 31 | with black box descriptions of all contained building blocks. 32 | 33 | **Level 2** zooms into some building blocks of level 1. Thus it contains 34 | the white box description of selected building blocks of level 1, 35 | together with black box descriptions of their internal building blocks. 36 | 37 | **Level 3** zooms into selected building blocks of level 2, and so on. 38 | 39 | Whitebox Overall System 40 | ----------------------- 41 | 42 | Here you describe the decomposition of the overall system using the 43 | following white box template. It contains 44 | 45 | - an overview diagram 46 | 47 | - a motivation for the decomposition 48 | 49 | - black box descriptions of the contained building blocks. For these 50 | we offer you alternatives: 51 | 52 | - use *one* table for a short and pragmatic overview of all 53 | contained building blocks and their interfaces 54 | 55 | - use a list of black box descriptions of the building blocks 56 | according to the black box template (see below). Depending on 57 | your choice of tool this list could be sub-chapters (in text 58 | files), sub-pages (in a Wiki) or nested elements (in a modeling 59 | tool). 60 | 61 | - (optional:) important interfaces, that are not explained in the 62 | black box templates of a building block, but are very important for 63 | understanding the white box. Since there are so many ways to specify 64 | interfaces why do not provide a specific template for them. In the 65 | worst case you have to specify and describe syntax, semantics, 66 | protocols, error handling, restrictions, versions, qualities, 67 | necessary compatibilities and many things more. In the best case you 68 | will get away with examples or simple signatures. 69 | 70 | ***<Overview Diagram>*** 71 | 72 | Motivation 73 | 74 | : *<text explanation>* 75 | 76 | Contained Building Blocks 77 | 78 | : *<Description of contained building block (black boxes)>* 79 | 80 | Important Interfaces 81 | 82 | : *<Description of important interfaces>* 83 | 84 | Insert your explanations of black boxes from level 1: 85 | 86 | If you use tabular form you will only describe your black boxes with 87 | name and responsibility according to the following schema: 88 | 89 | | **Name** | **Responsibility** | 90 | | -------------------- | -------------------------------------------- | 91 | | Black Box 1 |  *<Text>* | 92 | | Black Box 2 |  *<Text>* | 93 | 94 | If you use a list of black box descriptions then you fill in a separate 95 | black box template for every important building block . Its headline is 96 | the name of the black box. 97 | 98 | ### <Name black box 1> 99 | 100 | Here you describe <black box 1> according the the following black 101 | box template: 102 | 103 | - Purpose/Responsibility 104 | 105 | - Interface(s), when they are not extracted as separate paragraphs. 106 | This interfaces may include qualities and performance 107 | characteristics. 108 | 109 | - (Optional) Quality-/Performance characteristics of the black box, 110 | e.g.availability, run time behavior, …. 111 | 112 | - (Optional) directory/file location 113 | 114 | - (Optional) Fulfilled requirements (if you need traceability to 115 | requirements). 116 | 117 | - (Optional) Open issues/problems/risks 118 | 119 | *<Purpose/Responsibility>* 120 | 121 | *<Interface(s)>* 122 | 123 | *<(Optional) Quality/Performance Characteristics>* 124 | 125 | *<(Optional) Directory/File Location>* 126 | 127 | *<(Optional) Fulfilled Requirements>* 128 | 129 | *<(optional) Open Issues/Problems/Risks>* 130 | 131 | ### <Name black box 2> 132 | 133 | *<black box template>* 134 | 135 | ### <Name black box n> 136 | 137 | *<black box template>* 138 | 139 | ### <Name interface 1> 140 | 141 | … 142 | 143 | ### <Name interface m> 144 | 145 | Level 2 146 | ------- 147 | 148 | Here you can specify the inner structure of (some) building blocks from 149 | level 1 as white boxes. 150 | 151 | You have to decide which building blocks of your system are important 152 | enough to justify such a detailed description. Please prefer relevance 153 | over completeness. Specify important, surprising, risky, complex or 154 | volatile building blocks. Leave out normal, simple, boring or 155 | standardized parts of your system 156 | 157 | ### White Box *<building block 1>* 158 | 159 | …describes the internal structure of *building block 1*. 160 | 161 | *<white box template>* 162 | 163 | ### White Box *<building block 2>* 164 | 165 | *<white box template>* 166 | 167 | … 168 | ### White Box *<building block m>* 169 | 170 | *<white box template>* 171 | 172 | Level 3 173 | ------- 174 | 175 | Here you can specify the inner structure of (some) building blocks from 176 | level 2 as white boxes. 177 | 178 | When you need more detailed levels of your architecture please copy this 179 | part of arc42 for additional levels. 180 | 181 | ### White Box <\_building block x.1\_> 182 | 183 | Specifies the internal structure of *building block x.1*. 184 | 185 | *<white box template>* 186 | 187 | ### White Box <\_building block x.2\_> 188 | 189 | *<white box template>* 190 | 191 | ### White Box <\_building block y.1\_> 192 | 193 | *<white box template>* 194 | 195 | -------------------------------------------------------------------------------- /3. Flat Structure/06. Runtime View.md: -------------------------------------------------------------------------------- 1 | Runtime View 2 | ============ 3 | 4 | **Contents.** 5 | 6 | The runtime view describes concrete behavior and interactions of the 7 | system’s building blocks in form of scenarios from the following areas: 8 | 9 | - important use cases or features: how do building blocks execute 10 | them? 11 | 12 | - interactions at critical external interfaces: how do building blocks 13 | cooperate with users and neighboring systems? 14 | 15 | - operation and administration: launch, start-up, stop 16 | 17 | - error and exception scenarios 18 | 19 | Remark: The main criterion for the choice of possible scenarios 20 | (sequences, workflows) is their **architectural relevance**. It is 21 | **not** important to describe a large number of scenarios. You should 22 | rather document a representative selection. 23 | 24 | **Motivation.** 25 | 26 | You should understand how (instances of) building blocks of your system 27 | perform their job and communicate at runtime. You will mainly capture 28 | scenarios in your documentation to communicate your architecture to 29 | stakeholders that are less willing or able to read and understand the 30 | static models (building block view, deployment view). 31 | 32 | **Form.** 33 | 34 | There are many notations for describing scenarios, e.g. 35 | 36 | - numbered list of steps (in natural language) 37 | 38 | - activity diagrams or flow charts 39 | 40 | - sequence diagrams 41 | 42 | - BPMN or EPCs (event process chains) 43 | 44 | - state machines 45 | 46 | - … 47 | 48 | <Runtime Scenario 1> 49 | -------------------------- 50 | 51 | - *<insert runtime diagram or textual description of the 52 | scenario>* 53 | 54 | - *<insert description of the notable aspects of the interactions 55 | between the building block instances depicted in this diagram.>* 56 | 57 | <Runtime Scenario 2> 58 | -------------------------- 59 | 60 | ... 61 | 62 | <Runtime Scenario n> 63 | -------------------------- 64 | 65 | ... 66 | -------------------------------------------------------------------------------- /3. Flat Structure/07. Deployment View.md: -------------------------------------------------------------------------------- 1 | Deployment View 2 | =============== 3 | 4 | **Content.** 5 | 6 | The deployment view describes: 7 | 8 | 1. the technical infrastructure used to execute your system, with 9 | infrastructure elements like geographical locations, environments, 10 | computers, processors, channels and net topologies as well as other 11 | infrastructure elements and 12 | 13 | 2. the mapping of (software) building blocks to that infrastructure 14 | elements. 15 | 16 | Often systems are executed in different environments, e.g. development 17 | environment, test environment, production environment. In such cases you 18 | should document all relevant environments. 19 | 20 | Especially document the deployment view when your software is executed 21 | as distributed system with more then one computer, processor, server or 22 | container or when you design and construct your own hardware processors 23 | and chips. 24 | 25 | From a software perspective it is sufficient to capture those elements 26 | of the infrastructure that are needed to show the deployment of your 27 | building blocks. Hardware architects can go beyond that and describe the 28 | infrastructure to any level of detail they need to capture. 29 | 30 | **Motivation.** 31 | 32 | Software does not run without hardware. This underlying infrastructure 33 | can and will influence your system and/or some cross-cutting concepts. 34 | Therefore, you need to know the infrastructure. 35 | 36 | Maybe the highest level deployment diagram is already contained in 37 | section 3.2. as technical context with your own infrastructure as ONE 38 | black box. In this section you will zoom into this black box using 39 | additional deployment diagrams: 40 | 41 | - UML offers deployment diagrams to express that view. Use it, 42 | probably with nested diagrams, when your infrastructure is more 43 | complex. 44 | 45 | - When your (hardware) stakeholders prefer other kinds of diagrams 46 | rather than the deployment diagram, let them use any kind that is 47 | able to show nodes and channels of the infrastructure. 48 | 49 | Infrastructure Level 1 50 | ---------------------- 51 | 52 | Describe (usually in a combination of diagrams, tables, and text): 53 | 54 | - the distribution of your system to multiple locations, environments, 55 | computers, processors, .. as well as the physical connections 56 | between them 57 | 58 | - important justification or motivation for this deployment structure 59 | 60 | - Quality and/or performance features of the infrastructure 61 | 62 | - the mapping of software artifacts to elements of the infrastructure 63 | 64 | For multiple environments or alternative deployments please copy that 65 | section of arc42 for all relevant environments. 66 | 67 | ***<Overview Diagram>*** 68 | 69 | Motivation 70 | 71 | : *<explanation in text form>* 72 | 73 | Quality and/or Performance Features 74 | 75 | : *<explanation in text form>* 76 | 77 | Mapping of Building Blocks to Infrastructure 78 | 79 | : *<description of the mapping>* 80 | 81 | 82 | 83 | Infrastructure Level 2 84 | ---------------------- 85 | 86 | Here you can include the internal structure of (some) infrastructure 87 | elements from level 1. 88 | 89 | Please copy the structure from level 1 for each selected element. 90 | 91 | ### *<Infrastructure Element 1>* 92 | 93 | *<diagram + explanation>* 94 | 95 | ### *<Infrastructure Element 2>* 96 | 97 | *<diagram + explanation>* 98 | 99 | … 100 | 101 | ### *<Infrastructure Element n>* 102 | 103 | *<diagram + explanation>* 104 | 105 | -------------------------------------------------------------------------------- /3. Flat Structure/08. Crosscutting Concepts.md: -------------------------------------------------------------------------------- 1 | Cross-cutting Concepts 2 | ====================== 3 | 4 | **Content.** 5 | 6 | This section describes overall, principal regulations and solution ideas 7 | that are relevant in multiple parts (= cross-cutting) of your system. 8 | Such concepts are often related to multiple building blocks. They can 9 | include many different topics, such as 10 | 11 | - domain models 12 | 13 | - architecture patterns or design patterns 14 | 15 | - rules for using specific technology 16 | 17 | - principal, often technical decisions of overall decisions 18 | 19 | - implementation rules 20 | 21 | **Motivation.** 22 | 23 | Concepts form the basis for *conceptual integrity* (consistency, 24 | homogeneity) of the architecture. Thus, they are an important 25 | contribution to achieve inner qualities of your system. 26 | 27 | Some of these concepts cannot be assigned to individual building blocks 28 | (e.g. security or safety). This is the place in the template that we 29 | provided for a cohesive specification of such concepts. 30 | 31 | **Form.** 32 | 33 | The form can be varied: 34 | 35 | - concept papers with any kind of structure 36 | 37 | - cross-cutting model excerpts or scenarios using notations of the 38 | architecture views 39 | 40 | - sample implementations, especially for technical concepts 41 | 42 | - reference to typical usage of standard frameworks (e.g. using 43 | Hibernate for object/relational mapping) 44 | 45 | **Structure.** 46 | 47 | A potential (but not mandatory) structure for this section could be: 48 | 49 | - Domain concepts 50 | 51 | - User Experience concepts (UX) 52 | 53 | - Safety and security concepts 54 | 55 | - Architecture and design patterns 56 | 57 | - "Under-the-hood" 58 | 59 | - development concepts 60 | 61 | - operational concepts 62 | 63 | Note: it might be difficult to assign individual concepts to one 64 | specific topic on this list. 65 | 66 | ![Possible topics for crosscutting concepts](../images/08-Crosscutting-Concepts-Structure-EN.png) 67 | 68 | *<Concept 1>* 69 | ------------------- 70 | 71 | *<explanation>* 72 | 73 | *<Concept 2>* 74 | ------------------- 75 | 76 | *<explanation>* 77 | 78 | … 79 | 80 | *<Concept n>* 81 | ------------------- 82 | 83 | *<explanation>* 84 | -------------------------------------------------------------------------------- /3. Flat Structure/09. Architecture Decisions.md: -------------------------------------------------------------------------------- 1 | Design Decisions 2 | ================ 3 | 4 | **Contents.** 5 | 6 | Important, expensive, large scale or risky architecture decisions 7 | including rationals. With "decisions" we mean selecting one alternative 8 | based on given criteria. 9 | 10 | Please use your judgement to decide whether an architectural decision 11 | should be documented here in this central section or whether you better 12 | document it locally (e.g. within the white box template of one building 13 | block). 14 | 15 | Avoid redundancy. Refer to section 4, where you already captured the 16 | most important decisions of your architecture. 17 | 18 | **Motivation.** 19 | 20 | Stakeholders of your system should be able to comprehend and retrace 21 | your decisions. 22 | 23 | **Form.** 24 | 25 | Various options: 26 | 27 | - List or table, ordered by importance and consequences or: 28 | 29 | - more detailed in form of separate sections per decision 30 | 31 | - ADR (architecture decision record) for every important decision 32 | -------------------------------------------------------------------------------- /3. Flat Structure/10. Quality Requirements.md: -------------------------------------------------------------------------------- 1 | Quality Requirements 2 | ==================== 3 | 4 | **Content.** 5 | 6 | This section contains all quality requirements as quality tree with 7 | scenarios. The most important ones have already been described in 8 | section 1.2. (quality goals) 9 | 10 | Here you can also capture quality requirements with lesser priority, 11 | which will not create high risks when they are not fully achieved. 12 | 13 | **Motivation.** 14 | 15 | Since quality requirements will have a lot of influence on architectural 16 | decisions you should know for every stakeholder what is really important 17 | to them, concrete and measurable. 18 | 19 | Quality Tree 20 | ------------ 21 | 22 | **Content.** 23 | 24 | The quality tree (as defined in ATAM – Architecture Tradeoff Analysis 25 | Method) with quality/evaluation scenarios as leafs. 26 | 27 | **Motivation.** 28 | 29 | The tree structure with priorities provides an overview for a sometimes 30 | large number of quality requirements. 31 | 32 | **Form.** 33 | 34 | The quality tree is a high-level overview of the quality goals and 35 | requirements: 36 | 37 | - tree-like refinement of the term "quality". Use "quality" or 38 | "usefulness" as a root 39 | 40 | - a mind map with quality categories as main branches 41 | 42 | In any case the tree should include links to the scenarios of the 43 | following section. 44 | 45 | Quality Scenarios 46 | ----------------- 47 | 48 | **Contents.** 49 | 50 | Concretization of (sometimes vague or implicit) quality requirements 51 | using (quality) scenarios. 52 | 53 | These scenarios describe what should happen when a stimulus arrives at 54 | the system. 55 | 56 | For architects, two kinds of scenarios are important: 57 | 58 | - Usage scenarios (also called application scenarios or use case 59 | scenarios) describe the system’s runtime reaction to a certain 60 | stimulus. This also includes scenarios that describe the system’s 61 | efficiency or performance. Example: The system reacts to a user’s 62 | request within one second. 63 | 64 | - Change scenarios describe a modification of the system or of its 65 | immediate environment. Example: Additional functionality is 66 | implemented or requirements for a quality attribute change. 67 | 68 | **Motivation.** 69 | 70 | Scenarios make quality requirements concrete and allow to more easily 71 | measure or decide whether they are fulfilled. 72 | 73 | Especially when you want to assess your architecture using methods like 74 | ATAM you need to describe your quality goals (from section 1.2) more 75 | precisely down to a level of scenarios that can be discussed and 76 | evaluated. 77 | 78 | **Form.** 79 | 80 | Tabular or free form text. 81 | -------------------------------------------------------------------------------- /3. Flat Structure/11. Risks and Technical Debt.md: -------------------------------------------------------------------------------- 1 | Risks and Technical Debts 2 | ========================= 3 | 4 | **Contents.** 5 | 6 | A list of identified technical risks or technical debts, ordered by 7 | priority 8 | 9 | **Motivation.** 10 | 11 | “Risk management is project management for grown-ups” (Tim Lister, 12 | Atlantic Systems Guild.) 13 | 14 | This should be your motto for systematic detection and evaluation of 15 | risks and technical debts in the architecture, which will be needed by 16 | management stakeholders (e.g. project managers, product owners) as part 17 | of the overall risk analysis and measurement planning. 18 | 19 | **Form.** 20 | 21 | List of risks and/or technical debts, probably including suggested 22 | measures to minimize, mitigate or avoid risks or reduce technical debts. 23 | 24 | -------------------------------------------------------------------------------- /3. Flat Structure/12. Glossary.md: -------------------------------------------------------------------------------- 1 | Glossary 2 | ======== 3 | 4 | **Contents.** 5 | 6 | The most important domain and technical terms that your stakeholders use 7 | when discussing the system. 8 | 9 | You can also see the glossary as source for translations if you work in 10 | multi-language teams. 11 | 12 | **Motivation.** 13 | 14 | You should clearly define your terms, so that all stakeholders 15 | 16 | - have an identical understanding of these terms 17 | 18 | - do not use synonyms and homonyms 19 | 20 | **Form.** 21 | 22 | A table with columns <Term> and <Definition>. 23 | 24 | Potentially more columns in case you need translations. 25 | 26 | | Term | Definition | 27 | | --------------------------------- | --------------------------------- | 28 | | Term 1 | <definition-1> | 29 | | Term 2 | <definition-2> | 30 | 31 | 32 | -------------------------------------------------------------------------------- /3. Flat Structure/About arc42.md: -------------------------------------------------------------------------------- 1 | # About arc42 2 | 3 | arc42, the Template for documentation of software and system 4 | architecture. 5 | 6 | By Dr. Gernot Starke, Dr. Peter Hruschka and contributors. 7 | 8 | Template Revision: 7.0 EN (based on asciidoc), January 2017 9 | 10 | © We acknowledge that this document uses material from the arc 42 11 | architecture template, . Created by Dr. Peter 12 | Hruschka & Dr. Gernot Starke. 13 | 14 | > **Note** 15 | > 16 | > This version of the template contains some help and explanations. It 17 | > is used for familiarization with arc42 and the understanding of the 18 | > concepts. For documentation of your own system you use better the 19 | > *plain* version. 20 | 21 | 22 | ## 1. Introduction and Goals 23 | Short description of the requirements, driving forces, extract (or abstract) of requirements. Top three (max five) quality goals for the architecture which have highest priority for the major stakeholders. A table of important stakeholders with their expectation regarding architecture. 24 | ![Introduction and Goals](images/01-intro-and-goals.png) 25 | 26 | 27 | ## 2. Architecture Constraints 28 | Anything that constrains teams in design and implementation decisions or decision about related processes. Can sometimes go beyond individual systems and are valid for whole organizations and companies. 29 | ![Architecture Constraints](images/02-constraints-overview.png) 30 | 31 | ## 3. Context and scope 32 | Delimits your system from its (external) communication partners (neighboring systems and users). Specifies the external interfaces. Shown from a business/domain perspective (always) or a technical perspective (optional). 33 | ![Context and scope](images/03-context-overview.png) 34 | 35 | ## 4. Solution Strategy 36 | Summary of the fundamental decisions and solution strategies that shape the architecture. Can include technology, top-level decomposition, approaches to achieve top quality goals and relevant organizational decisions. 37 | ![Solution Strategy](images/04-solution-strategy-overview.png) 38 | 39 | ## 5. Building Block View 40 | Static decomposition of the system, abstractions of source-code, shown as hierarchy of white boxes (containing black boxes), up to the appropriate level of detail. 41 | ![Building Block View](images/05-building-block-overview.png) 42 | 43 | ## 6. Runtime View 44 | Behavior of building blocks as scenarios, covering important use cases or features, interactions at critical external interfaces, operation and administration plus error and exception behavior. 45 | ![Runtime View](images/06-runtime-overview.png) 46 | 47 | ## 7. Deployment View 48 | Technical infrastructure with environments, computers, processors, topologies. Mapping of (software) building blocks to infrastructure elements. 49 | ![Deployment View](images/07-deployment-overview.png) 50 | 51 | ## 8. Crosscutting Concepts 52 | Overall, principal regulations and solution approaches relevant in multiple parts (→ cross-cutting) of the system. Concepts are often related to multiple building blocks. Include different topics like domain models, architectur patterns and -styles, rules for using specific technology and inmplementation rules. 53 | ![Crosscutting Concepts](images/08-concepts-overview.png) 54 | 55 | ## 9. Architecture Decisions 56 | Important, expensive, critical, large scale or risky architecture decisions including rationals. 57 | ![Architecture Decisions](images/09-decision-overview.png) 58 | 59 | ## 10. Quality Requirements 60 | Quality requirements as scenarios, with quality tree to provide high-level overview. The most important quality goals should have been described in section 1.2. (quality goals). 61 | ![Quality Requirements](images/10-q-scenario-overview.png) 62 | 63 | ## 11. Risks and Technical Debt 64 | Known technical risks or technical debt. What potential problems exist within or around the system? What does the development team feel miserable about? 65 | ![Risks and Technical Debt](images/11-risk-overview.png) 66 | 67 | ## 12. Glossary 68 | Important domain and technical terms that stakeholders use when discussing he system. Also: translation reference if you work in a multi-language environment. 69 | ![Risks and Technical Debt](images/12-glossary-overview.png) 70 | -------------------------------------------------------------------------------- /3. Flat Structure/images/01-intro-and-goals.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/01-intro-and-goals.png -------------------------------------------------------------------------------- /3. Flat Structure/images/02-constraints-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/02-constraints-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/03-context-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/03-context-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/04-solution-strategy-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/04-solution-strategy-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/05-building-block-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/05-building-block-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/05_building_blocks-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/05_building_blocks-DE.png -------------------------------------------------------------------------------- /3. Flat Structure/images/05_building_blocks-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/05_building_blocks-EN.png -------------------------------------------------------------------------------- /3. Flat Structure/images/06-runtime-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/06-runtime-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/07-deployment-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/07-deployment-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/08-Crosscutting-Concepts-Structure-DE.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/08-Crosscutting-Concepts-Structure-DE.png -------------------------------------------------------------------------------- /3. Flat Structure/images/08-Crosscutting-Concepts-Structure-EN.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/08-Crosscutting-Concepts-Structure-EN.png -------------------------------------------------------------------------------- /3. Flat Structure/images/08-concepts-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/08-concepts-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/09-decision-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/09-decision-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/10-q-scenario-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/10-q-scenario-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/10_stimulus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/10_stimulus.png -------------------------------------------------------------------------------- /3. Flat Structure/images/11-risk-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/11-risk-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/12-glossary-overview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/12-glossary-overview.png -------------------------------------------------------------------------------- /3. Flat Structure/images/arc42-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/NetworkedAssets/arc42-in-markdown-template/9c3f20f196e86bcaae48f16ceea4a9fbb5e6d844/3. Flat Structure/images/arc42-logo.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Arc42 in Markdown 2 | 3 | Template of [arc42](http://arc42.org) in Markdown format. 4 | 5 | **About arc42** 6 | 7 | arc42, the Template for documentation of software and system 8 | architecture. 9 | 10 | By Dr. Gernot Starke, Dr. Peter Hruschka and contributors. 11 | 12 | Template Revision: 7.0 EN (based on asciidoc), January 2017 13 | 14 | © We acknowledge that this document uses material from the arc 42 15 | architecture template, . Created by Dr. Peter 16 | Hruschka & Dr. Gernot Starke. 17 | 18 | > **Note** 19 | > 20 | > This version of the template contains some help and explanations. It 21 | > is used for familiarization with arc42 and the understanding of the 22 | > concepts. For documentation of your own system you use better the 23 | > *plain* version. 24 | 25 | 26 | ## Templates 27 | There are available two templates: 28 | * [Multi File](1.%20Files%20Tree/00.%20About%20arc42.md) 29 | As a multiple files for each section 30 | * [Single File](2.%20Single%20File%2FArc42%20Template%20in%20Markdown.md) 31 | All sections in one big file 32 | 33 | ## Confluence Support 34 | [NetworkedAssets](http://networkedassets.com) offers free and paid Confluence plugins to manage documentation and it's process. 35 | 36 | ### Arc 42 Template for Confluence 37 | 38 | The **Arc42 Template for Confluence** is an add-on to create a space for the documentation of software architecture in confluence, depending on the english version of the [Arc42](http://arc42.org/) structure. 39 | The pagetree can also be inserted into already existing spaces via a page macro. 40 | 41 | See plugin details at: ATC Description 42 | User Guide: ATC User Guide (as PDF) 43 | Administration Guide: ATC Administration Guide (as PDF) 44 | 45 | Plugin available to download: 46 | - As JAR 47 | - On Atlassian Marketplace 48 | 49 | ### Manage My Tree for Confluence 50 | 51 | Plugin allows for: 52 | * moving pages (drag-n-drop) 53 | * renaming them (double-click or "Rename" button) 54 | * creating new pages ("Create" button) 55 | * removing unused pages ("Remove" button) 56 | 57 | Every change is performed on a copy of the page tree in memory. You can do any number of changes (adding, removing, renaming, and moving) on this tree before committing your work. 58 | 59 | See plugin details at: MMT Description 60 | User Guide: MMT User Guide (as PDF) 61 | Administration Guide: MMT Administration Guide (as PDF) 62 | 63 | Plugin available to download: 64 | - On Atlassian Marketplace 65 | 66 | 67 | ### Git4C - Git Viewer for Confluence 68 | 69 | Plugin allow to embed documentation from Git in Confluence. 70 | 71 | See plugin details at: Git Viewer for Confluence Description 72 | User Guide: Git Viewer for Confluence User Guide (as PDF) 73 | Administration Guide: Git Viewer for Confluence Administration Guide (as PDF) 74 | 75 | Plugin available to download: 76 | - On Atlassian Marketplace 77 | 78 | 79 | ![NetworkedAssets](https://www.networkedassets.com/wp-content/uploads/2016/12/NA_banner-home_v2.jpg) 80 | 81 | --------------------------------------------------------------------------------