@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.
- package/README.md +2 -1
- package/dst/specbook-api.js +19 -16
- package/dst/specbook-cli.js +14 -13
- package/dst/specbook-cmd-describe.js +20 -18
- package/dst/specbook-cmd-export.d.ts +3 -1
- package/dst/specbook-cmd-export.js +27 -9
- package/dst/specbook-cmd-preview.js +11 -2
- package/dst/specbook-config.js +90 -74
- package/dst/specbook-diagnostic.js +2 -1
- package/dst/specbook-diagram.d.ts +4 -0
- package/dst/specbook-diagram.js +0 -0
- package/dst/specbook-export-common.js +28 -14
- package/dst/specbook-export-html.d.ts +4 -2
- package/dst/specbook-export-html.js +89 -113
- package/dst/specbook-export-md.js +4 -3
- package/dst/specbook-export-pdf.d.ts +1 -1
- package/dst/specbook-export-pdf.js +11 -7
- package/dst/specbook-format.md +13 -9
- package/dst/specbook-format.yaml +1263 -676
- package/dst/specbook-link.d.ts +2 -0
- package/dst/specbook-link.js +77 -52
- package/dst/specbook-mcp.js +5 -6
- package/dst/specbook-parse-common.d.ts +1 -0
- package/dst/specbook-parse-common.js +4 -0
- package/dst/specbook-parse-semantic.js +81 -71
- package/dst/specbook-parse-syntax.js +4 -3
- package/dst/specbook-parse.js +1 -1
- package/dst/specbook-theme.d.ts +0 -1
- package/dst/specbook-theme.js +2 -3
- package/package.json +11 -9
package/dst/specbook-format.yaml
CHANGED
|
@@ -9,53 +9,52 @@
|
|
|
9
9
|
# Modeling Purpose
|
|
10
10
|
# ----------------
|
|
11
11
|
#
|
|
12
|
-
# This schema allows
|
|
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
|
|
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
|
-
# |
|
|
48
|
-
# |
|
|
49
|
-
# | ARCH:
|
|
50
|
-
# | ARCH:
|
|
51
|
-
# | ARCH:
|
|
52
|
-
# | ARCH:
|
|
53
|
-
# | ARCH:
|
|
54
|
-
# | ARCH:
|
|
55
|
-
# | ARCH:
|
|
56
|
-
# |
|
|
57
|
-
# |
|
|
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
|
-
#
|
|
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
|
|
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:*]], [[
|
|
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:
|
|
300
|
-
file: 03-REQS-
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
|
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:
|
|
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
|
|
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:
|
|
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
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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 *
|
|
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
|
|
2685
|
-
|
|
2686
|
-
|
|
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:
|
|
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`:
|
|
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:
|
|
2658
|
+
- name: PART-OF
|
|
2710
2659
|
desc: >
|
|
2711
|
-
|
|
2712
|
-
|
|
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:
|
|
2730
|
-
id:
|
|
2731
|
-
file:
|
|
2711
|
+
name: Technology Stack
|
|
2712
|
+
id: TS
|
|
2713
|
+
file: 24-ARCH-TS-Technology-Stack.md
|
|
2732
2714
|
desc: >
|
|
2733
|
-
The
|
|
2734
|
-
|
|
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
|
-
-
|
|
2737
|
-
https://
|
|
2738
|
-
-
|
|
2739
|
-
https://
|
|
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:
|
|
2743
|
-
properties:
|
|
2744
|
-
- CONCERN
|
|
2726
|
+
nodes: "[[ARCH:TS.TIER:*]]"
|
|
2745
2727
|
childs:
|
|
2746
|
-
- kind:
|
|
2747
|
-
desc:
|
|
2748
|
-
|
|
2749
|
-
|
|
2750
|
-
|
|
2751
|
-
|
|
2752
|
-
|
|
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
|
-
|
|
2757
|
-
qualified: true
|
|
2745
|
+
hierarchy: true
|
|
2758
2746
|
properties:
|
|
2759
|
-
-
|
|
2747
|
+
- PRODUCT
|
|
2760
2748
|
config:
|
|
2761
2749
|
size-node-width-max: 440
|
|
2762
|
-
|
|
2763
|
-
|
|
2764
|
-
|
|
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
|
-
|
|
2782
|
-
`
|
|
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
|
-
|
|
2785
|
-
|
|
2786
|
-
|
|
2787
|
-
|
|
2788
|
-
|
|
2789
|
-
|
|
2790
|
-
|
|
2791
|
-
|
|
2792
|
-
|
|
2793
|
-
|
|
2794
|
-
|
|
2795
|
-
|
|
2796
|
-
|
|
2797
|
-
|
|
2798
|
-
|
|
2799
|
-
|
|
2800
|
-
|
|
2801
|
-
|
|
2802
|
-
|
|
2803
|
-
|
|
2804
|
-
|
|
2805
|
-
|
|
2806
|
-
|
|
2807
|
-
|
|
2808
|
-
|
|
2809
|
-
|
|
2810
|
-
|
|
2811
|
-
|
|
2812
|
-
|
|
2813
|
-
|
|
2814
|
-
|
|
2815
|
-
|
|
2816
|
-
|
|
2817
|
-
|
|
2818
|
-
|
|
2819
|
-
|
|
2820
|
-
|
|
2821
|
-
|
|
2822
|
-
|
|
2823
|
-
|
|
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
|
-
|
|
2826
|
-
|
|
2827
|
-
|
|
2828
|
-
|
|
2829
|
-
|
|
2830
|
-
|
|
2831
|
-
|
|
2832
|
-
|
|
2833
|
-
|
|
2834
|
-
|
|
2835
|
-
|
|
2836
|
-
|
|
2837
|
-
|
|
2838
|
-
|
|
2839
|
-
|
|
2840
|
-
|
|
2841
|
-
|
|
2842
|
-
|
|
2843
|
-
|
|
2844
|
-
|
|
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
|
|
2848
|
-
id:
|
|
2849
|
-
file:
|
|
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:
|
|
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` (
|
|
2874
|
-
|
|
2875
|
-
|
|
2876
|
-
`
|
|
2877
|
-
(
|
|
2878
|
-
|
|
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:
|
|
2883
|
-
file:
|
|
3200
|
+
id: DV
|
|
3201
|
+
file: 27-ARCH-DV-Deployment-View.md
|
|
2884
3202
|
desc: >
|
|
2885
|
-
The environment into which the solution is deployed,
|
|
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:
|
|
2896
|
-
nodes: "[[ARCH:
|
|
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
|
|
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:
|
|
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:
|
|
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
|
|
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
|
|
2932
|
-
|
|
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
|
|
2936
|
-
this node
|
|
2937
|
-
|
|
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:
|
|
3384
|
+
- name: CONNECTS-TO
|
|
2940
3385
|
desc: >
|
|
2941
|
-
|
|
2942
|
-
|
|
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:
|
|
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
|
-
|
|
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
|
|
2969
|
-
tools
|
|
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
|
-
|
|
2974
|
-
|
|
2975
|
-
`
|
|
2976
|
-
|
|
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
|
|
2980
|
-
objects the
|
|
2981
|
-
|
|
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:
|
|
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.
|
|
3575
|
+
nodes: "[[ARCH:QP.TACTIC:*]]"
|
|
3000
3576
|
properties:
|
|
3001
3577
|
- QUALITY
|
|
3002
3578
|
childs:
|
|
3003
|
-
- kind:
|
|
3579
|
+
- kind: TACTIC
|
|
3004
3580
|
desc: >
|
|
3005
|
-
A single quality
|
|
3006
|
-
|
|
3007
|
-
|
|
3008
|
-
|
|
3009
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
3028
|
-
|
|
3029
|
-
|
|
3030
|
-
|
|
3031
|
-
`
|
|
3032
|
-
|
|
3033
|
-
|
|
3034
|
-
|
|
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
|
-
|
|
3636
|
+
tactic addresses.
|
|
3039
3637
|
value: list([[REQS:NR.*]])
|
|
3040
|
-
- name:
|
|
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
|
-
|
|
3043
|
-
|
|
3044
|
-
`
|
|
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
|
|
3048
|
-
|
|
3049
|
-
|
|
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:
|
|
3054
|
-
id:
|
|
3055
|
-
file:
|
|
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
|
|
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:
|
|
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
|
|
3079
|
-
|
|
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:
|
|
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
|
-
|
|
3151
|
-
`
|
|
3152
|
-
|
|
3153
|
-
|
|
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
|
-
|
|
3796
|
+
acyclic: true
|
|
3797
|
+
- name: DRIVEN-BY
|
|
3160
3798
|
desc: >
|
|
3161
|
-
|
|
3162
|
-
|
|
3163
|
-
|
|
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?"
|
|
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
|
-
|
|
3233
|
-
|
|
3234
|
-
|
|
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
|
|
3238
|
-
|
|
3239
|
-
|
|
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
|
-
-
|
|
3242
|
-
https://www.
|
|
3243
|
-
-
|
|
3244
|
-
https://
|
|
3245
|
-
-
|
|
3246
|
-
https://
|
|
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: "[[
|
|
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:
|
|
3252
|
-
|
|
3253
|
-
|
|
3254
|
-
|
|
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
|
-
|
|
3257
|
-
|
|
3258
|
-
|
|
3259
|
-
|
|
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
|
-
|
|
3264
|
-
|
|
3265
|
-
|
|
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
|
-
|
|
3270
|
-
-
|
|
3993
|
+
props:
|
|
3994
|
+
- name: VERIFIES
|
|
3271
3995
|
desc: >
|
|
3272
|
-
|
|
3273
|
-
|
|
3274
|
-
|
|
3275
|
-
|
|
3276
|
-
|
|
3277
|
-
|
|
3278
|
-
|
|
3279
|
-
-
|
|
3280
|
-
|
|
3281
|
-
|
|
3282
|
-
|
|
3283
|
-
|
|
3284
|
-
|
|
3285
|
-
|
|
3286
|
-
|
|
3287
|
-
|
|
3288
|
-
|
|
3289
|
-
|
|
3290
|
-
|
|
3291
|
-
|
|
3292
|
-
|
|
3293
|
-
|
|
3294
|
-
|
|
3295
|
-
|
|
3296
|
-
|
|
3297
|
-
|
|
3298
|
-
|
|
3299
|
-
|
|
3300
|
-
|
|
3301
|
-
|
|
3302
|
-
|
|
3303
|
-
|
|
3304
|
-
|
|
3305
|
-
|
|
3306
|
-
|
|
3307
|
-
|
|
3308
|
-
|
|
3309
|
-
|
|
3310
|
-
|
|
3311
|
-
|
|
3312
|
-
|
|
3313
|
-
|
|
3314
|
-
|
|
3315
|
-
|
|
3316
|
-
|
|
3317
|
-
|
|
3318
|
-
|
|
3319
|
-
|
|
3320
|
-
|
|
3321
|
-
|
|
3322
|
-
|
|
3323
|
-
|
|
3324
|
-
|
|
3325
|
-
|
|
3326
|
-
|
|
3327
|
-
|
|
3328
|
-
|
|
3329
|
-
|
|
3330
|
-
|
|
3331
|
-
|
|
3332
|
-
|
|
3333
|
-
|
|
3334
|
-
|
|
3335
|
-
|
|
3336
|
-
|
|
3337
|
-
|
|
3338
|
-
|
|
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
|
|