@rse/specbook 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,53 +9,52 @@
9
9
  # Modeling Purpose
10
10
  # ----------------
11
11
  #
12
- # This schema allows to specify a large variety documents for the
12
+ # This schema allows specifying a large variety of documents for the
13
13
  # precise specification of solutions, systems and software.
14
14
  #
15
15
  # Modeling Coverage
16
16
  # -----------------
17
17
  #
18
- # | "Standard" SpecBook Object | PRD | StRS | SyRS | SRS | UIS | UISG | TCS | AD |
19
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
20
- # | META: Title | | | | | | | | |
21
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
22
- # | REQS: Solution Vision | X | X | | | | | | |
23
- # | REQS: Solution Premises | X | X | X | X | | | | |
24
- # | REQS: Domain Glossary | X | X | X | X | | | | |
25
- # | REQS: User Personas | X | X | X | X | X | | | |
26
- # | REQS: User Journey | X | X | | | X | | | |
27
- # | REQS: Functional Requirements | X | X | X | X | | | | |
28
- # | REQS: Non-Functional Requirements | X | X | X | X | X | | | |
29
- # | REQS: Domain Rules | | X | X | X | | | | |
30
- # | REQS: Domain Workflows | | X | X | X | | | | |
31
- # | REQS: Use Cases | | | X | X | X | | | |
32
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
33
- # | DATA: Data Model | | | X | X | | | | |
34
- # | DATA: State Model | | | X | X | | | | |
35
- # | DATA: Authorization Model | | | X | X | | | | |
36
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
37
- # | APIS: Interface Model | | | X | X | | | | |
38
- # | APIS: Interface Datatypes | | | | X | | | | |
39
- # | APIS: Interface Endpoints | | | | X | | | | |
40
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
41
- # | UXUI: Interaction Concept | | | | | X | X | | |
42
- # | UXUI: Language Conventions | | | | | X | X | | |
43
- # | UXUI: Dialog Patterns | | | | | X | X | | |
44
- # | UXUI: Dialog Storyboard | | | | | X | | | |
45
- # | UXUI: Visual Design | | | | | X | X | | |
46
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
47
- # | TEST: Test Cases | | | | | | | X | |
48
- # | --------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
49
- # | ARCH: Context View | | | | | | | | X |
50
- # | ARCH: Functionality View | | | | | | | | X |
51
- # | ARCH: Information View | | | | | | | | X |
52
- # | ARCH: Concurrency View | | | | | | | | X |
53
- # | ARCH: Development View | | | | | | | | X |
54
- # | ARCH: Deployment View | | | | | | | | X |
55
- # | ARCH: Operations View | | | | | | | | X |
56
- # | ARCH: Quality Perspectives | | | | | | | | X |
57
- # | ARCH: Decision Record | | | | | | | | X |
58
- # | ARCH: Technology Stack | | | | | | | | X |
18
+ # | "Standard" SpecBook Object | PRD | StRS | SyRS | SRS | UIS | UISG | TCS | AD |
19
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
20
+ # | META: Title (TI) | | | | | | | | |
21
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
22
+ # | REQS: Solution Vision (SV) | X | X | | | | | | |
23
+ # | REQS: Solution Premises (SP) | X | X | X | X | | | | |
24
+ # | REQS: Domain Glossary (DG) | X | X | X | X | | | | |
25
+ # | REQS: User Personas (UP) | X | X | X | X | X | | | |
26
+ # | REQS: User Journey (UJ) | X | X | | | X | | | |
27
+ # | REQS: Functional Requirements (FR) | X | X | X | X | | | | |
28
+ # | REQS: Non-Functional Requirements (NR) | X | X | X | X | X | | | |
29
+ # | REQS: Domain Rules (DR) | | X | X | X | | | | |
30
+ # | REQS: Domain Workflows (DW) | | X | X | X | | | | |
31
+ # | REQS: Use Cases (UC) | | | X | X | X | | | |
32
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
33
+ # | DATA: Data Model (DM) | | | X | X | | | | |
34
+ # | DATA: State Model (SM) | | | X | X | | | | |
35
+ # | DATA: Authorization Model (AM) | | | X | X | | | | |
36
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
37
+ # | APIS: Interface Model (IM) | | | X | X | | | | |
38
+ # | APIS: Interface Datatypes (ID) | | | | X | | | | |
39
+ # | APIS: Interface Endpoints (IE) | | | | X | | | | |
40
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
41
+ # | UXUI: Interaction Concept (IC) | | | | | X | X | | |
42
+ # | UXUI: Language Conventions (LC) | | | | | X | X | | |
43
+ # | UXUI: Dialog Patterns (DP) | | | | | X | X | | |
44
+ # | UXUI: Dialog Storyboard (DS) | | | | | X | | | |
45
+ # | UXUI: Visual Design (VD) | | | | | X | X | | |
46
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
47
+ # | ARCH: Context View (CV) | | | | | | | | X |
48
+ # | ARCH: Functionality View (FV) | | | | | | | | X |
49
+ # | ARCH: Technology Stack (TS) | | | | | | | | X |
50
+ # | ARCH: Development Aspects (DA) | | | | | | | | X |
51
+ # | ARCH: Concurrency View (CO) | | | | | | | | X |
52
+ # | ARCH: Deployment View (DV) | | | | | | | | X |
53
+ # | ARCH: Operations View (OV) | | | | | | | | X |
54
+ # | ARCH: Quality Perspectives (QP) | | | | | | | | X |
55
+ # | ARCH: Design Decisions (DD) | | | | | | | | X |
56
+ # | -------------------------------------- | --- | ---- | ---- | --- | --- | ---- | --- | --- |
57
+ # | TEST: Test Cases (TC) | | | | | | | X | |
59
58
  #
60
59
  # Legend:
61
60
  # - PRD: Product Requirements Document (Cagan 2005)
@@ -67,21 +66,30 @@
67
66
  # - TCS: Test Case Specification (ISO/IEC/IEEE 29119-3:2021)
68
67
  # - AD: Architecture Description (ISO/IEC/IEEE 42010)
69
68
  #
70
- # Design Decisions
71
- # ----------------
69
+ # Modeling Decisions
70
+ # ------------------
71
+ #
72
+ # - All artifacts have a unique 2-word name (e.g. "Context View") and a
73
+ # corresponding unique 2-letter identifier.
72
74
  #
73
75
  # - All object references are strictly back-references, i.e., later
74
- # objects reference earlier ones.
76
+ # objects reference earlier ones. Only the "referenced" coverage
77
+ # constraints and the diagram node sets (e.g. the inputs of a "hub"
78
+ # diagram) name later objects.
75
79
  #
76
80
  # - The depth of the modeling aspects is at maximum at level 3, which
77
81
  # means that all objects stay at level 1 and 2 and level 3 is mainly
78
82
  # for properties. This leads to decent headings and a not too deep
79
83
  # Table of Contents.
80
84
  #
85
+ # - All artifacts are optional, so that the schema can back not only
86
+ # a full specification but also the individual document types of
87
+ # the modeling coverage matrix above on their own.
88
+ #
81
89
  # - The traditional hard Software Requirements Specification (SRS)
82
90
  # vs. Architecture Description (AD) document split is
83
91
  # intentionally smoothed, so we can link from AD to SRS objects
84
- # and in AI-times (where no longer dedicated teams write
92
+ # and in AI-times (where dedicated teams no longer write
85
93
  # those documents separately) the AI should see one coherent
86
94
  # specification document, too.
87
95
  #
@@ -93,9 +101,10 @@
93
101
  desc: >
94
102
  The top-level specification meta information.
95
103
  Some of the information is rendered onto the title page.
104
+ optional: true
96
105
  diagram:
97
106
  type: graph
98
- nodes: "[[REQS:*]], [[DATA:*]], [[APIS:*]], [[UXUI:*]], [[TEST:*]], [[ARCH:*]]"
107
+ nodes: "[[REQS:*]], [[DATA:*]], [[APIS:*]], [[UXUI:*]], [[ARCH:*]], [[TEST:*]]"
99
108
  deep: true
100
109
  qualified: true
101
110
  props:
@@ -146,6 +155,7 @@
146
155
  desired future state it aims to achieve. Every vision aspect is
147
156
  stated in a concise (1-3 sentence) paragraph in an aspirational
148
157
  but unambiguous tone.
158
+ optional: true
149
159
  refs: >
150
160
  - ISO/IEC/IEEE 29148:2018: Systems and software engineering -- Life cycle processes -- Requirements engineering (2018),
151
161
  https://www.iso.org/standard/72089.html
@@ -201,6 +211,7 @@
201
211
  resting on a premise are known and revisited once it turns out to be false. The
202
212
  artifact complements the Solution Vision: the vision states what the solution aims
203
213
  for, the premises state what it takes as given on the way there.
214
+ optional: true
204
215
  refs: >
205
216
  - ISO/IEC/IEEE 29148:2018: Systems and software engineering -- Life cycle processes -- Requirements engineering (2018),
206
217
  https://www.iso.org/standard/72089.html
@@ -248,21 +259,6 @@
248
259
  behave as agreed), or `Risk` (an uncertain event which, if it occurs,
249
260
  harms the achievement of the vision).
250
261
  value: enum(Assumption,Dependency,Risk)
251
- - name: TERMS
252
- desc: >
253
- Comma-separated references to the GLOSSARY terms the premise is about
254
- (e.g. the external system a dependency relies on), anchoring it in the
255
- ubiquitous language.
256
- value: list([[REQS:GL.TERM:*]])
257
- optional: true
258
- - name: OWNER
259
- desc: >
260
- Reference to the User Personas object (usually a `Stakeholder`) who
261
- vouches for the premise, i.e. who confirms an assumption, holds the
262
- agreement of a dependency, or owns the mitigation of a risk, omitted when
263
- nobody in particular is accountable.
264
- value: "[[REQS:UP.PERSONA:*]]"
265
- optional: true
266
262
  - name: LIKELIHOOD
267
263
  desc: >
268
264
  The likelihood that the premise fails, i.e. that the assumption turns out
@@ -286,22 +282,16 @@
286
282
  detect it early (e.g. a fallback, a contract, a load test), omitted for
287
283
  a premise whose failure is knowingly accepted.
288
284
  optional: true
289
- - name: AFFECTS
290
- desc: >
291
- Comma-separated references to the FUNCTIONAL-REQUIREMENTS,
292
- NON-FUNCTIONAL-REQUIREMENTS, or DOMAIN-RULES objects resting on the
293
- premise, i.e. those to be revisited once it fails.
294
- value: list([[REQS:FR.*]], [[REQS:NR.*]], [[REQS:DR.RULE:*]])
295
- optional: true
296
285
 
297
286
  - kind: REQS
298
287
  name: Domain Glossary
299
- id: GL
300
- file: 03-REQS-GL-Domain-Glossary.md
288
+ id: DG
289
+ file: 03-REQS-DG-Domain-Glossary.md
301
290
  desc: >
302
291
  The ubiquitous language of the domain, defining the meaning of each domain term in business
303
292
  language, together with its synonyms, its place in the hierarchy of terms, and the terms it
304
293
  has to be kept apart from, shared consistently across all Artifacts.
294
+ optional: true
305
295
  refs: >
306
296
  - ISO 704:2022: Terminology work -- Principles and methods (2022),
307
297
  https://www.iso.org/standard/79077.html
@@ -311,7 +301,7 @@
311
301
  https://www.domainlanguage.com/ddd/
312
302
  diagram:
313
303
  type: grid
314
- nodes: "[[REQS:GL.TERM:*]]"
304
+ nodes: "[[REQS:DG.TERM:*]]"
315
305
  properties:
316
306
  - TYPE
317
307
  config:
@@ -337,7 +327,8 @@
337
327
  diagram:
338
328
  type: hub
339
329
  center: self
340
- nodes: "[[REQS:GL.TERM:*]], [[REQS:DR.RULE:*]], [[DATA:DM.ENTITY:*]], [[REQS:UP.PERSONA:*]]"
330
+ nodes: "[[REQS:DG.TERM:*]], [[REQS:SP.PREMISE:*]], [[REQS:DR.RULE:*]], [[DATA:DM.ENTITY:*]],
331
+ [[REQS:UP.PERSONA:*]]"
341
332
  labeled: true
342
333
  qualified: true
343
334
  config:
@@ -364,7 +355,7 @@
364
355
  that the terms form a hierarchy in which a rule governing the broader term
365
356
  covers the narrower ones, too; at most one broader term, keeping the
366
357
  hierarchy a tree.
367
- value: "[[REQS:GL.TERM:*]]"
358
+ value: "[[REQS:DG.TERM:*]]"
368
359
  optional: true
369
360
  acyclic: true
370
361
  - name: DISTINCT-FROM
@@ -372,9 +363,17 @@
372
363
  Comma-separated references to the GLOSSARY terms easily confused with this
373
364
  one but deliberately *not* synonymous, listed on both terms of each pair,
374
365
  with the distinction stated in the definitions.
375
- value: list([[REQS:GL.TERM:*]])
366
+ value: list([[REQS:DG.TERM:*]])
376
367
  optional: true
377
368
  symmetric: true
369
+ - name: PREMISES
370
+ desc: >
371
+ Comma-separated references to the SOLUTION-PREMISES objects about the
372
+ term, i.e. the assumptions, dependencies, and risks concerning the thing
373
+ or party it denotes (e.g. the dependency on the external system an
374
+ `Actor` term names), anchoring every premise in the ubiquitous language.
375
+ value: list([[REQS:SP.PREMISE:*]])
376
+ optional: true
378
377
 
379
378
  - kind: REQS
380
379
  name: User Personas
@@ -384,6 +383,7 @@
384
383
  The *archetypal* user profiles representing distinct user groups, capturing their goals,
385
384
  needs, behaviors, and context, complemented by the non-user stakeholders whose interests
386
385
  the solution has to serve.
386
+ optional: true
387
387
  refs: >
388
388
  - Cooper: The Inmates Are Running the Asylum, 2nd ed. (2004),
389
389
  https://www.informit.com/store/inmates-are-running-the-asylum-why-high-tech-products-9780672326141
@@ -391,6 +391,15 @@
391
391
  https://www.wiley.com/en-gb/About+Face:+The+Essentials+of+Interaction+Design,+4th+Edition-p-9781118766576
392
392
  - Pruitt/Adlin: The Persona Lifecycle: Keeping People in Mind Throughout Product Design (2006),
393
393
  https://www.sciencedirect.com/book/9780125662512/the-persona-lifecycle
394
+ diagram:
395
+ type: grid
396
+ nodes: "[[REQS:UP.PERSONA:*]]"
397
+ properties:
398
+ - TYPE
399
+ - ROLE
400
+ config:
401
+ size-node-width-max: 440
402
+ grid-columns-max: 4
394
403
  childs:
395
404
  - kind: PERSONA
396
405
  desc: >
@@ -433,7 +442,7 @@
433
442
  Comma-separated references to the GLOSSARY terms the persona embodies, i.e.
434
443
  the domain roles it acts in and the domain concepts it primarily deals
435
444
  with, so that every persona is anchored in the ubiquitous language.
436
- value: list([[REQS:GL.TERM:*]])
445
+ value: list([[REQS:DG.TERM:*]])
437
446
  optional: true
438
447
  - name: PROFICIENCY
439
448
  desc: >
@@ -451,6 +460,14 @@
451
460
  independently of the per-step pain points of the User Journey, which
452
461
  record the friction within the target journey instead.
453
462
  optional: true
463
+ - name: PREMISES
464
+ desc: >
465
+ Comma-separated references to the SOLUTION-PREMISES objects the persona
466
+ (usually a `Stakeholder`) vouches for, i.e. whose assumption it confirms,
467
+ whose dependency agreement it holds, or whose risk mitigation it owns;
468
+ omitted when the persona is accountable for no premise.
469
+ value: list([[REQS:SP.PREMISE:*]])
470
+ optional: true
454
471
 
455
472
  - kind: REQS
456
473
  name: User Journey
@@ -461,6 +478,7 @@
461
478
  mapping their steps, touchpoints, and emotions over time. The journey is the *target*
462
479
  journey with the solution in place, so the friction it records is what the solution has
463
480
  to mitigate, not the status quo it replaces.
481
+ optional: true
464
482
  refs: >
465
483
  - NN/g: Journey Mapping 101 (2018),
466
484
  https://www.nngroup.com/articles/journey-mapping-101/
@@ -536,6 +554,7 @@
536
554
  The concrete behaviors and capabilities the solution must provide, describing *what* the
537
555
  system does in terms of functions, features, and operations, while the quality bounds and
538
556
  constraints on them belong to the Non-Functional Requirements.
557
+ optional: true
539
558
  refs: >
540
559
  - Mavin et al.: Easy Approach to Requirements Syntax (EARS) (2009),
541
560
  https://ieeexplore.ieee.org/document/5328509
@@ -577,6 +596,13 @@
577
596
  time"), preserving the conscious decision rather than silently dropping it,
578
597
  with the statement still phrased as it would be if in scope.
579
598
  value: enum(MUST,SHOULD,COULD,WONT)
599
+ - name: PREMISES
600
+ desc: >
601
+ Comma-separated references to the SOLUTION-PREMISES objects the
602
+ requirement rests on, i.e. the assumptions, dependencies, and risks whose
603
+ failure calls for revisiting it.
604
+ value: list([[REQS:SP.PREMISE:*]])
605
+ optional: true
580
606
 
581
607
  - kind: REQS
582
608
  name: Non-Functional Requirements
@@ -585,6 +611,7 @@
585
611
  desc: >
586
612
  The quality attributes and constraints the solution must satisfy, such as performance,
587
613
  security, scalability, reliability, and usability.
614
+ optional: true
588
615
  refs: >
589
616
  - ISO/IEC 25010:2023: Systems and software engineering -- Systems and software Quality Requirements and Evaluation (SQuaRE) -- Product quality model (2023),
590
617
  https://www.iso.org/standard/78176.html
@@ -638,6 +665,13 @@
638
665
  capability the requirement bounds or constrains.
639
666
  value: list([[REQS:FR.*]])
640
667
  optional: true
668
+ - name: PREMISES
669
+ desc: >
670
+ Comma-separated references to the SOLUTION-PREMISES objects the
671
+ requirement rests on, i.e. the assumptions, dependencies, and risks whose
672
+ failure calls for revisiting it.
673
+ value: list([[REQS:SP.PREMISE:*]])
674
+ optional: true
641
675
  - name: METRIC
642
676
  desc: >
643
677
  The threshold or target by which the requirement is judged satisfied,
@@ -653,6 +687,7 @@
653
687
  The domain invariants, policies, and decision logic that must always hold true in the
654
688
  problem domain, independent of any single feature, constraining the Functional and
655
689
  Non-Functional Requirements.
690
+ optional: true
656
691
  refs: >
657
692
  - Hay/Healy: Defining Business Rules ~ What Are They Really? (2000),
658
693
  https://www.businessrulesgroup.org/first_paper/br01c0.htm
@@ -728,7 +763,7 @@
728
763
  Comma-separated references to the GLOSSARY terms the rule governs, i.e.
729
764
  the domain terms its statement is about, so that every rule is anchored in
730
765
  the ubiquitous language and every term shows the rules that hold for it.
731
- value: list([[REQS:GL.TERM:*]])
766
+ value: list([[REQS:DG.TERM:*]])
732
767
  optional: true
733
768
  - name: CONSTRAINS
734
769
  desc: >
@@ -736,6 +771,13 @@
736
771
  NON-FUNCTIONAL-REQUIREMENTS objects the rule constrains.
737
772
  value: list([[REQS:FR.*]], [[REQS:NR.*]])
738
773
  optional: true
774
+ - name: PREMISES
775
+ desc: >
776
+ Comma-separated references to the SOLUTION-PREMISES objects the rule
777
+ rests on, i.e. the assumptions, dependencies, and risks whose failure
778
+ calls for revisiting it.
779
+ value: list([[REQS:SP.PREMISE:*]])
780
+ optional: true
739
781
 
740
782
  - kind: REQS
741
783
  name: Domain Workflows
@@ -831,7 +873,7 @@
831
873
  desc: >
832
874
  Comma-separated references to the GLOSSARY terms of type `Activity` the
833
875
  workflow realizes, anchoring it in the ubiquitous language.
834
- value: list([[REQS:GL.TERM:*]])
876
+ value: list([[REQS:DG.TERM:*]])
835
877
  optional: true
836
878
  - name: RULES
837
879
  desc: >
@@ -919,6 +961,7 @@
919
961
  The discrete goals users pursue with the solution, each describing an actor's interaction to
920
962
  achieve a specific outcome, together with the concrete step-by-step flows for main,
921
963
  alternative, and exceptional paths.
964
+ optional: true
922
965
  refs: >
923
966
  - Cockburn: Writing Effective Use Cases (2001),
924
967
  https://www.informit.com/store/writing-effective-use-cases-9780201702255
@@ -990,14 +1033,6 @@
990
1033
  (e.g. an access rule in an authentication step).
991
1034
  value: list([[REQS:DR.RULE:*]])
992
1035
  optional: true
993
- - name: TRANSITIONS
994
- desc: >
995
- Comma-separated references to the STATE-MODEL transition objects the
996
- scenarios of the use case trigger, i.e. whose state change a scenario
997
- step causes, so that every transition is exercised by at least one use
998
- case or test case.
999
- value: list([[DATA:SM.LIFECYCLE:*.TRANSITION:*]])
1000
- optional: true
1001
1036
  - name: INCLUDES
1002
1037
  desc: >
1003
1038
  Comma-separated references to the other USE-CASES objects this use case
@@ -1079,6 +1114,7 @@
1079
1114
  desc: >
1080
1115
  The structure of named entities, with named attributes and directed relationships, of the
1081
1116
  data the solution manages, defining how information is organized and connected.
1117
+ optional: true
1082
1118
  refs: >
1083
1119
  - Chen: The Entity-Relationship Model -- Toward a Unified View of Data (1976),
1084
1120
  https://dl.acm.org/doi/10.1145/320434.320440
@@ -1115,7 +1151,7 @@
1115
1151
  Comma-separated references to the GLOSSARY terms the entity materializes,
1116
1152
  i.e. the domain terms whose information it carries, so that every entity
1117
1153
  is anchored in the ubiquitous language and every term shows its data.
1118
- value: list([[REQS:GL.TERM:*]])
1154
+ value: list([[REQS:DG.TERM:*]])
1119
1155
  optional: true
1120
1156
  childs:
1121
1157
  - kind: ATTRIBUTE
@@ -1214,6 +1250,7 @@
1214
1250
  For each entity with a non-trivial lifecycle, the legal states it can occupy and the
1215
1251
  permitted transitions between them over its lifetime, making the forbidden moves as explicit
1216
1252
  as the allowed ones.
1253
+ optional: true
1217
1254
  refs: >
1218
1255
  - Shlaer/Mellor: Object Lifecycles: Modeling the World in States (1992)
1219
1256
  - Harel: Statecharts: A Visual Formalism for Complex Systems (1987),
@@ -1308,9 +1345,6 @@
1308
1345
  arrive at the very state it departs from (an internal transition, e.g.
1309
1346
  `edit` on `Draft`). Any move not listed as a transition is implicitly
1310
1347
  forbidden.
1311
- referenced:
1312
- - "[[REQS:UC.USE-CASE:*]]"
1313
- - "[[TEST:TC.TEST-CASE:*]]"
1314
1348
  props:
1315
1349
  - name: FROM
1316
1350
  desc: The state (of the same lifecycle) the transition departs from.
@@ -1341,6 +1375,15 @@
1341
1375
  transition enforces, usually through its `GUARD`.
1342
1376
  value: list([[REQS:DR.RULE:*]])
1343
1377
  optional: true
1378
+ - name: USE-CASES
1379
+ desc: >
1380
+ Comma-separated references to the USE-CASES objects whose
1381
+ scenarios trigger the transition, i.e. in which a scenario step
1382
+ causes the state change, tracing the transition into the use
1383
+ cases exercising it; omitted for a transition no use case
1384
+ triggers (e.g. one triggered by `Time` or by the system alone).
1385
+ value: list([[REQS:UC.USE-CASE:*]])
1386
+ optional: true
1344
1387
 
1345
1388
  - kind: DATA
1346
1389
  name: Authorization Model
@@ -1354,6 +1397,7 @@
1354
1397
  actors of the state transitions, the actors of the use cases, and the prose of the domain
1355
1398
  rules. The model is closed: an operation not granted to a role is forbidden, exactly like
1356
1399
  a move not listed as a state transition.
1400
+ optional: true
1357
1401
  refs: >
1358
1402
  - Ferraiolo/Kuhn: Role-Based Access Controls, 15th National Computer Security Conference (1992),
1359
1403
  https://csrc.nist.gov/publications/detail/conference-paper/1992/10/13/role-based-access-controls
@@ -1372,6 +1416,7 @@
1372
1416
  qualified: true
1373
1417
  config:
1374
1418
  size-node-width-max: 440
1419
+ graph-channel-width-max: 340
1375
1420
  childs:
1376
1421
  - kind: ROLE
1377
1422
  desc: >
@@ -1386,7 +1431,7 @@
1386
1431
  type: hub
1387
1432
  center: self
1388
1433
  deep: true
1389
- nodes: "[[DATA:AM.ROLE:*]], [[REQS:UP.PERSONA:*]], [[REQS:GL.TERM:*]], [[DATA:DM.ENTITY:*]],
1434
+ nodes: "[[DATA:AM.ROLE:*]], [[REQS:UP.PERSONA:*]], [[REQS:DG.TERM:*]], [[DATA:DM.ENTITY:*]],
1390
1435
  [[REQS:DR.RULE:*]]"
1391
1436
  labeled: true
1392
1437
  qualified: true
@@ -1403,12 +1448,12 @@
1403
1448
  `Actor` denoting the external systems holding the role (e.g. a registration
1404
1449
  system calling the machine-facing interface), as an external system is no
1405
1450
  persona.
1406
- value: list([[REQS:UP.PERSONA:*]], [[REQS:GL.TERM:*]])
1451
+ value: list([[REQS:UP.PERSONA:*]], [[REQS:DG.TERM:*]])
1407
1452
  - name: TERM
1408
1453
  desc: >
1409
1454
  Reference to the GLOSSARY term of type `Actor` the role grants, anchoring
1410
1455
  the role in the ubiquitous language.
1411
- value: "[[REQS:GL.TERM:*]]"
1456
+ value: "[[REQS:DG.TERM:*]]"
1412
1457
  optional: true
1413
1458
  - name: INHERITS
1414
1459
  desc: >
@@ -1583,6 +1628,7 @@
1583
1628
  nodes: "[[APIS:ID.TYPE:*]]"
1584
1629
  deep: true
1585
1630
  onlyConnected: true
1631
+ labeled: true
1586
1632
  qualified: true
1587
1633
  config:
1588
1634
  size-node-width-max: 440
@@ -1745,6 +1791,7 @@
1745
1791
  nodes: "[[APIS:IE.ENDPOINT:*]], [[APIS:ID.TYPE:*]]"
1746
1792
  deep: true
1747
1793
  onlyConnected: true
1794
+ labeled: true
1748
1795
  qualified: true
1749
1796
  config:
1750
1797
  size-node-width-max: 440
@@ -2003,6 +2050,15 @@
2003
2050
  quality bound is a Non-Functional Requirement instead).
2004
2051
  referenced:
2005
2052
  - "[[UXUI:DP.PATTERN:*]]"
2053
+ diagram:
2054
+ type: hub
2055
+ center: self
2056
+ nodes: "[[UXUI:IC.PRINCIPLE:*]], [[REQS:UP.PERSONA:*]], [[REQS:UJ.JOURNEY:*.STEP:*]],
2057
+ [[UXUI:DP.PATTERN:*]]"
2058
+ labeled: true
2059
+ qualified: true
2060
+ config:
2061
+ size-node-width-max: 440
2006
2062
  props:
2007
2063
  - name: CATEGORY
2008
2064
  desc: >
@@ -2043,7 +2099,7 @@
2043
2099
  Concept states how it behaves, the Language Conventions how it talks, and the Visual Design
2044
2100
  how it looks. Domain terms are *defined* in the Domain Glossary and only *surfaced* here,
2045
2101
  while the conventions of the specification text itself and of code identifiers are out of
2046
- scope (they belong to the Development View).
2102
+ scope (they belong to the Development Aspects).
2047
2103
  refs: >
2048
2104
  - Podmajersky: Strategic Writing for UX (2019),
2049
2105
  https://www.oreilly.com/library/view/strategic-writing-for/9781492049388/
@@ -2102,7 +2158,7 @@
2102
2158
  Comma-separated references to the GLOSSARY terms whose surfacing in the
2103
2159
  user-facing text the convention governs, so that the Domain Glossary defines
2104
2160
  the term and the convention states how it is written.
2105
- value: list([[REQS:GL.TERM:*]])
2161
+ value: list([[REQS:DG.TERM:*]])
2106
2162
  optional: true
2107
2163
  - name: EXAMPLE
2108
2164
  desc: >
@@ -2151,6 +2207,7 @@
2151
2207
  center: self
2152
2208
  nodes: "[[UXUI:DP.PATTERN:*]], [[UXUI:IC.PRINCIPLE:*]], [[UXUI:DS.STORYBOARD:*]]"
2153
2209
  deep: true
2210
+ labeled: true
2154
2211
  qualified: true
2155
2212
  config:
2156
2213
  size-node-width-max: 440
@@ -2232,7 +2289,7 @@
2232
2289
  desc: >
2233
2290
  A single depicted dialog flow, named with a short (3-8 word) summary of the flow and
2234
2291
  comprised of frames in sequence. A storyboard shows the concrete user interface of
2235
- one flow, as seen by its actors (the intent and the information exchanged is a Use
2292
+ one flow, as seen by its actors (the intent and the information exchanged are a Use
2236
2293
  Cases scenario instead, and a structure recurring across flows is a Dialog Pattern
2237
2294
  instead).
2238
2295
  diagram:
@@ -2241,6 +2298,7 @@
2241
2298
  nodes: "[[UXUI:DS.STORYBOARD:*]], [[REQS:UP.PERSONA:*]],
2242
2299
  [[REQS:UC.USE-CASE:*.SCENARIO:*]], [[UXUI:DP.PATTERN:*]]"
2243
2300
  deep: true
2301
+ labeled: true
2244
2302
  qualified: true
2245
2303
  config:
2246
2304
  size-node-width-max: 440
@@ -2352,6 +2410,7 @@
2352
2410
  type: hub
2353
2411
  center: self
2354
2412
  nodes: "[[UXUI:VD.ELEMENT:*]], [[REQS:UP.PERSONA:*]], [[UXUI:IC.PRINCIPLE:*]], [[UXUI:VD.MOCKUP:*]]"
2413
+ labeled: true
2355
2414
  qualified: true
2356
2415
  config:
2357
2416
  size-node-width-max: 440
@@ -2429,135 +2488,16 @@
2429
2488
  the design tool or a screenshot of an already existing user interface, so
2430
2489
  that the look is seen rather than only read.
2431
2490
 
2432
- - kind: TEST
2433
- name: Test Cases
2434
- id: TC
2435
- file: 22-TEST-TC-Test-Cases.md
2436
- desc: >
2437
- The verifiable conditions and steps used to confirm that requirements, domain rules, use
2438
- case scenarios, and state transitions are correctly implemented, with mandatory defined
2439
- inputs, mandatory expected outcomes, and optional pre- and post-conditions.
2440
-
2441
- Test cases are not derived from use cases alone: a use case scenario describes an intent-level
2442
- flow, while a test case fixes the concrete data and the observable assertions that decide pass
2443
- or fail, and many test cases (e.g. of Non-Functional Requirements or of cross-session rules)
2444
- have no use case counterpart at all.
2445
- refs: >
2446
- - ISO/IEC/IEEE 29119-3:2021: Software and systems engineering -- Software testing -- Part 3: Test documentation (2021),
2447
- https://www.iso.org/standard/79429.html
2448
- - ISO/IEC/IEEE 29119-4:2021: Software and systems engineering -- Software testing -- Part 4: Test techniques (2021),
2449
- https://www.iso.org/standard/79430.html
2450
- - ISTQB CTFL 4.0: Certified Tester Foundation Level Syllabus (2023),
2451
- https://istqb.org/certifications/certified-tester-foundation-level-ctfl-v4-0/
2452
- diagram:
2453
- type: grid
2454
- nodes: "[[TEST:TC.TEST-CASE:*]]"
2455
- config:
2456
- size-node-width-max: 440
2457
- size-node-height-scale: 2
2458
- grid-columns-max: 4
2459
- childs:
2460
- - kind: TEST-CASE
2461
- desc: >
2462
- A single verifiable test case, named with a short (3-8 word) summary and defined by
2463
- its mandatory input and expected outcome plus its optional pre- and post-conditions.
2464
-
2465
- The test case is at verification level: it pins down what the objects it verifies
2466
- leave open, namely concrete data (e.g. `the correct six-digit token`), a boundary
2467
- or equivalence class (e.g. `one more question within the same minute`), and an
2468
- observable assertion, including the negative one (e.g. `the rejected question is
2469
- not stored and the earlier questions remain unchanged`).
2470
-
2471
- A test case which merely rephrases a scenario in different words, adding none of these,
2472
- is redundant and should be sharpened or dropped. Conversely, one scenario can require
2473
- several test cases (one per boundary or equivalence class), and one test case can
2474
- verify a requirement, a rule, and a scenario at once.
2475
-
2476
- A test case whose stimulus is a sequence rather than a single action carries the
2477
- procedure in its body as sequentially numbered, imperative steps, mirroring the
2478
- steps of a use case scenario (e.g. `1. The user logs in on device A. 2. The same
2479
- user logs in on device B.`), with `INPUT` naming the decisive stimulus among them.
2480
- diagram:
2481
- type: hub
2482
- center: self
2483
- nodes: "[[TEST:TC.TEST-CASE:*]], [[REQS:FR.REQUIREMENT:*]], [[REQS:NR.REQUIREMENT:*]],
2484
- [[REQS:DR.RULE:*]], [[REQS:UC.USE-CASE:*.SCENARIO:*]], [[REQS:DW.WORKFLOW:*]],
2485
- [[DATA:SM.LIFECYCLE:*.TRANSITION:*]], [[DATA:DM.ENTITY:*.ATTRIBUTE:*]],
2486
- [[DATA:AM.ROLE:*.PERMISSION:*]], [[APIS:IE.ENDPOINT:*]],
2487
- [[UXUI:DS.STORYBOARD:*.FRAME:*]]"
2488
- labeled: true
2489
- qualified: true
2490
- config:
2491
- size-node-width-max: 440
2492
- size-node-height-scale: 1.75
2493
- props:
2494
- - name: VERIFIES
2495
- desc: >
2496
- Comma-separated references to the FUNCTIONAL-REQUIREMENTS or
2497
- NON-FUNCTIONAL-REQUIREMENTS objects, the DOMAIN-RULES objects, the
2498
- USE-CASES scenario objects, the STATE-MODEL transition objects, the
2499
- DATA-MODEL attribute objects, the AUTHORIZATION-MODEL permission objects,
2500
- the INTERFACE-ENDPOINTS objects, and/or the DIALOG-STORYBOARD frame objects
2501
- the test case verifies, so that a scenario (in particular an `Exceptional`
2502
- one, judged by its `OUTCOME`) is covered by an acceptance test beside the
2503
- requirements it exercises, a rule (judged by the condition it states) is
2504
- proven to hold, not just to be documented, a transition (judged by its
2505
- `GUARD` and the resulting state) is proven to be permitted exactly as
2506
- modeled, an attribute (judged by its `TYPE` and `CONSTRAINT`) is proven to
2507
- reject the values outside its range, pattern, or invariant, a permission
2508
- (judged by the operations it grants and, the model being closed, by the
2509
- ones it denies) is proven to be enforced, an endpoint (judged by its
2510
- arguments, options, and results) is proven to honor its contract, and a
2511
- frame (judged by the dialog step it storyboards) is proven to be reachable
2512
- and to behave as storyboarded.
2513
- value: list([[REQS:*.REQUIREMENT:*]], [[REQS:DR.RULE:*]], [[REQS:UC.USE-CASE:*.SCENARIO:*]],
2514
- [[DATA:SM.LIFECYCLE:*.TRANSITION:*]], [[DATA:DM.ENTITY:*.ATTRIBUTE:*]],
2515
- [[DATA:AM.ROLE:*.PERMISSION:*]], [[APIS:IE.ENDPOINT:*]],
2516
- [[UXUI:DS.STORYBOARD:*.FRAME:*]])
2517
- - name: WORKFLOWS
2518
- desc: >
2519
- Comma-separated references to the DOMAIN-WORKFLOWS objects the test case
2520
- walks through end to end, i.e. whose activities and handoffs its procedure
2521
- steps cross in order, so that the collaboration across actors and sittings
2522
- (not just the use cases of each single sitting) is proven to work as
2523
- modeled; omitted for a test case confined to a single sitting.
2524
- value: list([[REQS:DW.WORKFLOW:*]])
2525
- optional: true
2526
- - name: PRE-CONDITION
2527
- desc: >
2528
- The state or setup that must hold before the test is executed.
2529
- optional: true
2530
- - name: INPUT
2531
- desc: >
2532
- The mandatory, concrete input data or action applied during the test, i.e.
2533
- the stimulus whose response the `EXPECTED` judges.
2534
- - name: EXPECTED
2535
- desc: >
2536
- The mandatory, concrete, observable response of the solution to the `INPUT`
2537
- (a message shown, a session issued, a submission rejected) that defines a
2538
- passing test, as opposed to the `POST-CONDITION` which is the state left
2539
- behind. When the test case verifies a NON-FUNCTIONAL-REQUIREMENTS object,
2540
- the expected response restates the `METRIC` threshold of that requirement
2541
- as the pass criterion (e.g. `p95 latency < 200 ms`) rather than a
2542
- qualitative phrase (e.g. `remains responsive`).
2543
- - name: POST-CONDITION
2544
- desc: >
2545
- The persisted state that must hold after the test completes (e.g. `the
2546
- authorization token is in state used`), including the state that must not
2547
- have changed (e.g. `no session token exists`), as opposed to the `EXPECTED`
2548
- which is the immediate response, and omitted for a test whose input leaves
2549
- no state behind.
2550
- optional: true
2551
-
2552
2491
  - kind: ARCH
2553
2492
  name: Context View
2554
2493
  id: CV
2555
- file: 23-ARCH-CV-Context-View.md
2494
+ file: 22-ARCH-CV-Context-View.md
2556
2495
  desc: >
2557
2496
  The relationships, dependencies, and interactions between the solution and its environment,
2558
2497
  defining the system's boundary by enumerating the external entities sitting at it. The
2559
2498
  artifact complements the Solution Vision: its `SCOPE` states what is deliberately *out* of
2560
2499
  the solution, the Context View enumerates what the solution touches *at* the boundary.
2500
+ optional: true
2561
2501
  refs: >
2562
2502
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Context Viewpoint (2011),
2563
2503
  https://www.viewpoints-and-perspectives.info/home/viewpoints/context/
@@ -2584,8 +2524,8 @@
2584
2524
  - kind: ENTITY
2585
2525
  desc: >
2586
2526
  A single external entity the solution interacts with, named with a short (2-5 word)
2587
- summary (e.g. `Payment Gateway`, `Identity Provider`, `End User`) and described in a
2588
- concise (1-3 sentence) paragraph by the relationship and dependency between the
2527
+ summary (e.g. `Payment Gateway`, `Identity Provider`, `End User`) and described in
2528
+ a concise (1-3 sentence) paragraph by the relationship and dependency between the
2589
2529
  solution and the entity, plus a 1-sentence rationale ("why") for the entity being
2590
2530
  part of the system context.
2591
2531
 
@@ -2593,8 +2533,8 @@
2593
2533
  boundary: a party with a mere interest in the solution but no such exchange is a
2594
2534
  `Stakeholder` persona of the User Personas instead, and a platform element the
2595
2535
  solution deploys and operates itself (e.g. a managed database of its own) is a
2596
- Deployment View node instead -- only a party or system the solution merely
2597
- consumes or serves belongs to the system context.
2536
+ Deployment View node instead -- only a party or system the solution merely consumes
2537
+ or serves belongs to the system context.
2598
2538
  format:
2599
2539
  maxTableColumns: 5
2600
2540
  props:
@@ -2623,7 +2563,7 @@
2623
2563
  the domain (usually a term of type `Actor`, which covers an external system
2624
2564
  as a party acting in the domain), anchoring every boundary entity in the
2625
2565
  ubiquitous language.
2626
- value: list([[REQS:GL.TERM:*]])
2566
+ value: list([[REQS:DG.TERM:*]])
2627
2567
  optional: true
2628
2568
  - name: INTERFACE
2629
2569
  desc: >
@@ -2660,10 +2600,12 @@
2660
2600
  - kind: ARCH
2661
2601
  name: Functionality View
2662
2602
  id: FV
2663
- file: 24-ARCH-FV-Functionality-View.md
2603
+ file: 23-ARCH-FV-Functionality-View.md
2664
2604
  desc: >
2665
2605
  The functional components of the solution, their responsibilities, interfaces, and primary
2666
- interactions, describing *what* the system does at runtime.
2606
+ interactions, describing *how* the solution's runtime elements are structured and which
2607
+ responsibility each owns, delivering the behaviors the Functional Requirements state.
2608
+ optional: true
2667
2609
  refs: >
2668
2610
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Functional Viewpoint (2011),
2669
2611
  https://www.viewpoints-and-perspectives.info/home/viewpoints/functional/
@@ -2674,6 +2616,7 @@
2674
2616
  diagram:
2675
2617
  type: graph
2676
2618
  nodes: "[[ARCH:FV.COMPONENT:*]]"
2619
+ labeled: true
2677
2620
  properties:
2678
2621
  - KIND
2679
2622
  childs:
@@ -2681,35 +2624,63 @@
2681
2624
  desc: >
2682
2625
  A single functional component, named with a short (2-5 word) summary (e.g.
2683
2626
  `Authentication Service`, `Order Processor`, `Notification Dispatcher`) and
2684
- described in a concise (1-3 sentence) paragraph by *what* it does and how it
2685
- collaborates with the components it depends on, plus a 1-sentence rationale ("why")
2686
- for the component's existence and boundary.
2627
+ described in a concise (1-3 sentence) paragraph whose first sentence names the
2628
+ single, primary responsibility the component owns (split into several components
2629
+ otherwise) and which elaborates how the component fulfills it and collaborates
2630
+ with the components it depends on, plus a 1-sentence rationale ("why") for the
2631
+ component's existence and boundary.
2687
2632
  format:
2688
2633
  maxTableColumns: 5
2689
2634
  diagram:
2690
2635
  type: hub
2691
2636
  center: self
2692
- nodes: "[[ARCH:FV.COMPONENT:*]]"
2637
+ nodes: "[[ARCH:FV.COMPONENT:*]], [[REQS:FR.REQUIREMENT:*]], [[APIS:IM.INTERFACE:*]],
2638
+ [[DATA:DM.ENTITY:*]]"
2639
+ labeled: true
2640
+ qualified: true
2693
2641
  properties:
2694
2642
  - KIND
2695
2643
  config:
2696
- size-node-width-max: 440
2644
+ size-node-width-max: 440
2645
+ size-node-height-scale: 1.75
2697
2646
  props:
2698
2647
  - name: KIND
2699
2648
  desc: |
2700
2649
  The kind of the functional component, one of:
2701
2650
  - `Component`: Cohesive unit of functionality with a defined interface.
2702
- - `Service`: Independently deployable provider of functionality.
2651
+ - `Service`: Provider of functionality with an independent lifecycle.
2703
2652
  - `Module`: Logical grouping of related functionality within a
2704
2653
  component.
2705
2654
  - `Connector`: Mediator that conveys interactions between components
2706
2655
  (e.g. bus, gateway).
2707
2656
  - `Subsystem`: Larger composite grouping several components.
2708
2657
  value: enum(Component,Service,Module,Connector,Subsystem)
2709
- - name: RESPONSIBILITY
2658
+ - name: PART-OF
2710
2659
  desc: >
2711
- The 1-sentence statement of the single, primary responsibility the component
2712
- owns.
2660
+ Reference to the FUNCTIONALITY-VIEW object this component is contained
2661
+ in, expressing the composition hierarchy the kinds imply: a `Module`
2662
+ references the component it groups functionality within, and a component
2663
+ references the `Subsystem` it belongs to; omitted for a top-level
2664
+ component.
2665
+ value: "[[ARCH:FV.COMPONENT:*]]"
2666
+ optional: true
2667
+ acyclic: true
2668
+ - name: REALIZES
2669
+ desc: >
2670
+ Comma-separated references to the FUNCTIONAL-REQUIREMENTS objects the
2671
+ component realizes, i.e. whose capability its functionality delivers, so
2672
+ that every Functional Requirement is owned by at least one component.
2673
+ value: list([[REQS:FR.*]])
2674
+ optional: true
2675
+ - name: OWNS
2676
+ desc: >
2677
+ Comma-separated references to the DATA-MODEL entities the component owns,
2678
+ i.e. for which it is the single authoritative source of truth (other
2679
+ components access an owned entity through the owner's interfaces or hold
2680
+ derived copies only), so that every entity is owned by at most one
2681
+ component; omitted when the component owns no entity.
2682
+ value: list([[DATA:DM.ENTITY:*]])
2683
+ optional: true
2713
2684
  - name: PROVIDES
2714
2685
  desc: >
2715
2686
  Comma-separated references to the INTERFACE-MODEL objects the component
@@ -2718,138 +2689,382 @@
2718
2689
  (e.g. a user interface or an internal module).
2719
2690
  value: list([[APIS:IM.INTERFACE:*]])
2720
2691
  optional: true
2692
+ - name: CONSUMES
2693
+ desc: >
2694
+ Comma-separated references to the INTERFACE-MODEL objects the component
2695
+ consumes, i.e. the `Provided` interfaces of other components and the
2696
+ `Required` interfaces offered by external entities, through which its
2697
+ dependencies are exercised; omitted when the component consumes no
2698
+ modeled interface.
2699
+ value: list([[APIS:IM.INTERFACE:*]])
2700
+ optional: true
2721
2701
  - name: DEPENDS-ON
2722
2702
  desc: >
2723
2703
  Comma-separated references to the FUNCTIONALITY-VIEW objects this component
2724
- depends on at runtime.
2704
+ depends on at runtime, naming the target component only, while the
2705
+ interface through which a dependency is exercised is stated by `CONSUMES`
2706
+ where modeled.
2725
2707
  value: list([[ARCH:FV.COMPONENT:*]])
2726
2708
  optional: true
2727
2709
 
2728
2710
  - kind: ARCH
2729
- name: Information View
2730
- id: IV
2731
- file: 25-ARCH-IV-Information-View.md
2711
+ name: Technology Stack
2712
+ id: TS
2713
+ file: 24-ARCH-TS-Technology-Stack.md
2732
2714
  desc: >
2733
- The way the solution stores, manages, manipulates, and distributes information, defining the
2734
- static data structure and dynamic information flow.
2715
+ The concrete technology products the solution is built upon, organized by tier and lifecycle
2716
+ phase, recording for each component its chosen product, its purpose, and the alternatives
2717
+ that were considered but not chosen.
2718
+ optional: true
2735
2719
  refs: >
2736
- - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Information Viewpoint (2011),
2737
- https://www.viewpoints-and-perspectives.info/home/viewpoints/information/
2738
- - Kleppmann: Designing Data-Intensive Applications (2017),
2739
- https://dataintensive.net/
2720
+ - Starke/Hruschka: arc42 Template: Solution Strategy and Crosscutting Concepts (2005),
2721
+ https://arc42.org/overview
2722
+ - Brown: The C4 Model: Container Diagram (2018),
2723
+ https://c4model.com/diagrams/container
2740
2724
  diagram:
2741
2725
  type: grid
2742
- nodes: "[[ARCH:IV.ASPECT:*]]"
2743
- properties:
2744
- - CONCERN
2726
+ nodes: "[[ARCH:TS.TIER:*]]"
2745
2727
  childs:
2746
- - kind: ASPECT
2747
- desc: >
2748
- A single information aspect, named with a short (2-5 word) summary (e.g. `Order
2749
- Persistence`, `Event Stream`, `Cache Coherency`) and described in a concise (1-3
2750
- sentence) paragraph by how the solution stores, manages, or distributes the
2751
- information and how its consistency is upheld, plus a 1-sentence rationale ("why")
2752
- for handling the information this way.
2728
+ - kind: TIER
2729
+ desc: |
2730
+ The architectural tier grouping the technology components belonging to it, named
2731
+ with a short (1-2 word) summary mirroring the name of the Deployment View tier
2732
+ referencing it through `STACK`, typically one of:
2733
+
2734
+ - `Client`: Runs on the client side (e.g. browser, desktop, mobile).
2735
+ - `Server`: Runs on the server side (e.g. backend, application, API).
2736
+ - `Middleware`: Runs between client and server (e.g. message broker, gateway).
2737
+ - `Database`: Runs as the data store (e.g. relational or document database).
2738
+ - `Common`: Runs on several tiers alike (e.g. a language, a logging library,
2739
+ or a shared module used by client and server), so a product
2740
+ used on several tiers is a single component here instead of
2741
+ one per tier; referenced by no Deployment View tier.
2753
2742
  diagram:
2754
2743
  type: hub
2755
2744
  center: self
2756
- nodes: "[[ARCH:IV.ASPECT:*]], [[DATA:DM.ENTITY:*]], [[ARCH:FV.COMPONENT:*]]"
2757
- qualified: true
2745
+ hierarchy: true
2758
2746
  properties:
2759
- - CONCERN
2747
+ - PRODUCT
2760
2748
  config:
2761
2749
  size-node-width-max: 440
2762
- props:
2763
- - name: CONCERN
2764
- desc: >
2765
- The information-handling concern the aspect addresses: `Persistence`,
2766
- `Flow`, `Ownership`, `Consistency`, `Replication`, `Caching`, `Retention`,
2767
- or `Migration`.
2768
- value: enum(Persistence,Flow,Ownership,Consistency,Replication,Caching,Retention,Migration)
2769
- - name: ENTITIES
2770
- desc: >
2771
- Comma-separated references to the DATA-MODEL entities the aspect governs.
2772
- value: list([[DATA:DM.ENTITY:*]])
2773
- optional: true
2774
- - name: OWNER
2775
- desc: >
2776
- Reference to the FUNCTIONALITY-VIEW object that owns this information.
2777
- value: "[[ARCH:FV.COMPONENT:*]]"
2778
- optional: true
2779
- - name: LIFECYCLE
2750
+ size-node-height-scale: 1.75
2751
+ childs:
2752
+ - kind: COMPONENT
2780
2753
  desc: >
2781
- How the information comes into being, changes, and is disposed of (e.g.
2782
- `created on order, retained 7 years, then purged`).
2754
+ A single technology component, named with a short (2-5 word) summary (e.g.
2755
+ `UI Framework`, `Web Server`, `Relational Database`) and described in a
2756
+ concise (1-3 sentence) paragraph by how the product is used within the
2757
+ solution and how it fits into the overall technology stack, plus a
2758
+ 1-sentence rationale ("why") for choosing this product over the
2759
+ alternatives.
2783
2760
 
2784
- - kind: ARCH
2785
- name: Concurrency View
2786
- id: CO
2787
- file: 26-ARCH-CO-Concurrency-View.md
2788
- desc: >
2789
- The concurrency structure of the solution, mapping functional components to processes and
2790
- threads, and defining how they coordinate and communicate.
2791
- refs: >
2792
- - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Concurrency Viewpoint (2011),
2793
- https://www.viewpoints-and-perspectives.info/home/viewpoints/concurrency/
2794
- - Kruchten: Architectural Blueprints -- The "4+1" View Model of Software Architecture (1995),
2795
- https://ieeexplore.ieee.org/document/469759
2796
- - Schmidt et al.: Pattern-Oriented Software Architecture, Volume 2: Patterns for Concurrent and Networked Objects (2000),
2797
- https://www.wiley.com/en-us/Pattern+Oriented+Software+Architecture,+Volume+2,+Patterns+for+Concurrent+and+Networked+Objects-p-9781118725177
2798
- diagram:
2799
- type: grid
2800
- nodes: "[[ARCH:CO.UNIT:*]]"
2801
- properties:
2802
- - KIND
2803
- childs:
2804
- - kind: UNIT
2805
- desc: >
2806
- A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker
2807
- Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise
2808
- (1-3 sentence) paragraph by how it executes and how it avoids or manages contention,
2809
- races, and deadlocks, plus a 1-sentence rationale ("why") for the chosen concurrency
2810
- structure.
2811
- diagram:
2812
- type: hub
2813
- center: self
2814
- nodes: "[[ARCH:CO.UNIT:*]], [[ARCH:FV.COMPONENT:*]]"
2815
- qualified: true
2816
- properties:
2817
- - KIND
2818
- config:
2819
- size-node-width-max: 440
2820
- props:
2821
- - name: KIND
2822
- desc: |
2823
- The kind of the concurrency unit, one of:
2761
+ A component states one product in one role on one tier: the product used
2762
+ by several tiers alike belongs to the `Common` tier once, the lock-in
2763
+ carrying trade-off behind the choice is a Design Decisions decision
2764
+ referencing the component through `DECIDES`, and the functional components
2765
+ depending on the product reference it through `USED-BY`.
2766
+ diagram:
2767
+ type: hub
2768
+ center: self
2769
+ nodes: "[[ARCH:TS.TIER:*.COMPONENT:*]], [[ARCH:FV.COMPONENT:*]],
2770
+ [[ARCH:DD.DECISION:*]]"
2771
+ labeled: true
2772
+ qualified: true
2773
+ properties:
2774
+ - PRODUCT
2775
+ - PHASE
2776
+ config:
2777
+ size-node-width-max: 440
2778
+ size-node-height-scale: 1.75
2779
+ props:
2780
+ - name: PRODUCT
2781
+ desc: >
2782
+ The concrete product, library, or framework chosen for this
2783
+ component (e.g. `VueJS`, `Node.js`, `PostgreSQL`).
2784
+ - name: ALTERNATIVES
2785
+ desc: >
2786
+ Comma-separated names of the products which would also fit this
2787
+ component but were not chosen (e.g. `React, Svelte`): the
2788
+ rationale of the description states *why* the product won, this
2789
+ property states *against what*, so it is expected whenever the
2790
+ rationale compares the product against others; omitted when there
2791
+ was no real alternative.
2792
+ optional: true
2793
+ - name: LICENSE
2794
+ desc: >
2795
+ The license under which the product is used (e.g. `MIT`,
2796
+ `Apache-2.0`, `AGPL-3.0`, `commercial`, `in-house`), the evidence
2797
+ for a Non-Functional Requirement of category `Compliance`;
2798
+ omitted when the license is of no concern to the solution.
2799
+ optional: true
2800
+ - name: PHASE
2801
+ desc: |
2802
+ The lifecycle phases in which the component is relevant, one or
2803
+ more of:
2804
+
2805
+ - `Build-Time`: Used during development, compilation, or
2806
+ packaging.
2807
+ - `Run-Time`: Used while the solution executes in
2808
+ production.
2809
+ - `Operate-Time`: Used to operate the solution in production
2810
+ (e.g. for rollout, monitoring, or backup),
2811
+ referenced by the Operations View concerns
2812
+ through `TOOLS`.
2813
+ value: tags(Build-Time,Run-Time,Operate-Time)
2814
+ - name: COVERAGE
2815
+ desc: |
2816
+ A comma-separated list of the aspects the component covers, drawn
2817
+ from the catalog of its `PHASE`: for `Build-Time` the *Build-Time
2818
+ Aspects* (the categories of the Development Aspects), for
2819
+ `Operate-Time` the *Operate-Time Aspects* (the categories of the
2820
+ Operations View concerns), and for `Run-Time` the *Client*,
2821
+ *Server*, *Middleware*, or *Database Aspects* of the component's
2822
+ `TIER` (a `Common` tier component draws from the catalogs of all
2823
+ tiers it serves), each defined below with its typical sub-aspects
2824
+ as an explanation only. The general goal is to achieve a maximum
2825
+ coverage of all aspects per tier and phase with the minimum total
2826
+ number of `PRODUCT`s.
2827
+
2828
+ The *Build-Time Aspects* which usually have to be covered (the
2829
+ Development Aspects `CATEGORY` values):
2830
+ - **Structure**:
2831
+ Module Layout, Package Layout, Workspace.
2832
+ - **Build**:
2833
+ Compilation, Transpilation, Bundling, Packaging.
2834
+ - **Dependency**:
2835
+ Dependency Management, Lock File, Vulnerability Audit.
2836
+ - **Codeline**:
2837
+ Version Control, Branching, Merging, Versioning, Release
2838
+ Tagging.
2839
+ - **Standardization**:
2840
+ Linting, Formatting, Type Checking, Coding Conventions.
2841
+ - **Testing**:
2842
+ Unit Testing, Integration Testing, End-to-End Testing,
2843
+ Coverage Measurement.
2844
+ - **Tooling**:
2845
+ Task Running, Code Generation, Development Automation.
2846
+
2847
+ The *Operate-Time Aspects* which usually have to be covered (the
2848
+ Operations View `CATEGORY` values):
2849
+ - **Installation**:
2850
+ Provisioning, Container Orchestration, Infrastructure as
2851
+ Code.
2852
+ - **Configuration**:
2853
+ Configuration Management, Secret Management, Environment
2854
+ Files.
2855
+ - **Migration**:
2856
+ Data Migration, Schema Migration, Environment Promotion.
2857
+ - **Monitoring**:
2858
+ Metrics, Health Checks, Dashboards, Tracing.
2859
+ - **Logging**:
2860
+ Log Collection, Log Retention, Log Inspection.
2861
+ - **Alerting**:
2862
+ Notification, Escalation, On-Call Paging.
2863
+ - **Backup**:
2864
+ Dumps, Snapshots, Backup Storage.
2865
+ - **Recovery**:
2866
+ Restore, Failover, Point-in-Time Recovery.
2867
+ - **Upgrade**:
2868
+ Rollout, Rolling Update, Rollback, Image Distribution.
2869
+ - **Capacity**:
2870
+ Scaling, Autoscaling, Capacity Planning.
2871
+ - **Administration**:
2872
+ User Administration, Data Retention, Certificate Rotation.
2873
+ - **Incident**:
2874
+ Troubleshooting, Diagnostics, Post-Mortem.
2875
+ - **Support**:
2876
+ Ticketing, Knowledge Base, Escalation.
2877
+
2878
+ The *Client Aspects* which usually have to be covered (at least
2879
+ for clients in a Rich-Client architecture):
2824
2880
 
2825
- - `Process`: An independent OS process with its own address space.
2826
- - `Thread`: A thread of execution within a process.
2827
- - `Pool`: A managed group of interchangeable workers.
2828
- - `Queue`: An asynchronous buffer decoupling producers and consumers.
2829
- - `EventLoop`: A single-threaded cooperative scheduler of tasks.
2830
- value: enum(Process,Thread,Pool,Queue,EventLoop)
2831
- - name: HOSTS
2832
- desc: >
2833
- Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside
2834
- this concurrency unit.
2835
- value: list([[ARCH:FV.COMPONENT:*]])
2836
- optional: true
2837
- - name: MULTIPLICITY
2838
- desc: >
2839
- How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n
2840
- auto-scaled`).
2841
- - name: COORDINATION
2842
- desc: >
2843
- The mechanism by which the unit coordinates or communicates with other units
2844
- (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
2881
+ - **Interface Theme**:
2882
+ Style Reset, Shape, Color, Gradient, Shadow, Font, Icon.
2883
+ - **Interface Widgets**:
2884
+ Icon, Label, Text Paragraph, Image, Form, Text-Field,
2885
+ Text-Area, Date Picker, Toggle, Radio Button, Checkbox,
2886
+ Select List, Slider, Progress Bar, Hyperlink, Popup Menu,
2887
+ Dropdown Menu, Toolbar, Tooltip, Tab, Pill, Breadcrumb,
2888
+ Pagination, Badge, Alert, Panel, Modal, Table, Scrollbar,
2889
+ Carousel.
2890
+ - **Interface Layouting**:
2891
+ Responsive Design, Media Query, Frame, Grid, Padding, Border,
2892
+ Margin, Alignment, Force, Magnetism.
2893
+ - **Interface Effects**:
2894
+ Transition, Transformation, Keyframes, Easing Function, Sound
2895
+ Effect, Physics.
2896
+ - **Interface Interactions**:
2897
+ Mouse, Keyboard, Touchscreen, Gesture, Clipboard, Drag & Drop.
2898
+ - **Interface States**:
2899
+ Rendered, Enabled, Visible, Focused, Warning, Error, Floating.
2900
+ - **Interface Mask**:
2901
+ Markup Loading, Markup Generation, Virtual DOM, Text, Bitmaps,
2902
+ Vectors, 2D/3D Canvas, Accessibility.
2903
+ - **Interface Internationalization**:
2904
+ Text Internationalization (I18N).
2905
+ - **Data Conversion**:
2906
+ Value Formatting, Value Parsing, Localization (L10N).
2907
+ - **Data Binding**:
2908
+ Reactive, Observer, Unidirectional, Bidirectional, Incremental.
2909
+ - **Presentation Model**:
2910
+ Parameter Value, Command Value, State Value, Data Value, Event
2911
+ Value, Value Validation, Presentation Logic.
2912
+ - **Dialog Navigation**:
2913
+ Deep Linking, Routing, Dialog Flow.
2914
+ - **Dialog Automation**:
2915
+ Dialog Macros, Click-Through, Smoke Testing.
2916
+ - **Dialog Communication**:
2917
+ Service, Event, Model, Socket, Hooks.
2918
+ - **Dialog Life-Cycle**:
2919
+ Component States, Component State Transitions.
2920
+ - **Dialog Structure**:
2921
+ Component, Model/View/Controller Roles, Hierarchical
2922
+ Composition.
2923
+ - **State Persistence**:
2924
+ Local Storage, Cookies, Caching.
2925
+ - **Business Model**:
2926
+ Entity, Field, Relationship, Universally Unique Identifiers
2927
+ (UUID).
2928
+ - **Use-Case Authorization**:
2929
+ User Experience, Dialog Restriction, User, Group, Role,
2930
+ Use-Case, Data, Access.
2931
+ - **Client Networking**:
2932
+ Request/Response, Synchronization, Push, Pull, Pulled-Push,
2933
+ REST, GraphQL, Authentication, Session.
2934
+ - **Environment Detection**:
2935
+ Runtime Detection, Feature Detection.
2936
+
2937
+ The *Server Aspects* which usually have to be covered (at least
2938
+ for servers, sometimes called Thin-Servers, in a Rich-Client
2939
+ architecture):
2940
+
2941
+ - **Environment Detection**:
2942
+ Operating System, Execution Platform, Network Topology,
2943
+ Feature Toggles.
2944
+ - **Argument Parsing**:
2945
+ CLI Options, CLI Arguments, Bootstrapping Parameters.
2946
+ - **Configuration Parsing**:
2947
+ Configuration File, Environment Variables, Directives.
2948
+ - **Process Daemonizing**:
2949
+ Terminal Detaching, Host Process Detaching, PID File.
2950
+ - **Process Management**:
2951
+ Pre-Forking, Child Processes, Threads, Supervision.
2952
+ - **Component Management**:
2953
+ Component Structure, Instantiation, Component Life-Cycle.
2954
+ - **Component Communication**:
2955
+ Events, Hooks, Registry, Dependency Injection.
2956
+ - **Server Networking**:
2957
+ Socket Listening, Connection Acceptance, Request/Response,
2958
+ Messaging.
2959
+ - **Peer Information**:
2960
+ Peer Identification, Peer Address, User Agent.
2961
+ - **Session Handling**:
2962
+ Session State, Session Security, Session Expiry.
2963
+ - **User Authentication**:
2964
+ Identity, Credentials, Tokens, Single Sign-On.
2965
+ - **Request Validation**:
2966
+ Syntax Validation, Semantic Validation, Sanitizing.
2967
+ - **Request Processing**:
2968
+ Dispatching, Routing, Context Determination.
2969
+ - **Role Authorization**:
2970
+ Role, Permission, Access Control.
2971
+ - **Client Networking**:
2972
+ Peer Connection, Request/Response, Publish/Subscribe.
2973
+ - **Task Scheduling**:
2974
+ Recurring Tasks, Cron, Job Queue.
2975
+ - **Execution Tracing**:
2976
+ Logging, Metrics, Measurement, Tracing.
2977
+ - **Database Access**:
2978
+ Object-Relational Mapping, Query Building, Entity Mapping.
2979
+ - **Database Connectivity**:
2980
+ Driver, Connection Pooling, Local/Remote Connection.
2981
+ - **Database Schema**:
2982
+ Schema Creation, Schema Upgrade, Schema Downgrade.
2983
+ - **Database Bootstrapping**:
2984
+ Mandatory Data, Domain Data, Seeding, Fixtures.
2985
+
2986
+ The *Middleware Aspects* which usually have to be covered (at
2987
+ least for solutions with a dedicated tier between client and
2988
+ server):
2989
+
2990
+ - **Message Brokering**:
2991
+ Publish/Subscribe, Queues, Topics, Delivery Guarantees,
2992
+ Retention.
2993
+ - **Request Routing**:
2994
+ API Gateway, Reverse Proxy, Path Routing, Rewriting.
2995
+ - **Load Balancing**:
2996
+ Distribution, Health Checks, Sticky Sessions, Failover.
2997
+ - **Transport Security**:
2998
+ TLS Termination, Certificates, Mutual TLS, Firewalling.
2999
+ - **Content Caching**:
3000
+ Response Caching, Content Delivery, Compression.
3001
+ - **Traffic Control**:
3002
+ Rate Limiting, Throttling, Circuit Breaking, Retry.
3003
+ - **Service Discovery**:
3004
+ Registry, Naming, Configuration Distribution.
3005
+ - **Identity Federation**:
3006
+ OAuth, OpenID Connect, SAML, Token Exchange.
3007
+
3008
+ The *Database Aspects* which usually have to be covered (at
3009
+ least for solutions with a data store of their own):
3010
+
3011
+ - **Storage Engine**:
3012
+ Row Store, Column Store, Document Store, Key-Value Store,
3013
+ Graph Store, Time Series, Binary Assets.
3014
+ - **Transaction Management**:
3015
+ ACID, Isolation Levels, Locking, Multi-Version Concurrency.
3016
+ - **Query Language**:
3017
+ SQL, Query DSL, Stored Procedures, Views.
3018
+ - **Indexing**:
3019
+ B-Tree, Hash, Full-Text Search, Geospatial, Vector.
3020
+ - **Replication**:
3021
+ Primary/Replica, Multi-Primary, Failover, Sharding.
3022
+ - **Database Security**:
3023
+ Encryption at Rest, Access Control, Auditing.
3024
+
3025
+ value: tags(Structure,Build,Dependency,Codeline,Standardization,Testing,Tooling,
3026
+ Installation,Configuration,Migration,Monitoring,Logging,Alerting,Backup,
3027
+ Recovery,Upgrade,Capacity,Administration,Incident,Support,
3028
+ "Interface Theme","Interface Widgets","Interface Layouting","Interface Effects",
3029
+ "Interface Interactions","Interface States","Interface Mask",
3030
+ "Interface Internationalization","Data Conversion","Data Binding",
3031
+ "Presentation Model","Dialog Navigation","Dialog Automation",
3032
+ "Dialog Communication","Dialog Life-Cycle","Dialog Structure",
3033
+ "State Persistence","Business Model","Use-Case Authorization",
3034
+ "Client Networking","Environment Detection",
3035
+ "Argument Parsing","Configuration Parsing","Process Daemonizing",
3036
+ "Process Management","Component Management","Component Communication",
3037
+ "Server Networking","Peer Information","Session Handling",
3038
+ "User Authentication","Request Validation","Request Processing",
3039
+ "Role Authorization","Task Scheduling","Execution Tracing",
3040
+ "Database Access","Database Connectivity","Database Schema",
3041
+ "Database Bootstrapping",
3042
+ "Message Brokering","Request Routing","Load Balancing","Transport Security",
3043
+ "Content Caching","Traffic Control","Service Discovery","Identity Federation",
3044
+ "Storage Engine","Transaction Management","Query Language","Indexing",
3045
+ "Replication","Database Security")
3046
+ optional: true
3047
+ - name: USED-BY
3048
+ desc: >
3049
+ Comma-separated references to the FUNCTIONALITY-VIEW objects using
3050
+ the product, the path along which a Deployment View node reaches
3051
+ the products running on it and along which swapping the product is
3052
+ impact-analyzed; omitted for a component not tied to particular
3053
+ functional components (e.g. a language or a build tool used by
3054
+ all).
3055
+ value: list([[ARCH:FV.COMPONENT:*]])
3056
+ optional: true
2845
3057
 
2846
3058
  - kind: ARCH
2847
- name: Development View
2848
- id: DV
2849
- file: 27-ARCH-DV-Development-View.md
3059
+ name: Development Aspects
3060
+ id: DA
3061
+ file: 25-ARCH-DA-Development-Aspects.md
2850
3062
  desc: >
2851
3063
  The architecture supporting the software development process, defining the module
2852
- organization, build approach, and codeline conventions.
3064
+ organization, build approach, and codeline conventions. The artifact is absent when the
3065
+ development conventions are governed outside the specification (e.g. by repository-level
3066
+ contributor instructions).
3067
+ optional: true
2853
3068
  refs: >
2854
3069
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Development Viewpoint (2011),
2855
3070
  https://www.viewpoints-and-perspectives.info/home/viewpoints/development/
@@ -2859,7 +3074,9 @@
2859
3074
  https://www.informit.com/store/documenting-software-architectures-views-and-beyond-9780321552686
2860
3075
  diagram:
2861
3076
  type: grid
2862
- nodes: "[[ARCH:DV.ASPECT:*]]"
3077
+ nodes: "[[ARCH:DA.ASPECT:*]]"
3078
+ properties:
3079
+ - CATEGORY
2863
3080
  childs:
2864
3081
  - kind: ASPECT
2865
3082
  desc: >
@@ -2867,23 +3084,125 @@
2867
3084
  Layering`, `Build Pipeline`, `Branching Model`) and described in a concise (1-3
2868
3085
  sentence) paragraph by the development convention or structure and the rule
2869
3086
  developers must follow, plus a 1-sentence rationale ("why").
3087
+
3088
+ An aspect states a standing developer-facing rule about the source structure and
3089
+ process: it names no concrete products (a Technology Stack `Build-Time` component
3090
+ states the product choice), does not restate the runtime structure (a Functionality
3091
+ View `Module` or `Subsystem` groups the logic), does not cover production
3092
+ procedures (an Operations View concern does), and the trade-off that produced a
3093
+ rule is a Design Decisions decision referencing the aspect through `AFFECTS`.
2870
3094
  props:
2871
3095
  - name: CATEGORY
2872
3096
  desc: >
2873
- The development concern the aspect governs: `Structure` (module/package
2874
- organization), `Build` (compilation and packaging), `Dependency` (dependency
2875
- management and layering rules), `Codeline` (branching, merging, versioning),
2876
- `Standardization` (coding standards and conventions), or `Tooling`
2877
- (development tools and automation).
2878
- value: enum(Structure,Build,Dependency,Codeline,Standardization,Tooling)
3097
+ The development concern the aspect governs: `Structure` (the physical
3098
+ source module/package layout), `Build` (compilation and packaging),
3099
+ `Dependency` (the allowed dependency edges between the structures),
3100
+ `Codeline` (branching, merging, versioning), `Standardization` (coding
3101
+ standards and conventions), `Testing` (test conventions, layout, and
3102
+ coverage rules), or `Tooling` (development tools and automation).
3103
+ value: enum(Structure,Build,Dependency,Codeline,Standardization,Testing,Tooling)
3104
+
3105
+ - kind: ARCH
3106
+ name: Concurrency View
3107
+ id: CO
3108
+ file: 26-ARCH-CO-Concurrency-View.md
3109
+ desc: >
3110
+ The concurrency structure of the solution, mapping functional components to processes and
3111
+ threads, and defining how they coordinate and communicate. The artifact is absent when the
3112
+ solution runs as a single sequential unit of execution and has no concurrency structure
3113
+ worth describing.
3114
+ optional: true
3115
+ refs: >
3116
+ - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Concurrency Viewpoint (2011),
3117
+ https://www.viewpoints-and-perspectives.info/home/viewpoints/concurrency/
3118
+ - Kruchten: Architectural Blueprints -- The "4+1" View Model of Software Architecture (1995),
3119
+ https://ieeexplore.ieee.org/document/469759
3120
+ - Schmidt et al.: Pattern-Oriented Software Architecture, Volume 2: Patterns for Concurrent and Networked Objects (2000),
3121
+ https://www.wiley.com/en-us/Pattern+Oriented+Software+Architecture,+Volume+2,+Patterns+for+Concurrent+and+Networked+Objects-p-9781118725177
3122
+ diagram:
3123
+ type: graph
3124
+ nodes: "[[ARCH:CO.UNIT:*]]"
3125
+ labeled: true
3126
+ properties:
3127
+ - KIND
3128
+ childs:
3129
+ - kind: UNIT
3130
+ desc: >
3131
+ A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker
3132
+ Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise
3133
+ (1-3 sentence) paragraph by how it executes and how it avoids or manages contention,
3134
+ races, and deadlocks (including its start order and failure/restart behavior where
3135
+ non-obvious), plus a 1-sentence rationale ("why") for the chosen concurrency
3136
+ structure.
3137
+
3138
+ A unit executes work at runtime: a queue or channel between units is not a unit
3139
+ but the coordination mechanism stated in `COORDINATION`, its contract an Interface
3140
+ Model interface (e.g. of kind `MQTT` or `WebSocket`), and the platform element
3141
+ hosting a managed broker a Deployment View `Managed` node -- only the executing
3142
+ structure itself belongs to the Concurrency View.
3143
+ diagram:
3144
+ type: hub
3145
+ center: self
3146
+ nodes: "[[ARCH:CO.UNIT:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:DV.NODE:*]]"
3147
+ labeled: true
3148
+ qualified: true
3149
+ properties:
3150
+ - KIND
3151
+ config:
3152
+ size-node-width-max: 440
3153
+ size-node-height-scale: 1.75
3154
+ props:
3155
+ - name: KIND
3156
+ desc: |
3157
+ The kind of the concurrency unit, one of:
3158
+
3159
+ - `Process`: An independent OS process with its own address space.
3160
+ - `Thread`: A thread of execution within a process.
3161
+ - `Task`: A lightweight cooperative task (e.g. coroutine, fiber).
3162
+ - `Pool`: A managed group of interchangeable workers.
3163
+ - `EventLoop`: A single-threaded cooperative scheduler of tasks.
3164
+ value: enum(Process,Thread,Task,Pool,EventLoop)
3165
+ - name: PART-OF
3166
+ desc: >
3167
+ Reference to the CONCURRENCY-VIEW object this unit is contained in,
3168
+ expressing the containment the kinds imply: a `Thread`, `Task`, `Pool`, or
3169
+ `EventLoop` references the `Process` it executes within, and a `Task` the
3170
+ `EventLoop` or `Pool` scheduling it; omitted for a top-level unit.
3171
+ value: "[[ARCH:CO.UNIT:*]]"
3172
+ optional: true
3173
+ acyclic: true
3174
+ - name: HOSTS
3175
+ desc: >
3176
+ Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside
3177
+ this concurrency unit; omitted when no modeled component runs inside it.
3178
+ value: list([[ARCH:FV.COMPONENT:*]])
3179
+ optional: true
3180
+ - name: MULTIPLICITY
3181
+ desc: >
3182
+ How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n
3183
+ auto-scaled`).
3184
+ - name: COORDINATES-WITH
3185
+ desc: >
3186
+ Comma-separated references to the CONCURRENCY-VIEW objects this unit
3187
+ coordinates or communicates with at runtime, naming the peer unit only
3188
+ (e.g. a producer names the consumer it feeds through a shared queue),
3189
+ while the mechanism is stated by `COORDINATION`.
3190
+ value: list([[ARCH:CO.UNIT:*]])
3191
+ optional: true
3192
+ - name: COORDINATION
3193
+ desc: >
3194
+ The mechanism by which the unit coordinates or communicates with other
3195
+ units, usually those referenced in `COORDINATES-WITH` (e.g. `shared
3196
+ queue`, `mutex`, `message passing`, `optimistic locking`).
2879
3197
 
2880
3198
  - kind: ARCH
2881
3199
  name: Deployment View
2882
- id: DP
2883
- file: 28-ARCH-DP-Deployment-View.md
3200
+ id: DV
3201
+ file: 27-ARCH-DV-Deployment-View.md
2884
3202
  desc: >
2885
- The environment into which the solution is deployed, mapping software elements to the
2886
- runtime platform, hardware, and network topology.
3203
+ The environment into which the solution is deployed, partitioning it into tiers and mapping
3204
+ software elements to the runtime platform, hardware, and network topology.
3205
+ optional: true
2887
3206
  refs: >
2888
3207
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Deployment Viewpoint (2011),
2889
3208
  https://www.viewpoints-and-perspectives.info/home/viewpoints/deployment/
@@ -2892,62 +3211,245 @@
2892
3211
  - Brown: The C4 Model: Deployment Diagram (2018),
2893
3212
  https://c4model.com/diagrams/deployment
2894
3213
  diagram:
2895
- type: grid
2896
- nodes: "[[ARCH:DP.NODE:*]]"
3214
+ type: graph
3215
+ nodes: "[[ARCH:DV.NODE:*]]"
3216
+ labeled: true
2897
3217
  properties:
3218
+ - TIER
3219
+ - AREA
2898
3220
  - KIND
2899
3221
  - PLATFORM
3222
+ config:
3223
+ size-node-width-max: 350
2900
3224
  childs:
3225
+ - kind: TIER
3226
+ desc: >
3227
+ A single deployment tier, named with a short (1-3 word) summary (e.g. `Client`,
3228
+ `Server`, `Database`, `Data Center`) and described in a concise (1-3 sentence)
3229
+ paragraph by the code or data it hosts and its spatial and network separation from
3230
+ the other tiers, plus a 1-sentence rationale ("why") for the partitioning.
3231
+
3232
+ A tier is a logically and spatially distinct, network-connected, technology-induced
3233
+ partition of the solution, the *horizontal* split when drawn (an `AREA` is the
3234
+ *vertical*, domain-induced one): every node belongs to exactly one tier via its
3235
+ `TIER`, a location-level tier (e.g. a data center) groups the tiers referencing it
3236
+ via `PART-OF`, and a single deployment unit within a tier is a `NODE` -- only the
3237
+ partition itself belongs here.
3238
+ format:
3239
+ type: concise
3240
+ diagram:
3241
+ type: hub
3242
+ center: self
3243
+ nodes: "[[ARCH:DV.TIER:*]], [[ARCH:DV.NODE:*]]"
3244
+ labeled: true
3245
+ qualified: true
3246
+ properties:
3247
+ - LOCATION
3248
+ - KIND
3249
+ config:
3250
+ size-node-width-max: 440
3251
+ size-node-height-scale: 1.75
3252
+ props:
3253
+ - name: PART-OF
3254
+ desc: >
3255
+ Reference to the DEPLOYMENT-VIEW tier this tier is contained in (e.g. the
3256
+ `Server` and `Database` tiers reference the `Data Center` tier hosting
3257
+ them); omitted for a top-level tier.
3258
+ value: "[[ARCH:DV.TIER:*]]"
3259
+ optional: true
3260
+ acyclic: true
3261
+ - name: LOCATION
3262
+ desc: >
3263
+ Where the tier physically runs (e.g. `Hetzner data center Nürnberg, dev/QA/prod
3264
+ environments`, `attendee and operator devices`, `Cloudflare edge`); omitted
3265
+ when inherited from the `PART-OF` tier.
3266
+ optional: true
3267
+ - name: STACK
3268
+ desc: >
3269
+ Reference to the TECHNOLOGY-STACK tier whose products run in this tier;
3270
+ omitted when the Technology Stack is absent, has no matching tier, or the
3271
+ tier (e.g. a data center) groups other tiers only.
3272
+ value: "[[ARCH:TS.TIER:*]]"
3273
+ optional: true
3274
+ - kind: AREA
3275
+ desc: >
3276
+ A single deployment area, named with a short (1-3 word) summary (e.g. `Ordering`,
3277
+ `Billing`, `Identity`) and described in a concise (1-3 sentence) paragraph by the
3278
+ domain it covers and its separation from the other areas, plus a 1-sentence rationale
3279
+ ("why") for the partitioning.
3280
+
3281
+ An area is a logically distinct, domain-induced partition of the solution deployed
3282
+ as physical units of its own, the *vertical* split when drawn (a `TIER` is the
3283
+ *horizontal*, technology-induced one): a node dedicated to the area references it via
3284
+ its `AREA`, a node shared by several areas references none, and a domain grouping
3285
+ without deployment units of its own is a Functionality View `Subsystem` instead. The
3286
+ kind is absent when the solution is not split vertically.
3287
+ optional: true
3288
+ format:
3289
+ type: concise
3290
+ diagram:
3291
+ type: hub
3292
+ center: self
3293
+ nodes: "[[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]]"
3294
+ labeled: true
3295
+ qualified: true
3296
+ properties:
3297
+ - KIND
3298
+ config:
3299
+ size-node-width-max: 440
3300
+ size-node-height-scale: 1.75
2901
3301
  - kind: NODE
2902
3302
  desc: >
2903
- A single deployment node, named with a short (2-5 word) summary (e.g. `Web Tier`,
3303
+ A single deployment node, named with a short (2-5 word) summary (e.g. `Web Servers`,
2904
3304
  `Database Cluster`, `Edge CDN`) and described in a concise (1-3 sentence) paragraph
2905
3305
  by the node, its sizing, and its place in the deployment topology, plus a 1-sentence
2906
3306
  rationale ("why") for the node's placement and platform choice.
3307
+
3308
+ A node is a platform element the solution deploys onto and operates itself: a
3309
+ managed third-party service the solution merely consumes is a Context View
3310
+ `Service` entity, the software products running on the node are Technology Stack
3311
+ components (referencing the hosted components through `USED-BY`), and the procedures
3312
+ operating the node are Operations View concerns -- only the runtime environment
3313
+ itself belongs to the Deployment View, with the tier and area the node belongs to
3314
+ and the network segments it is attached to as its `TIER`, `AREA`, and `NETWORK`
3315
+ siblings.
2907
3316
  diagram:
2908
3317
  type: hub
2909
3318
  center: self
2910
- nodes: "[[ARCH:DP.NODE:*]], [[ARCH:FV.COMPONENT:*]]"
3319
+ nodes: "[[ARCH:DV.TIER:*]], [[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]],
3320
+ [[ARCH:DV.NETWORK:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]]"
3321
+ labeled: true
2911
3322
  qualified: true
2912
3323
  properties:
3324
+ - LOCATION
2913
3325
  - KIND
2914
3326
  - PLATFORM
3327
+ - SCOPE
2915
3328
  config:
2916
- size-node-width-max: 440
3329
+ size-node-width-max: 440
3330
+ size-node-height-scale: 1.75
2917
3331
  props:
2918
3332
  - name: KIND
2919
3333
  desc: |
2920
3334
  The kind of the deployment node, one of:
2921
-
2922
3335
  - `Server`: A physical or virtual machine.
2923
3336
  - `Container`: A containerized runtime (e.g. Docker, OCI).
2924
- - `Cluster`: A managed group of nodes (e.g. Kubernetes cluster).
3337
+ - `Cluster`: A group of nodes managed as one (e.g. Kubernetes cluster),
3338
+ containing the nodes referencing it via `PART-OF`.
2925
3339
  - `Function`: A serverless / function-as-a-service runtime.
2926
3340
  - `Device`: An edge or client device.
2927
3341
  - `Managed`: A managed cloud service (e.g. managed database, queue).
2928
3342
  value: enum(Server,Container,Cluster,Function,Device,Managed)
3343
+ - name: TIER
3344
+ desc: >
3345
+ Reference to the DEPLOYMENT-VIEW tier the node belongs to, exactly one, as a
3346
+ single deployment unit never spans tiers.
3347
+ value: "[[ARCH:DV.TIER:*]]"
3348
+ - name: AREA
3349
+ desc: >
3350
+ Reference to the DEPLOYMENT-VIEW area the node is dedicated to, at most one,
3351
+ as a single deployment unit never spans areas; omitted for a node shared by
3352
+ several areas or when the solution is not split vertically.
3353
+ value: "[[ARCH:DV.AREA:*]]"
3354
+ optional: true
2929
3355
  - name: PLATFORM
2930
3356
  desc: >
2931
- The runtime platform of the node (e.g. `Linux x86-64`, `Kubernetes 1.30`,
2932
- `AWS Lambda (Node.js)`).
3357
+ The execution platform of the node, i.e. its operating system, runtime, or
3358
+ cloud service (e.g. `Linux x86-64`, `Kubernetes 1.30`, `AWS Lambda
3359
+ (Node.js)`), not the software products running on it, which are Technology
3360
+ Stack components.
3361
+ - name: PART-OF
3362
+ desc: >
3363
+ Reference to the DEPLOYMENT-VIEW object this node is contained in,
3364
+ expressing the nesting the kinds imply: a `Container` references the
3365
+ `Server` or `Cluster` running it, and a `Server` the `Cluster` it belongs
3366
+ to; omitted for a top-level node.
3367
+ value: "[[ARCH:DV.NODE:*]]"
3368
+ optional: true
3369
+ acyclic: true
2933
3370
  - name: HOSTS
2934
3371
  desc: >
2935
- Comma-separated references to the FUNCTIONALITY-VIEW objects deployed onto
2936
- this node.
2937
- value: list([[ARCH:FV.COMPONENT:*]])
3372
+ Comma-separated references to the CONCURRENCY-VIEW or FUNCTIONALITY-VIEW
3373
+ objects deployed onto this node: the concurrency units executing on the
3374
+ node (which themselves state the components they host), and the functional
3375
+ components not mapped by any concurrency unit directly. A containing node
3376
+ does not repeat what its `PART-OF` nodes host.
3377
+ value: list([[ARCH:CO.UNIT:*]], [[ARCH:FV.COMPONENT:*]])
3378
+ optional: true
3379
+ - name: INSTANCES
3380
+ desc: >
3381
+ How many instances of the node run (e.g. `1`, `3 per environment`, `0..n
3382
+ auto-scaled`).
2938
3383
  optional: true
2939
- - name: NETWORK
3384
+ - name: CONNECTS-TO
2940
3385
  desc: >
2941
- The network placement and connectivity of the node (e.g. `public subnet, TLS
2942
- 443`, `private VLAN`).
3386
+ Comma-separated references to the DEPLOYMENT-VIEW objects this node opens
3387
+ network connections to at runtime, naming the target node only, while the
3388
+ carried protocols are stated by the `PROTOCOLS` of the shared `NETWORK`.
3389
+ value: list([[ARCH:DV.NODE:*]])
3390
+ optional: true
3391
+ - name: NETWORKS
3392
+ desc: >
3393
+ Comma-separated references to the DEPLOYMENT-VIEW network segments the node
3394
+ is attached to (e.g. a public ingress and a private backend network); omitted
3395
+ when the topology models no network segments.
3396
+ value: list([[ARCH:DV.NETWORK:*]])
3397
+ optional: true
3398
+ - kind: NETWORK
3399
+ desc: >
3400
+ A single network segment the deployment nodes are attached to, named with a short
3401
+ (2-5 word) summary (e.g. `Public Internet`, `Backend VLAN`, `Database Subnet`) and
3402
+ described in a concise (1-3 sentence) paragraph by its reach, its isolation from the
3403
+ other segments, and the traffic it carries, plus a 1-sentence rationale ("why") for
3404
+ the segmentation.
3405
+
3406
+ A segment is the medium the nodes communicate over: the attached nodes reference it
3407
+ via `NETWORKS`, the directed links between them are their `CONNECTS-TO` references,
3408
+ and the contract of the carried traffic is an Interface Model interface -- only the
3409
+ network itself belongs here. The kind is absent when the topology has no
3410
+ segmentation worth describing.
3411
+ optional: true
3412
+ format:
3413
+ type: concise
3414
+ diagram:
3415
+ type: hub
3416
+ center: self
3417
+ nodes: "[[ARCH:DV.NETWORK:*]], [[ARCH:DV.NODE:*]]"
3418
+ labeled: true
3419
+ qualified: true
3420
+ properties:
3421
+ - KIND
3422
+ - SCOPE
3423
+ config:
3424
+ size-node-width-max: 440
3425
+ size-node-height-scale: 1.75
3426
+ props:
3427
+ - name: SCOPE
3428
+ desc: |
3429
+ The reach of the segment, one of:
3430
+ - `Public`: Reachable from the Internet.
3431
+ - `Private`: Reachable from the solution's own nodes only.
3432
+ - `Isolated`: Reachable from selected nodes only (e.g. a database subnet).
3433
+ value: enum(Public,Private,Isolated)
3434
+ - name: PROTOCOLS
3435
+ desc: >
3436
+ The protocols and ports carried by the segment (e.g. `HTTPS 443, WSS 443`,
3437
+ `HTTP, WS, TCP 5432`).
3438
+ - name: ADDRESSING
3439
+ desc: >
3440
+ The address range or naming of the segment (e.g. `10.0.0.0/8`, `public IPv4
3441
+ and IPv6`, `*.example.com`).
3442
+ optional: true
2943
3443
 
2944
3444
  - kind: ARCH
2945
3445
  name: Operations View
2946
3446
  id: OV
2947
- file: 29-ARCH-OV-Operations-View.md
3447
+ file: 28-ARCH-OV-Operations-View.md
2948
3448
  desc: >
2949
- The way the solution is operated, administered, and supported in production, defining
2950
- installation, monitoring, and management concerns.
3449
+ The way the solution is operated, administered, and supported in production, defining the
3450
+ standing procedures by which the operating organization installs, configures, migrates,
3451
+ observes, protects, upgrades, scales, and supports the running solution.
3452
+ optional: true
2951
3453
  refs: >
2952
3454
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Operational Viewpoint (2011),
2953
3455
  https://www.viewpoints-and-perspectives.info/home/viewpoints/operational/
@@ -2965,28 +3467,102 @@
2965
3467
  desc: >
2966
3468
  A single operational concern, named with a short (2-5 word) summary (e.g. `Rolling
2967
3469
  Deployment`, `Metrics Collection`, `Backup and Restore`) and described in a concise
2968
- (1-3 sentence) paragraph by how it is handled in production and which procedures or
2969
- tools support it, plus a 1-sentence rationale ("why") for the operational approach.
3470
+ (1-3 sentence) paragraph by the procedure through which it is handled in production
3471
+ and the steps and tools supporting it, plus a 1-sentence rationale ("why") for the
3472
+ operational approach.
3473
+
3474
+ A concern states a standing production procedure the operating organization
3475
+ performs on the running solution: a capability the solution offers its users (even
3476
+ an administrating one) is a Functional Requirement or Use Case, an automatic
3477
+ behavior of the solution is a Domain Rule, the design tactic making the solution
3478
+ operable (e.g. replication, statelessness) is a Quality Perspectives tactic
3479
+ referencing the concern through `OPERATED-BY`, the deployment shape acted upon
3480
+ (instances, environments) is the Deployment View, the pipeline producing the
3481
+ deployable artifact is a `Build` aspect of the Development Aspects, and the products
3482
+ used are Technology Stack `Operate-Time` components referenced through `TOOLS` --
3483
+ only the procedure itself, its trigger, and its responsible operator belong here.
3484
+ diagram:
3485
+ type: hub
3486
+ center: self
3487
+ nodes: "[[ARCH:OV.CONCERN:*]], [[REQS:NR.REQUIREMENT:*]], [[REQS:UP.PERSONA:*]],
3488
+ [[ARCH:QP.TACTIC:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]],
3489
+ [[ARCH:DV.NODE:*]], [[DATA:DM.ENTITY:*]], [[ARCH:TS.TIER:*.COMPONENT:*]]"
3490
+ labeled: true
3491
+ qualified: true
3492
+ properties:
3493
+ - CATEGORY
3494
+ config:
3495
+ size-node-width-max: 440
3496
+ size-node-height-scale: 1.75
2970
3497
  props:
2971
3498
  - name: CATEGORY
3499
+ desc: |
3500
+ The category of the concern, one of:
3501
+ - `Installation`: Provisioning the environments and installing the
3502
+ solution into them.
3503
+ - `Configuration`: Managing the configuration of the installed solution.
3504
+ - `Migration`: Moving data or functionality between versions or
3505
+ environments.
3506
+ - `Monitoring`: Observing the health and performance of the running
3507
+ solution.
3508
+ - `Logging`: Collecting, retaining, and inspecting the logs.
3509
+ - `Alerting`: Notifying the operators of conditions requiring
3510
+ attention.
3511
+ - `Backup`: Preserving the data and state of the solution.
3512
+ - `Recovery`: Restoring the solution after a failure or data loss.
3513
+ - `Upgrade`: Rolling out new versions of the solution.
3514
+ - `Capacity`: Scaling the solution and planning its capacity.
3515
+ - `Administration`: Routine housekeeping (e.g. user administration, data
3516
+ retention, certificate rotation).
3517
+ - `Incident`: Troubleshooting and responding to incidents.
3518
+ - `Support`: Handling the requests of the users through the support
3519
+ tiers and their escalation.
3520
+ value: enum(Installation,Configuration,Migration,Monitoring,Logging,Alerting,Backup,Recovery,Upgrade,Capacity,Administration,Incident,Support)
3521
+ - name: TRIGGER
3522
+ desc: >
3523
+ When the procedure is performed (e.g. `nightly`, `on release`, `on alert`,
3524
+ `before each event`, `on demand`), separating the routine (scheduled)
3525
+ concerns from the reactive (event-driven) ones.
3526
+ - name: OPERATOR
2972
3527
  desc: >
2973
- The category of the concern: `Installation`, `Configuration`,
2974
- `Provisioning`, `Monitoring`, `Logging`, `Alerting`, `Backup`, `Recovery`,
2975
- `Upgrade`, or `Support`.
2976
- value: enum(Installation,Configuration,Provisioning,Monitoring,Logging,Alerting,Backup,Recovery,Upgrade,Support)
3528
+ Comma-separated references to the User Personas objects performing the
3529
+ procedure, usually a `Stakeholder` persona like the operations team (a
3530
+ procedure performed by a `User` persona through the solution is a Use Case
3531
+ instead); omitted when no persona of the operating organization is modeled.
3532
+ value: list([[REQS:UP.PERSONA:*]])
3533
+ optional: true
3534
+ - name: ADDRESSES
3535
+ desc: >
3536
+ Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS objects the
3537
+ procedure fulfills (e.g. a recovery objective, a retention obligation);
3538
+ omitted when the concern fulfills no stated requirement.
3539
+ value: list([[REQS:NR.*]])
3540
+ optional: true
2977
3541
  - name: ELEMENTS
2978
3542
  desc: >
2979
- Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
2980
- objects the concern applies to.
2981
- value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
3543
+ Comma-separated references to the FUNCTIONALITY-VIEW, CONCURRENCY-VIEW,
3544
+ DEPLOYMENT-VIEW, or DATA-MODEL objects the procedure acts upon (e.g. the
3545
+ nodes scaled, the units restarted, the entities backed up or migrated).
3546
+ value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]], [[ARCH:DV.TIER:*]],
3547
+ [[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]], [[ARCH:DV.NETWORK:*]],
3548
+ [[DATA:DM.ENTITY:*]])
3549
+ optional: true
3550
+ - name: TOOLS
3551
+ desc: >
3552
+ Comma-separated references to the TECHNOLOGY-STACK components (usually of
3553
+ `PHASE` `Operate-Time`) supporting the procedure; omitted when the procedure
3554
+ uses no modeled product.
3555
+ value: list([[ARCH:TS.TIER:*.COMPONENT:*]])
2982
3556
  optional: true
2983
3557
 
2984
3558
  - kind: ARCH
2985
3559
  name: Quality Perspectives
2986
3560
  id: QP
2987
- file: 30-ARCH-QP-Quality-Perspectives.md
3561
+ file: 29-ARCH-QP-Quality-Perspectives.md
2988
3562
  desc: >
2989
- How the Non-Functional Requirements (NR) are addressed.
3563
+ How the Non-Functional Requirements (NR) are addressed by the architecture, through the
3564
+ tactics built into the solution across the views.
3565
+ optional: true
2990
3566
  refs: >
2991
3567
  - Rozanski/Woods: Software Systems Architecture, 2nd ed.: The Perspectives (2011),
2992
3568
  https://www.viewpoints-and-perspectives.info/home/perspectives/
@@ -2996,21 +3572,41 @@
2996
3572
  https://www.iso.org/standard/78176.html
2997
3573
  diagram:
2998
3574
  type: grid
2999
- nodes: "[[ARCH:QP.PERSPECTIVE:*]]"
3575
+ nodes: "[[ARCH:QP.TACTIC:*]]"
3000
3576
  properties:
3001
3577
  - QUALITY
3002
3578
  childs:
3003
- - kind: PERSPECTIVE
3579
+ - kind: TACTIC
3004
3580
  desc: >
3005
- A single quality perspective, named with a short (2-5 word) summary (e.g.
3006
- `Horizontal Scaling`, `Defense in Depth`, `Graceful Degradation`) and described in a
3007
- concise (1-3 sentence) paragraph by how the architecture satisfies the quality
3008
- attribute across the affected elements, plus a 1-sentence rationale ("why") for the
3009
- chosen tactic over alternatives.
3581
+ A single quality tactic, one architectural tactic applied to one quality attribute
3582
+ (the perspective in the sense of Rozanski/Woods, i.e. the cross-cutting quality
3583
+ concern applied to the elements of all views, identified by `QUALITY`), named with
3584
+ a short (2-5 word) summary (e.g. `Horizontal Scaling`, `Defense in Depth`,
3585
+ `Graceful Degradation`) and described in a concise (1-3 sentence) paragraph by how
3586
+ the tactic satisfies the quality attribute across the affected elements, plus a
3587
+ 1-sentence rationale ("why") for the tactic satisfying the addressed requirements
3588
+ (not for choosing it over alternatives, which is the rationale of a Design
3589
+ Decisions decision).
3590
+
3591
+ A tactic states a design mechanism built into the solution: the threshold the
3592
+ mechanism has to meet is the `METRIC` of the addressed Non-Functional Requirement
3593
+ and is not restated, the production procedure performed against the mechanism
3594
+ (e.g. scaling out, restoring) is an Operations View concern referenced through
3595
+ `OPERATED-BY`, the trade-off that chose the mechanism over alternatives is a
3596
+ Design Decisions decision referencing the tactic through `DECIDES`, the product
3597
+ realizing the mechanism is a Technology Stack component referenced through
3598
+ `TOOLS`, the developer-facing rule about the source structure is an aspect of the
3599
+ Development Aspects, and a mechanism driven solely by a `Constraint` requirement
3600
+ (e.g. a hosting or budget mandate) protects no quality and is a Design Decisions
3601
+ decision alone -- only the mechanism, the quality it achieves, and the elements it
3602
+ shapes belong here.
3010
3603
  diagram:
3011
3604
  type: hub
3012
3605
  center: self
3013
- nodes: "[[ARCH:QP.PERSPECTIVE:*]], [[REQS:NR.REQUIREMENT:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]]"
3606
+ nodes: "[[ARCH:QP.TACTIC:*]], [[REQS:NR.REQUIREMENT:*]], [[ARCH:FV.COMPONENT:*]],
3607
+ [[ARCH:CO.UNIT:*]], [[ARCH:DA.ASPECT:*]], [[ARCH:DV.NODE:*]], [[DATA:DM.ENTITY:*]],
3608
+ [[ARCH:OV.CONCERN:*]], [[ARCH:DD.DECISION:*]], [[ARCH:TS.TIER:*.COMPONENT:*]]"
3609
+ labeled: true
3014
3610
  qualified: true
3015
3611
  properties:
3016
3612
  - QUALITY
@@ -3019,43 +3615,75 @@
3019
3615
  props:
3020
3616
  - name: QUALITY
3021
3617
  desc: >
3022
- The quality attribute the perspective addresses, a solution-oriented
3618
+ The quality attribute the tactic addresses, a solution-oriented
3023
3619
  refinement of the NON-FUNCTIONAL-REQUIREMENTS categories which intentionally
3024
3620
  differs from them.
3025
3621
 
3026
3622
  The NR categories follow the ISO/IEC 25010:2023 top-level characteristics
3027
- (and include `Safety` and `Flexibility`) plus the non-quality categories
3028
- `Compliance` and `Constraint`, whereas the perspective qualities decompose
3029
- some of the characteristics into the finer-grained, architecturally
3030
- actionable attributes `Scalability`, `Availability`, `Privacy`,
3031
- `Accessibility`, and `Portability`, and address a `Constraint` through the
3032
- quality it protects. The quality therefore need not match the category of
3033
- the requirements it addresses.
3034
- value: enum(Performance,Scalability,Reliability,Availability,Security,Privacy,Usability,Accessibility,Maintainability,Portability,Compatibility,Compliance)
3623
+ plus the non-quality categories `Compliance` and `Constraint`, whereas the
3624
+ tactic qualities decompose some of the characteristics into the
3625
+ finer-grained, architecturally actionable attributes `Scalability`,
3626
+ `Availability`, `Privacy`, `Accessibility`, and `Portability` (with
3627
+ `Flexibility` fully absorbed by `Scalability` and `Portability`), and
3628
+ address a `Compliance` or `Constraint` requirement through the quality it
3629
+ protects (e.g. a data protection obligation through `Privacy`). The
3630
+ quality therefore need not match the category of the requirements it
3631
+ addresses.
3632
+ value: enum(Performance,Scalability,Reliability,Availability,Safety,Security,Privacy,Usability,Accessibility,Maintainability,Portability,Compatibility)
3035
3633
  - name: ADDRESSES
3036
3634
  desc: >
3037
3635
  Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS objects the
3038
- perspective addresses.
3636
+ tactic addresses.
3039
3637
  value: list([[REQS:NR.*]])
3040
- - name: TACTIC
3638
+ - name: MECHANISM
3639
+ desc: >
3640
+ The design mechanism through which the tactic is applied to achieve the
3641
+ quality (e.g. `stateless replication behind a load balancer`,
3642
+ `read-through cache`, `circuit breaker`).
3643
+ - name: TRADES-OFF
3041
3644
  desc: >
3042
- The architectural tactic or strategy applied to achieve the quality (e.g.
3043
- `stateless replication behind a load balancer`, `read-through cache`,
3044
- `circuit breaker`).
3645
+ Comma-separated quality attributes (from the same set as `QUALITY`) the
3646
+ tactic knowingly degrades in favor of the addressed one (e.g. a one-time
3647
+ token trades `Usability` for `Security`); omitted when the tactic has no
3648
+ notable cost on another quality.
3649
+ value: tags(Performance,Scalability,Reliability,Availability,Safety,Security,Privacy,Usability,Accessibility,Maintainability,Portability,Compatibility)
3650
+ optional: true
3045
3651
  - name: AFFECTS
3046
3652
  desc: >
3047
- Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
3048
- objects the tactic affects.
3049
- value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
3653
+ Comma-separated references to the FUNCTIONALITY-VIEW, CONCURRENCY-VIEW,
3654
+ DEVELOPMENT-ASPECTS, DEPLOYMENT-VIEW, DATA-MODEL, AUTHORIZATION-MODEL, or
3655
+ INTERFACE-MODEL objects the tactic shapes (e.g. the components replicated,
3656
+ the aspects governing modifiability, the entities anonymized, the roles
3657
+ and interfaces secured).
3658
+ value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]], [[ARCH:DA.ASPECT:*]],
3659
+ [[ARCH:DV.TIER:*]], [[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]], [[ARCH:DV.NETWORK:*]],
3660
+ [[DATA:DM.ENTITY:*]], [[DATA:AM.ROLE:*]], [[APIS:IM.INTERFACE:*]])
3661
+ optional: true
3662
+ - name: OPERATED-BY
3663
+ desc: >
3664
+ Comma-separated references to the OPERATIONS-VIEW objects whose procedure
3665
+ acts upon the design mechanism of the tactic (e.g. the scaling out of the
3666
+ replication, the restoring of the backup); omitted when no modeled procedure
3667
+ operates the tactic.
3668
+ value: list([[ARCH:OV.CONCERN:*]])
3669
+ optional: true
3670
+ - name: TOOLS
3671
+ desc: >
3672
+ Comma-separated references to the TECHNOLOGY-STACK components realizing the
3673
+ tactic (e.g. the load balancer, the message broker, the CDN); omitted when
3674
+ the tactic uses no modeled product.
3675
+ value: list([[ARCH:TS.TIER:*.COMPONENT:*]])
3050
3676
  optional: true
3051
-
3052
3677
  - kind: ARCH
3053
- name: Decision Record
3054
- id: DR
3055
- file: 31-ARCH-DR-Decision-Record.md
3678
+ name: Design Decisions
3679
+ id: DD
3680
+ file: 30-ARCH-DD-Design-Decisions.md
3056
3681
  desc: >
3057
- The major decisions related to the architecture, each recording the forces at play, the
3058
- chosen response, and the reasoning that justifies it.
3682
+ The major decisions related to the solution design, each recording the forces at play, the
3683
+ chosen response, and the reasoning that justifies it. The artifact is the last one of the
3684
+ architecture, as a decision references the requirements forcing it, the elements it
3685
+ shapes, and the tactics and products it chose, all of which precede it.
3686
+ optional: true
3059
3687
  refs: >
3060
3688
  - Nygard: Documenting Architecture Decisions (2011),
3061
3689
  https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
@@ -3065,7 +3693,7 @@
3065
3693
  https://adr.github.io/
3066
3694
  diagram:
3067
3695
  type: grid
3068
- nodes: "[[ARCH:DR.DECISION:*]]"
3696
+ nodes: "[[ARCH:DD.DECISION:*]]"
3069
3697
  properties:
3070
3698
  - STATUS
3071
3699
  config:
@@ -3075,53 +3703,48 @@
3075
3703
  - kind: DECISION
3076
3704
  desc: |
3077
3705
  A single architecture decision, named with a short summary of the decision, not
3078
- longer than 80 characters, and recorded as its context (`WHEN`), the decision
3079
- itself (`WHAT`), its rationale (`WHY`), and optional background (`NOTES`).
3706
+ longer than 80 characters, and recorded entirely in its properties, with no
3707
+ description paragraph of its own: the forces driving it (`DRIVEN-BY`), the options
3708
+ it was chosen over (`ALTERNATIVES`), its context (`WHEN`), the decision itself
3709
+ (`WHAT`), its rationale (`WHY`), and its optional consequences (`CONSEQUENCES`) and
3710
+ background (`NOTES`).
3080
3711
 
3081
3712
  A decision *MUST* qualify on all of the following three tenets:
3082
-
3083
3713
  - **Hard to Reverse**: the cost of changing it later is meaningful ("Oh my god,
3084
3714
  this would result in a dramatic refactoring!"). So, if a decision is easy to
3085
3715
  reverse, just skip it.
3086
-
3087
3716
  - **Surprising without Context**: a future architect will look at the code and
3088
3717
  wonder ("Why on earth did they do it this way?"). So, if a decision is not
3089
3718
  surprising, nobody will wonder why.
3090
-
3091
3719
  - **Result of a Real Trade-Off**: there were genuine alternatives and one was
3092
3720
  picked for specific reasons ("We deliberately chose this, because..."). So, if
3093
3721
  there was no real alternative, there's nothing to record beyond "we did the
3094
3722
  obvious thing."
3095
3723
 
3096
3724
  The following typically qualify as a decision:
3097
-
3098
3725
  - **Architectural shape.** "We're using a monorepo." "The write model is
3099
3726
  event-sourced, the read model is projected into PostgreSQL."
3100
-
3101
3727
  - **Integration patterns between contexts.** "Ordering and Billing communicate
3102
3728
  via domain events, not synchronous HTTP."
3103
-
3104
3729
  - **Technology choices that carry lock-in.** Database, message bus, auth
3105
3730
  provider, deployment target. Not every library - just the ones that would take
3106
3731
  a quarter to swap out.
3107
-
3108
3732
  - **Boundary and scope decisions.** "Customer data is owned by the Customer
3109
3733
  context; other contexts reference it by ID only." The explicit no's are as
3110
3734
  valuable as the yes's.
3111
-
3112
3735
  - **Deliberate deviations from the obvious path.** "We're using manual SQL
3113
3736
  instead of an ORM because X." Anything where a reasonable reader would assume
3114
3737
  the opposite. These stop the next engineer from "fixing" something that was
3115
3738
  deliberate.
3116
-
3117
- - **Constraints not visible in the code.** "We can't use AWS because of
3118
- compliance requirements." "Response times must be under 200ms because of the
3119
- partner API contract."
3120
-
3121
3739
  - **Rejected alternatives when the rejection is non-obvious.** If you considered
3122
3740
  GraphQL and picked REST for subtle reasons, record it - otherwise someone will
3123
3741
  suggest GraphQL again in six months.
3124
3742
 
3743
+ A constraint itself is not a decision: a compliance obligation, a hosting mandate,
3744
+ or a partner-imposed threshold is a Non-Functional Requirement (of category
3745
+ `Compliance`, `Constraint`, or the affected quality), and the decision is the
3746
+ response to it, referencing it through `DRIVEN-BY`.
3747
+
3125
3748
  `WHEN`, `WHAT`, and `WHY` are each just a single paragraph of concise and brief
3126
3749
  prose text, usually comprised of just 1 to 3 sentences. The value of a decision is
3127
3750
  in recording *that* a decision was made and *why* - not in filling out sections of
@@ -3138,7 +3761,15 @@
3138
3761
  diagram:
3139
3762
  type: hub
3140
3763
  center: self
3141
- nodes: "[[ARCH:DR.DECISION:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]]"
3764
+ nodes: "[[ARCH:DD.DECISION:*]], [[REQS:NR.REQUIREMENT:*]], [[REQS:SP.PREMISE:*]],
3765
+ [[DATA:DM.ENTITY:*]], [[DATA:SM.LIFECYCLE:*]], [[DATA:AM.ROLE:*]],
3766
+ [[APIS:IM.INTERFACE:*]], [[APIS:ID.TYPE:*]], [[APIS:IE.ENDPOINT:*]],
3767
+ [[UXUI:IC.PRINCIPLE:*]], [[UXUI:LC.CONVENTION:*]], [[UXUI:DP.PATTERN:*]],
3768
+ [[UXUI:DS.STORYBOARD:*]], [[UXUI:VD.ELEMENT:*]],
3769
+ [[ARCH:CV.ENTITY:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]],
3770
+ [[ARCH:DA.ASPECT:*]], [[ARCH:DV.TIER:*]], [[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]],
3771
+ [[ARCH:DV.NETWORK:*]], [[ARCH:QP.TACTIC:*]], [[ARCH:TS.TIER:*.COMPONENT:*]]"
3772
+ labeled: true
3142
3773
  qualified: true
3143
3774
  properties:
3144
3775
  - STATUS
@@ -3146,22 +3777,65 @@
3146
3777
  size-node-width-max: 440
3147
3778
  props:
3148
3779
  - name: STATUS
3780
+ desc: |
3781
+ The status of the decision, one of:
3782
+ - `Proposed`: Under consideration, not yet binding.
3783
+ - `Accepted`: Binding for the solution.
3784
+ - `Rejected`: Considered and deliberately turned down, recorded so
3785
+ that it is not proposed again unknowingly.
3786
+ - `Deprecated`: No longer binding, without a replacing decision.
3787
+ - `Superseded`: Replaced by the decision referenced in `SUPERSEDED-BY`.
3788
+ value: enum(Proposed,Accepted,Rejected,Deprecated,Superseded)
3789
+ - name: SUPERSEDED-BY
3149
3790
  desc: >
3150
- The status of the decision: `proposed`, `accepted`, `deprecated`, or
3151
- `superseded`.
3152
- value: enum(proposed,accepted,deprecated,superseded)
3153
- - name: AFFECTS
3154
- desc: >
3155
- Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
3156
- objects the decision affects.
3157
- value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
3791
+ Reference to the DESIGN-DECISIONS object that supersedes this decision,
3792
+ present if and only if `STATUS` is `Superseded` (which the schema cannot
3793
+ enforce itself).
3794
+ value: "[[ARCH:DD.DECISION:*]]"
3158
3795
  optional: true
3159
- - name: SUPERSEDED-BY
3796
+ acyclic: true
3797
+ - name: DRIVEN-BY
3160
3798
  desc: >
3161
- Reference to the DECISION-RECORD object that supersedes this decision.
3162
- Should be present if and only if `STATUS` is `superseded`.
3163
- value: "[[ARCH:DR.DECISION:*]]"
3799
+ Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS or
3800
+ SOLUTION-PREMISES objects forcing the decision (e.g. the compliance
3801
+ obligation, the budget constraint, the dependency taken as given), anchoring
3802
+ the forces `WHEN` describes in prose; omitted when no modeled requirement or
3803
+ premise drives the decision.
3804
+ value: list([[REQS:NR.*]], [[REQS:SP.PREMISE:*]])
3164
3805
  optional: true
3806
+ - name: AFFECTS
3807
+ desc: >
3808
+ Comma-separated references to the objects of the DATA, APIS, UXUI, or ARCH
3809
+ artifacts the decision shapes, i.e. the entities, lifecycles, and roles, the
3810
+ interfaces, datatypes, and endpoints, the interaction principles, language
3811
+ conventions, dialog patterns, storyboards, and visual elements, and the
3812
+ elements of the architecture views (e.g. the entity owned by a single
3813
+ context, the interface styled REST instead of GraphQL, the dialog pattern
3814
+ chosen over a native one, the components split, the external system
3815
+ integrated); omitted for a decision shaping no modeled element.
3816
+ value: list([[DATA:DM.ENTITY:*]], [[DATA:SM.LIFECYCLE:*]], [[DATA:AM.ROLE:*]],
3817
+ [[APIS:IM.INTERFACE:*]], [[APIS:ID.TYPE:*]], [[APIS:IE.ENDPOINT:*]],
3818
+ [[UXUI:IC.PRINCIPLE:*]], [[UXUI:LC.CONVENTION:*]], [[UXUI:DP.PATTERN:*]],
3819
+ [[UXUI:DS.STORYBOARD:*]], [[UXUI:VD.ELEMENT:*]],
3820
+ [[ARCH:CV.ENTITY:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]],
3821
+ [[ARCH:DA.ASPECT:*]], [[ARCH:DV.TIER:*]], [[ARCH:DV.AREA:*]], [[ARCH:DV.NODE:*]],
3822
+ [[ARCH:DV.NETWORK:*]])
3823
+ optional: true
3824
+ - name: DECIDES
3825
+ desc: >
3826
+ Comma-separated references to the QUALITY-PERSPECTIVES tactics or
3827
+ TECHNOLOGY-STACK components the decision chose over their alternatives,
3828
+ i.e. the mechanism or product which exists because of this decision; omitted
3829
+ when the decision chose no modeled tactic or product.
3830
+ value: list([[ARCH:QP.TACTIC:*]], [[ARCH:TS.TIER:*.COMPONENT:*]])
3831
+ optional: true
3832
+ - name: ALTERNATIVES
3833
+ desc: >
3834
+ Comma-separated names of the options considered but not chosen (e.g.
3835
+ `REST polling, bespoke WebSocket protocol`): the rationale `WHY` states *why*
3836
+ the decision won, this property states *against what*, and as a decision
3837
+ qualifies only as the result of a real trade-off, there is always at least
3838
+ one.
3165
3839
  - name: WHEN
3166
3840
  desc: |
3167
3841
  The **Context** of the decision: it captures the situation that forces the
@@ -3203,7 +3877,7 @@
3203
3877
  The **Rationale** of the decision: it is the reasoning that justifies the
3204
3878
  decision - the bridge that explains why this choice, given those forces. It
3205
3879
  answers "Of all the things we could have done, why was this the right
3206
- one?". Where the context states the forces and the decision states the
3880
+ one?" Where the context states the forces and the decision states the
3207
3881
  choice, the rationale is the logical connective tissue between them - it
3208
3882
  shows that the decision actually follows from the context. The following
3209
3883
  usually goes into it:
@@ -3216,6 +3890,19 @@
3216
3890
  on X, option C cost too much on Y"); and
3217
3891
  - assumptions and evidence (benchmarks, prior experience, constraints, or
3218
3892
  principles the reasoning rests on).
3893
+ - name: CONSEQUENCES
3894
+ desc: |
3895
+ The **Consequences** of the decision: what follows from it once made, in
3896
+ contrast to the trade-off reasoning of `WHY`, which precedes it. It is
3897
+ *OPTIONAL* and omitted when nothing non-obvious follows. The following
3898
+ usually goes into it:
3899
+
3900
+ - what becomes easier and what becomes harder (the negative consequences
3901
+ are the valuable ones, as they are the price knowingly paid);
3902
+ - the obligations the decision imposes on the elements it affects (e.g.
3903
+ a convention to follow, a migration to perform); and
3904
+ - the follow-up decisions it makes necessary.
3905
+ optional: true
3219
3906
  - name: NOTES
3220
3907
  desc: |
3221
3908
  The **Background** of the decision: it is *OPTIONAL* and can be omitted
@@ -3223,254 +3910,154 @@
3223
3910
  following usually goes into it:
3224
3911
 
3225
3912
  - information about the decision *process* (e.g. a weighted decision
3226
- matrix of considered alternatives);
3227
- - consequences of the decision (but only when non-obvious downstream
3228
- effects need to be called out); and
3913
+ matrix of considered alternatives); and
3229
3914
  - links to strongly related decisions.
3230
3915
  optional: true
3231
-
3232
- - kind: ARCH
3233
- name: Technology Stack
3234
- id: TS
3235
- file: 32-ARCH-TS-Technology-Stack.md
3916
+ - kind: TEST
3917
+ name: Test Cases
3918
+ id: TC
3919
+ file: 31-TEST-TC-Test-Cases.md
3236
3920
  desc: >
3237
- The concrete technology products the solution is built upon, organized by tier and lifecycle
3238
- phase, recording for each component its chosen product, its purpose, and the alternatives
3239
- that were considered but not chosen.
3921
+ The verifiable conditions and steps used to confirm that requirements, domain rules, use
3922
+ case scenarios, state transitions, and the mechanisms, procedures, and decisions of the
3923
+ architecture are correctly implemented, with mandatory defined inputs, mandatory expected
3924
+ outcomes, and optional pre- and post-conditions. The artifact is the last one, as a test
3925
+ case verifies objects of every preceding kind.
3926
+
3927
+ Test cases are not derived from use cases alone: a use case scenario describes an intent-level
3928
+ flow, while a test case fixes the concrete data and the observable assertions that decide pass
3929
+ or fail, and many test cases (e.g. of Non-Functional Requirements or of cross-session rules)
3930
+ have no use case counterpart at all.
3931
+ optional: true
3240
3932
  refs: >
3241
- - ThoughtWorks: Technology Radar (2010),
3242
- https://www.thoughtworks.com/radar
3243
- - Ford: Build Your Own Technology Radar (2013),
3244
- https://nealford.com/memeagora/2013/05/28/build_your_own_technology_radar.html
3245
- - Fowler: Patterns of Enterprise Application Architecture (2002),
3246
- https://martinfowler.com/books/eaa.html
3933
+ - ISO/IEC/IEEE 29119-3:2021: Software and systems engineering -- Software testing -- Part 3: Test documentation (2021),
3934
+ https://www.iso.org/standard/79429.html
3935
+ - ISO/IEC/IEEE 29119-4:2021: Software and systems engineering -- Software testing -- Part 4: Test techniques (2021),
3936
+ https://www.iso.org/standard/79430.html
3937
+ - ISTQB CTFL 4.0: Certified Tester Foundation Level Syllabus (2023),
3938
+ https://istqb.org/certifications/certified-tester-foundation-level-ctfl-v4-0/
3247
3939
  diagram:
3248
3940
  type: grid
3249
- nodes: "[[ARCH:TS.TIER:*]]"
3941
+ nodes: "[[TEST:TC.TEST-CASE:*]]"
3942
+ config:
3943
+ size-node-width-max: 440
3944
+ size-node-height-scale: 2
3945
+ grid-columns-max: 4
3250
3946
  childs:
3251
- - kind: TIER
3252
- name: (?:Client|Server|Middleware|Database)
3253
- desc: |
3254
- The architectural tier grouping the technology components belonging to it, one of:
3947
+ - kind: TEST-CASE
3948
+ desc: >
3949
+ A single verifiable test case, named with a short (3-8 word) summary and defined by
3950
+ its mandatory input and expected outcome plus its optional pre- and post-conditions.
3255
3951
 
3256
- - `Client`: Runs on the client side (e.g. browser, desktop, mobile).
3257
- - `Server`: Runs on the server side (e.g. backend, application, API).
3258
- - `Middleware`: Runs between client and server (e.g. message broker, gateway).
3259
- - `Database`: Runs as the data store (e.g. relational or document database).
3952
+ The test case is at verification level: it pins down what the objects it verifies
3953
+ leave open, namely concrete data (e.g. `the correct six-digit token`), a boundary
3954
+ or equivalence class (e.g. `one more question within the same minute`), and an
3955
+ observable assertion, including the negative one (e.g. `the rejected question is
3956
+ not stored and the earlier questions remain unchanged`).
3957
+
3958
+ A test case which merely rephrases a scenario in different words, adding none of these,
3959
+ is redundant and should be sharpened or dropped. Conversely, one scenario can require
3960
+ several test cases (one per boundary or equivalence class), and one test case can
3961
+ verify a requirement, a rule, and a scenario at once.
3962
+
3963
+ A test case whose stimulus is a sequence rather than a single action carries the
3964
+ procedure in its body as sequentially numbered, imperative steps, mirroring the
3965
+ steps of a use case scenario (e.g. `1. The user logs in on device A. 2. The same
3966
+ user logs in on device B.`), with `INPUT` naming the decisive stimulus among them.
3967
+
3968
+ A test case verifying an architecture element asserts the element itself, not the
3969
+ threshold behind it: a threshold is the `METRIC` of a Non-Functional Requirement and
3970
+ verified by referencing the requirement, while a Quality Perspectives tactic is
3971
+ referenced only when its mechanism is the assertion (e.g. that the failover switch
3972
+ happens, not how fast), an Operations View concern when its procedure is rehearsed
3973
+ (e.g. a restore drill), a Deployment View node or network when its topology is
3974
+ inspected (e.g. a port scan proving an `Isolated` segment), a component or
3975
+ concurrency unit when its collaboration or contention is exercised, an aspect of
3976
+ the Development Aspects or a Design Decisions decision when its rule is checked by
3977
+ an architectural fitness function (e.g. no dependency edge against the layering).
3260
3978
  diagram:
3261
3979
  type: hub
3262
3980
  center: self
3263
- hierarchy: true
3264
- properties:
3265
- - PRODUCT
3981
+ nodes: "[[TEST:TC.TEST-CASE:*]], [[REQS:FR.REQUIREMENT:*]], [[REQS:NR.REQUIREMENT:*]],
3982
+ [[REQS:DR.RULE:*]], [[REQS:UC.USE-CASE:*.SCENARIO:*]], [[REQS:DW.WORKFLOW:*]],
3983
+ [[DATA:SM.LIFECYCLE:*.TRANSITION:*]], [[DATA:DM.ENTITY:*.ATTRIBUTE:*]],
3984
+ [[DATA:AM.ROLE:*.PERMISSION:*]], [[APIS:IE.ENDPOINT:*]],
3985
+ [[UXUI:DS.STORYBOARD:*.FRAME:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]],
3986
+ [[ARCH:DA.ASPECT:*]], [[ARCH:DV.NODE:*]], [[ARCH:DV.NETWORK:*]],
3987
+ [[ARCH:OV.CONCERN:*]], [[ARCH:QP.TACTIC:*]], [[ARCH:DD.DECISION:*]]"
3988
+ labeled: true
3989
+ qualified: true
3266
3990
  config:
3267
3991
  size-node-width-max: 440
3268
3992
  size-node-height-scale: 1.75
3269
- childs:
3270
- - kind: COMPONENT
3993
+ props:
3994
+ - name: VERIFIES
3271
3995
  desc: >
3272
- A single technology component, named with a short (2-5 word) summary (e.g.
3273
- `UI Framework`, `Web Server`, `Relational Database`) and described in a
3274
- concise (1-3 sentence) paragraph by how the product is used within the
3275
- solution and how it fits into the overall technology stack, plus a
3276
- 1-sentence rationale ("why") for choosing this product over the
3277
- alternatives.
3278
- props:
3279
- - name: PRODUCT
3280
- desc: >
3281
- The concrete product, library, or framework chosen for this
3282
- component (e.g. `VueJS`, `Node.js`, `PostgreSQL`).
3283
- - name: ALTERNATIVES
3284
- desc: >
3285
- Comma-separated names of products which would also fit this
3286
- component but were not chosen (e.g. `React, Svelte`).
3287
- optional: true
3288
- - name: COVERAGE
3289
- desc: |
3290
- A comma-separated list of either one or more of the *Client
3291
- Aspects* or one or more of the *Server Aspects* (or their
3292
- sub-aspects) defined below. The general goal is to achieve a
3293
- maximum coverage of all aspects per `TIER` with the minimum
3294
- total number of `PRODUCT`s.
3295
-
3296
- The known *Client Aspects* which usually have to be covered (at
3297
- least for clients in a Rich-Client architecture):
3298
-
3299
- - **Interface Theme**:
3300
- Style Reset, Shape, Color, Gradient, Shadow, Font, Icon.
3301
-
3302
- - **Interface Widgets**:
3303
- Icon, Label, Text Paragraph, Image, Form, Text-Field,
3304
- Text-Area, Date Picker, Toggle, Radio Button, Checkbox,
3305
- Select List, Slider, Progress Bar, Hyperlink, Popup Menu,
3306
- Dropdown Menu, Toolbar, Tooltip, Tab, Pill, Breadcrumb,
3307
- Pagination, Badge, Alert, Panel, Modal, Table, Scrollbar,
3308
- Carousel.
3309
-
3310
- - **Interface Layouting**:
3311
- Responsive Design, Media Query, Frame, Grid, Padding, Border,
3312
- Margin, Alignment, Force, Magnetism.
3313
-
3314
- - **Interface Effects**:
3315
- Transition, Transformation, Keyframes, Easing Function, Sound
3316
- Effect, Physics.
3317
-
3318
- - **Interface Interactions**:
3319
- Mouse, Keyboard, Touchscreen, Gesture, Clipboard, Drag & Drop.
3320
-
3321
- - **Interface States**:
3322
- Rendered, Enabled, Visible, Focused, Warning, Error, Floating.
3323
-
3324
- - **Interface Mask**:
3325
- Markup Loading, Markup Generation, Virtual DOM, Text, Bitmaps,
3326
- Vectors, 2D/3D Canvas, Accessibility.
3327
-
3328
- - **Interface Internationalization**:
3329
- Text Internationalization (I18N).
3330
-
3331
- - **Data Conversion**:
3332
- Value Formatting, Value Parsing, Localization (L10N).
3333
-
3334
- - **Data Binding**:
3335
- Reactive, Observer, Unidirectional, Bidirectional, Incremental.
3336
-
3337
- - **Presentation Model**:
3338
- Parameter Value, Command Value, State Value, Data Value, Event
3339
- Value, Value Validation, Presentation Logic.
3340
-
3341
- - **Dialog Navigation**:
3342
- Deep Linking, Routing, Dialog Flow.
3343
-
3344
- - **Dialog Automation**:
3345
- Dialog Macros, Click-Through, Smoke Testing.
3346
-
3347
- - **Dialog Communication**:
3348
- Service, Event, Model, Socket, Hooks.
3349
-
3350
- - **Dialog Life-Cycle**:
3351
- Component States, Component State Transitions.
3352
-
3353
- - **Dialog Structure**:
3354
- Component, Model/View/Controller Roles, Hierarchical
3355
- Composition.
3356
-
3357
- - **State Persistence**:
3358
- Local Storage, Cookies, Caching.
3359
-
3360
- - **Business Model**:
3361
- Entity, Field, Relationship, Universally Unique Identifiers
3362
- (UUID).
3363
-
3364
- - **Use-Case Authorization**:
3365
- User Experience, Dialog Restriction, User, Group, Role,
3366
- Use-Case, Data, Access.
3367
-
3368
- - **Client Networking**:
3369
- Request/Response, Synchronization, Push, Pull, Pulled-Push,
3370
- REST, GraphQL, Authentication, Session.
3371
-
3372
- - **Environment Detection**:
3373
- Runtime Detection, Feature Detection.
3374
-
3375
- The known *Server Aspects* which usually have to be covered (at
3376
- least for servers, sometimes called Thin-Servers, in a Rich-Client
3377
- architecture):
3378
-
3379
- - **Environment Detection**:
3380
- Detect the run-time environment, like underlying operating
3381
- system, execution platform, network topology, feature toggles,
3382
- etc.
3383
-
3384
- - **Argument Parsing**:
3385
- Parse options and arguments of the Command-Line Interface
3386
- (CLI) to bootstrap application parameters.
3387
-
3388
- - **Configuration Parsing**:
3389
- Load and parse directives from a configuration file to
3390
- bootstrap application parameters.
3391
-
3392
- - **Process Daemonizing**:
3393
- Detach from the startup terminal and host process in order to
3394
- run fully independently.
3395
-
3396
- - **Process Management**:
3397
- (Pre-)fork child processes and/or threads of execution and
3398
- monitor and control them during the life-cycle of the
3399
- application.
3400
-
3401
- - **Component Management**:
3402
- Structure the code into components, instantiate them at
3403
- run-time and manage them in a stateful component life-cycle.
3404
-
3405
- - **Component Communication**:
3406
- Provide inter-component communication mechanisms like events,
3407
- hooks, registry, etc.
3408
-
3409
- - **Server Networking**:
3410
- Listen to network sockets, accept connections and manage
3411
- request/response and message communication.
3412
-
3413
- - **Peer Information**:
3414
- Determine unique identification and add-on information about
3415
- the client peer.
3416
-
3417
- - **Session Handling**:
3418
- Manage secured per-connection sessions to keep state between
3419
- communication requests and/or client sessions.
3420
-
3421
- - **User Authentication**:
3422
- Determine and validate the unique identity of the user
3423
- communicating over the current network connection.
3424
-
3425
- - **Request Validation**:
3426
- Validate the syntactical and semantical compliance of the
3427
- requests and sanitize the requests.
3428
-
3429
- - **Request Processing**:
3430
- Process the request by dispatching execution according to the
3431
- provided request and determined context information.
3432
-
3433
- - **Role Authorization**:
3434
- Determine whether the role of the current user is allowed to
3435
- execute the current request.
3436
-
3437
- - **Client Networking**:
3438
- Provide mechanisms to connect to peers over the network and
3439
- perform request/response and/or publish/subscribe
3440
- communication.
3441
-
3442
- - **Task Scheduling**:
3443
- Schedule and execute recurring tasks independent of regular
3444
- I/O operations.
3445
-
3446
- - **Execution Tracing**:
3447
- Provide mechanisms for tracing the execution by logging event
3448
- and measurement information at certain points of interest.
3449
-
3450
- - **Database Access**:
3451
- Map in-memory domain entities onto a data-store-dependent
3452
- persistent data structure.
3453
-
3454
- - **Database Connectivity**:
3455
- Locally or remotely connect the database access layer to the
3456
- underlying data store.
3457
-
3458
- - **Database Schema**:
3459
- Create, update or downgrade the data schema inside the
3460
- underlying data store.
3461
-
3462
- - **Database Bootstrapping**:
3463
- Create, update or downgrade both mandatory bootstrapping and
3464
- optional domain-specific data inside the underlying data
3465
- store.
3466
- optional: true
3467
- - name: WHEN
3468
- desc: |
3469
- The lifecycle phase in which the component is relevant, one of:
3470
-
3471
- - `Build-Time`: Used during development, compilation, or
3472
- packaging.
3473
- - `Run-Time`: Used while the solution executes in production.
3474
- value: enum(Build-Time,Run-Time)
3475
- optional: true
3996
+ Comma-separated references to the FUNCTIONAL-REQUIREMENTS or
3997
+ NON-FUNCTIONAL-REQUIREMENTS objects, the DOMAIN-RULES objects, the
3998
+ USE-CASES scenario objects, the STATE-MODEL transition objects, the
3999
+ DATA-MODEL attribute objects, the AUTHORIZATION-MODEL permission objects,
4000
+ the INTERFACE-ENDPOINTS objects, the DIALOG-STORYBOARD frame objects, the
4001
+ FUNCTIONALITY-VIEW, CONCURRENCY-VIEW, DEVELOPMENT-ASPECTS, DEPLOYMENT-VIEW
4002
+ (node and network), OPERATIONS-VIEW, and QUALITY-PERSPECTIVES objects,
4003
+ and/or the DESIGN-DECISIONS objects the test case verifies, so that a
4004
+ scenario (in particular an `Exceptional` one, judged by its `OUTCOME`) is
4005
+ covered by an acceptance test beside the requirements it exercises, a rule
4006
+ (judged by the condition it states) is proven to hold, not just to be
4007
+ documented, a transition (judged by its `GUARD` and the resulting state) is
4008
+ proven to be permitted exactly as modeled, an attribute (judged by its
4009
+ `TYPE` and `CONSTRAINT`) is proven to reject the values outside its range,
4010
+ pattern, or invariant, a permission (judged by the operations it grants
4011
+ and, the model being closed, by the ones it denies) is proven to be
4012
+ enforced, an endpoint (judged by its arguments, options, and results) is
4013
+ proven to honor its contract, a frame (judged by the dialog step it
4014
+ storyboards) is proven to be reachable and to behave as storyboarded, a
4015
+ component or unit (judged by its responsibility and dependencies) is proven
4016
+ to collaborate and to withstand contention as modeled, an aspect (judged by
4017
+ the rule it states) is proven to be obeyed by the source structure, a node
4018
+ or network (judged by its `INSTANCES`, `PART-OF`, and `SCOPE`) is proven to
4019
+ be deployed and isolated as modeled, a concern (judged by its procedure) is
4020
+ proven to be performable, a tactic (judged by its `MECHANISM`) is proven to
4021
+ take effect, and a decision (judged by its `WHAT`) is proven to be complied
4022
+ with.
4023
+ value: list([[REQS:*.REQUIREMENT:*]], [[REQS:DR.RULE:*]], [[REQS:UC.USE-CASE:*.SCENARIO:*]],
4024
+ [[DATA:SM.LIFECYCLE:*.TRANSITION:*]], [[DATA:DM.ENTITY:*.ATTRIBUTE:*]],
4025
+ [[DATA:AM.ROLE:*.PERMISSION:*]], [[APIS:IE.ENDPOINT:*]],
4026
+ [[UXUI:DS.STORYBOARD:*.FRAME:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:CO.UNIT:*]],
4027
+ [[ARCH:DA.ASPECT:*]], [[ARCH:DV.NODE:*]], [[ARCH:DV.NETWORK:*]],
4028
+ [[ARCH:OV.CONCERN:*]], [[ARCH:QP.TACTIC:*]], [[ARCH:DD.DECISION:*]])
4029
+ - name: WORKFLOWS
4030
+ desc: >
4031
+ Comma-separated references to the DOMAIN-WORKFLOWS objects the test case
4032
+ walks through end to end, i.e. whose activities and handoffs its procedure
4033
+ steps cross in order, so that the collaboration across actors and sittings
4034
+ (not just the use cases of each single sitting) is proven to work as
4035
+ modeled; omitted for a test case confined to a single sitting.
4036
+ value: list([[REQS:DW.WORKFLOW:*]])
4037
+ optional: true
4038
+ - name: PRE-CONDITION
4039
+ desc: >
4040
+ The state or setup that must hold before the test is executed.
4041
+ optional: true
4042
+ - name: INPUT
4043
+ desc: >
4044
+ The mandatory, concrete input data or action applied during the test, i.e.
4045
+ the stimulus whose response the `EXPECTED` judges.
4046
+ - name: EXPECTED
4047
+ desc: >
4048
+ The mandatory, concrete, observable response of the solution to the `INPUT`
4049
+ (a message shown, a session issued, a submission rejected) that defines a
4050
+ passing test, as opposed to the `POST-CONDITION` which is the state left
4051
+ behind. When the test case verifies a NON-FUNCTIONAL-REQUIREMENTS object,
4052
+ the expected response restates the `METRIC` threshold of that requirement
4053
+ as the pass criterion (e.g. `p95 latency < 200 ms`) rather than a
4054
+ qualitative phrase (e.g. `remains responsive`).
4055
+ - name: POST-CONDITION
4056
+ desc: >
4057
+ The persisted state that must hold after the test completes (e.g. `the
4058
+ authorization token is in state used`), including the state that must not
4059
+ have changed (e.g. `no session token exists`), as opposed to the `EXPECTED`
4060
+ which is the immediate response, and omitted for a test whose input leaves
4061
+ no state behind.
4062
+ optional: true
3476
4063