@rse/specbook 0.9.7 → 0.9.9

package/dst/specbook-format.yaml

@@ -0,0 +1,1484 @@
+##
+##  Specification Book (SpecBook)
+##  Copyright (c) 2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+##  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+##
+
+-   kind: META
+    name: Title
+    id:   TI
+    file: META-01-TI-Title.md
+    desc: >
+        The top-level specification meta information.
+        Some of the information is rendered onto the title page.
+    props:
+        -   name: LOGO
+            desc: The logo of the specification.
+            optional: true
+        -   name: TITLE
+            desc: The title of the specification.
+        -   name: SUBTITLE
+            desc: The subtitle of the specification.
+            optional: true
+        -   name: AUTHOR
+            desc: The author of the specification.
+            optional: true
+        -   name: VERSION
+            desc: The version of the specification.
+            optional: true
+        -   name: LANG
+            desc: The language of the specification texts (ISO 639-1 code).
+            value: /^[a-z]{2}(-[A-Za-z0-9]+)?$/
+            optional: true
+        -   name: CHARSET
+            desc: The character set the embedded fonts are subsetted to.
+            value: enum(US-ASCII,ISO-8859-1,ISO-Latin-1,ISO-8859-15,ISO-Latin-15,UTF-8)
+            optional: true
+        -   name: PAPER-SIZE
+            desc: The paper size the print/PDF rendering is targeted at.
+            value: enum(A4,Letter,Legal)
+            optional: true
+        -   name: THEME-STYLE
+            desc: The theme style.
+            value: enum(dark,light)
+            optional: true
+        -   name: THEME-TONE
+            desc: The theme color tone.
+            value: /^#[0-9a-fA-F]{6}$/
+            optional: true
+
+-   kind: SPEC
+    name: Solution Vision
+    id: SV
+    file: SPEC-01-SV-Solution-Vision.md
+    desc: >
+        The high-level, aspirational description of the solution, capturing its purpose, value
+        proposition, and the desired future state it aims to achieve.
+    childs:
+        -   kind: ASPECT
+            desc: >
+                A single vision aspect, named with a short (2-5 word) summary and described in a
+                concise (1-3 sentence) paragraph in an aspirational but unambiguous tone.
+
+                Recommended aspects are `Purpose` (why the solution exists), `Target Audience` (who
+                it serves), `Value Proposition` (the unique benefit offered), `Differentiators` (how
+                it stands apart from alternatives), and `Future State` (the desired outcome once
+                adopted).
+
+-   kind: SPEC
+    name: User Personas
+    id: UP
+    file: SPEC-02-UP-User-Personas.md
+    desc: >
+        The *archetypal* user profiles representing distinct user groups, capturing their goals,
+        needs, behaviors, and context.
+    format:
+        maxTableColumns: 5
+    childs:
+        -   kind: PERSONA
+            desc: >
+                An archetypal user profile, named with a per-artifact unique first name of the
+                fictional person and carrying a short, bold first-person quote -- written in the
+                persona's own voice, like a "tagline", "mantra", or "defining statement" -- that
+                captures their core attitude, motivation, frustration, or need in a single memorable
+                line.
+            props:
+                -   name: GENDER
+                    desc: >
+                        The gender of the persona: `male`, `female`, or `diverse`.
+                    value: enum(male,female,diverse)
+                -   name: AGE
+                    desc: The age in years of the persona.
+                    value: /^[0-9]+$/
+                -   name: ROLE
+                    desc: The role of the persona.
+
+-   kind: SPEC
+    name: User Journey
+    id: UJ
+    file: SPEC-03-UJ-User-Journey.md
+    desc: >
+        The end-to-end experience a user has while discovering, adopting, and using the solution,
+        mapping their steps, touchpoints, and emotions over time.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:UJ.JOURNEY:*]]"
+        properties:
+            -   ACTOR
+    childs:
+        -   kind: JOURNEY
+            desc: >
+                The end-to-end journey of a single persona (or of multiple personas sharing the same
+                experience as role variants), named with a 2-5 word summary of the pursued scenario.
+            props:
+                -   name: ACTOR
+                    desc: >
+                        Comma-separated references to the User Personas objects experiencing the
+                        journey.
+                    value: list([[SPEC:UP.PERSONA:*]])
+            childs:
+                -   kind: STEP
+                    desc: >
+                        A single step of the journey, named with a 5-10 word summary of the step at
+                        its touchpoint.
+                    props:
+                        -   name: STAGE
+                            desc: >
+                                The journey stage the step belongs to: `Awareness` (the actor is not
+                                aware of the solution, but has a need), `Consideration` (the actor
+                                is aware of the solution and considers its use), `Decision` (the
+                                actor wants to pick the solution), `Onboarding` (the actor starts
+                                using the solution), `Retention` (the actor stays a user in the long
+                                term), or `Advocacy` (the actor is a fan of the solution and tells
+                                others).
+                            value: enum(Awareness,Consideration,Decision,Onboarding,Retention,Advocacy)
+                        -   name: GOAL
+                            desc: What the actor wants to achieve at this step.
+                        -   name: TOUCHPOINT
+                            desc: >
+                                Where or how the interaction happens (e.g. landing page, email,
+                                support call).
+                        -   name: ACTION
+                            desc: What the actor actually does at this step.
+                        -   name: EMOTION
+                            desc: >
+                                The **AS IS** felt state at this step, given as a word plus an
+                                intensity on a 1-5 Likert scale (e.g. `Curious (4)`).
+                            value: /^.+ \([1-5]\)$/
+                        -   name: PAIN-POINT
+                            desc: >
+                                The **AS IS** friction or frustration the actor encounters at this
+                                step.
+                            optional: true
+
+-   kind: SPEC
+    name: Functional Requirements
+    id: FR
+    file: SPEC-04-FR-Functional-Requirements.md
+    desc: >
+        The concrete behaviors and capabilities the solution must provide, describing *what* the
+        system does in terms of functions, features, and operations.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:FR.REQUIREMENT:*]]"
+        properties:
+            -   PRIORITY
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: REQUIREMENT
+            desc: >
+                A single functional requirement, named with a short (3-8 word) summary and described
+                in a concise (1-3 sentence) paragraph as *what* the solution must do, written with
+                the keyword `MUST`, `SHOULD`, `COULD`, or `WONT` to indicate the obligation level,
+                plus a 1-sentence rationale ("why").
+            props:
+                -   name: PRIORITY
+                    desc: >
+                        The MoSCoW priority of the requirement: `MUST`, `SHOULD`, `COULD`, or
+                        `WONT`. The `WONT` priority records a requirement deliberately excluded from
+                        the current scope ("won't have this time"), preserving the conscious
+                        decision rather than silently dropping it.
+                    value: enum(MUST,SHOULD,COULD,WONT)
+
+-   kind: SPEC
+    name: Non-Functional Requirements
+    id: NR
+    file: SPEC-05-NR-Non-Functional-Requirements.md
+    desc: >
+        The quality attributes and constraints the solution must satisfy, such as performance,
+        security, scalability, reliability, and usability.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:NR.REQUIREMENT:*]]"
+        properties:
+            -   PRIORITY
+            -   CATEGORY
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: REQUIREMENT
+            desc: >
+                A single non-functional requirement, named with a short (3-8 word) summary and
+                described in a concise (1-3 sentence) paragraph as the quality attribute or
+                constraint the solution must satisfy, plus a 1-sentence rationale ("why").
+
+                The description especially *MUST* contain a *METRIC* within the `CATEGORY`, which
+                (according to the SMART principle) is the *specific*, *measurable*, *achievable*,
+                *relevant*, and *time-bound* threshold or target by which the requirement is judged
+                satisfied (e.g. `p95 latency < 200ms`, `99.9% uptime`).
+            props:
+                -   name: PRIORITY
+                    desc: >
+                        The MoSCoW priority of the requirement: `MUST`, `SHOULD`, `COULD`, or
+                        `WONT`. The `WONT` priority records a requirement deliberately excluded from
+                        the current scope ("won't have this time"), preserving the conscious
+                        decision rather than silently dropping it.
+                    value: enum(MUST,SHOULD,COULD,WONT)
+                -   name: CATEGORY
+                    desc: >
+                        The quality attribute category the requirement addresses, according to the
+                        top-level characteristics of the ISO/IEC 25010:2023 Software-Quality Model
+                        (except for `Functional Suitability`, which is covered by the Functional
+                        Requirements instead).
+                    value: enum(Performance,Compatibility,Usability,Reliability,Security,Safety,Maintainability,Flexibility,Compliance)
+
+-   kind: SPEC
+    name: Business Rules
+    id: BR
+    file: SPEC-06-BR-Business-Rules.md
+    desc: >
+        The domain invariants, policies, and decision logic that must always hold true in the
+        problem domain, independent of any single feature, constraining the Functional and
+        Non-Functional Requirements.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:BR.RULE:*]]"
+        properties:
+            -   CATEGORY
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: RULE
+            desc: >
+                A single business rule, named with a short (3-8 word) summary and described in a
+                concise (1-3 sentence) paragraph stating the rule declaratively as a condition that
+                must hold, written with the keyword `MUST`, `SHOULD`, or `MUST NOT` to indicate the
+                obligation level and naming the domain terms it governs (as defined in the
+                Glossary), plus a 1-sentence rationale ("why").
+            props:
+                -   name: CATEGORY
+                    desc: >
+                        The kind of rule: `Invariant` (a condition that must always hold),
+                        `Constraint` (a limit on allowed values or actions), `Derivation` (a value
+                        computed from others), or `Policy` (a deliberate business decision or
+                        guideline).
+                    value: enum(Invariant,Constraint,Derivation,Policy)
+                -   name: CONSTRAINS
+                    desc: >
+                        Comma-separated references to the FUNCTIONAL-REQUIREMENTS or
+                        NON-FUNCTIONAL-REQUIREMENTS objects the rule constrains.
+                    value: list([[SPEC:FR.*]], [[SPEC:NR.*]])
+                    optional: true
+
+-   kind: SPEC
+    name: Data Model
+    id: DM
+    file: SPEC-07-DM-Data-Model.md
+    desc: >
+        The structure of named entities, with named attributes and directed relationships, of the
+        data the solution manages, defining how information is organized and connected.
+    diagram:
+        type: graph
+        nodes: "[[SPEC:DM.ENTITY:*]]"
+        edges: "[[SPEC:DM.ENTITY:*.RELATION:*]]"
+    childs:
+        -   kind: ENTITY
+            name: "[A-Z][a-zA-Z0-9]*"
+            desc: >
+                A named entity of the data model, carrying a Pascal-cased, 1-3 word long,
+                per-artifact unique name, and described by a 1-sentence description ("what") plus a
+                1-sentence rationale ("why").
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[SPEC:DM.ENTITY:*]]"
+                edges: "[[SPEC:DM.ENTITY:*.RELATION:*]]"
+                config:
+                    size-node-width-max: 440
+            childs:
+                -   kind: ATTRIBUTE
+                    name: "[a-z][a-zA-Z0-9]*"
+                    desc: >
+                        A named attribute of the entity, carrying a camel-cased, 1-3 word long,
+                        per-entity unique identifier, and described by a 1-sentence description
+                        ("what") plus a 1-sentence rationale ("why").
+                    props:
+                        -   name: TYPE
+                            desc: >
+                                The type of the entity attribute, one of `boolean`, `string`,
+                                `integer`, `float`, `uuid`, `bytes`, `date`, `time`, `datetime`, or
+                                `enum(XXX,YYY[,...])`, optionally prefixed with the qualifier
+                                `unique` to indicate inclusion into the primary key of the entity,
+                                and optionally suffixed with `?` to indicate an optional (nullable)
+                                value.
+                            value: /^(?:unique\s+)?(?:boolean|string|integer|float|uuid|bytes|date|time|datetime|enum\((?:[A-Za-z0-9_]+)(?:,\s*[A-Za-z0-9_]+)*\))(?:\?)?$/
+                        -   name: DEFAULT
+                            desc: The default value of the entity attribute.
+                            value: /.*/
+                            optional: true
+                -   kind: RELATION
+                    name: "[a-z][a-zA-Z0-9]*"
+                    desc: >
+                        A named directed relation of the entity, carrying a camel-cased, 1-3 word
+                        long, per-entity unique identifier and targeting another entity, and
+                        described by a 1-sentence description ("what") plus a 1-sentence rationale
+                        ("why").
+                    optional: true
+                    props:
+                        -   name: TYPE
+                            desc: Reference to the DATA-MODEL entity the directed relation targets.
+                            value: "[[SPEC:DM.ENTITY:*]]"
+                        -   name: ARITY
+                            desc: >
+                                The arity (cardinality) of the relation at the target entity: `0..1`
+                                or `?` for zero or one ("optional"), `1` for exactly one
+                                ("mandatory"), `0..n` or `*` for zero or more, `1..n` or `+` for one
+                                or more, or `{n}`/`{n,m}` for an exact number or range.
+                            value: /^(?:\?|\*|\+|\{\d+(?:,\d+)?\}|1|0\.\.1|0\.\.n|1\.\.n)$/
+                            optional: true
+
+-   kind: SPEC
+    name: State Model
+    id: SM
+    file: SPEC-08-SM-State-Model.md
+    desc: >
+        For each entity with a non-trivial lifecycle, the legal states it can occupy and the
+        permitted transitions between them over its lifetime, making the forbidden moves as explicit
+        as the allowed ones.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:SM.LIFECYCLE:*]]"
+        properties:
+            -   ENTITY
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: LIFECYCLE
+            desc: >
+                The lifecycle of a single entity, named with the short (1-3 word) name of the
+                lifecycle, normally the name of the entity it governs.
+            diagram:
+                type: graph
+                edges: "[[SPEC:SM.LIFECYCLE:*.TRANSITION:*]]"
+                edgeSource: FROM
+                edgeTarget: TO
+                onlyConnected: true
+                properties:
+                    -   INITIAL
+                    -   FINAL
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: ENTITY
+                    desc: >
+                        Reference to the DATA-MODEL entity whose lifecycle this models.
+                    value: "[[SPEC:DM.ENTITY:*]]"
+            childs:
+                -   kind: STATE
+                    name: "[A-Z][a-zA-Z0-9]*"
+                    desc: >
+                        A single state the entity can occupy, carrying a short, Pascal-cased,
+                        per-lifecycle unique name (e.g. `Draft`, `Shipped`) and described by a
+                        1-sentence description of what holds true in it.
+
+                        Every state used in a transition *MUST* be declared, and every state with no
+                        outgoing transition *MUST* be final (a non-final state with no outgoing
+                        transition would be a stuck dead-end). The converse does *not* hold: a final
+                        state *MAY* still have outgoing transitions, modeling a resting state that
+                        can later be left again (e.g. a `Closed` state with a `reopen` transition
+                        back to `Active`). Thus the final states are a superset of, but not
+                        necessarily equal to, the states without outgoing transitions.
+                    props:
+                        -   name: INITIAL
+                            desc: >
+                                Whether the state is the initial one, i.e. the single state every
+                                instance of the entity enters upon creation.
+                            value: /^(?:true|false)$/
+                            optional: true
+                        -   name: FINAL
+                            desc: >
+                                Whether the state is a final one, i.e. a terminal state in which the
+                                entity may legally come to rest permanently.
+                            value: /^(?:true|false)$/
+                            optional: true
+                -   kind: TRANSITION
+                    name: "[a-z]+"
+                    desc: >
+                        A single permitted transition between two states, named with the short,
+                        lower-cased verb of the triggering event or action (e.g. `submit`, `ship`,
+                        `cancel`) and described by a 1-sentence description of its side effect
+                        ("what happens"), followed by a ", **WHEN** `<guard>`" clause stating the
+                        condition that must hold for the transition to be permitted. Any move not
+                        listed as a transition is implicitly forbidden.
+                    props:
+                        -   name: FROM
+                            desc: The state the transition departs from.
+                            value: "[[SPEC:SM.LIFECYCLE:*.STATE:*]]"
+                        -   name: TO
+                            desc: The state the transition arrives at.
+                            value: "[[SPEC:SM.LIFECYCLE:*.STATE:*]]"
+
+-   kind: SPEC
+    name: Glossary
+    id: GL
+    file: SPEC-09-GL-Glossary.md
+    desc: >
+        The ubiquitous language of the domain, defining the meaning of each domain term in business
+        language, together with its synonyms and the ambiguities to avoid, shared consistently
+        across all Artifacts.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:GL.TERM:*]]"
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: TERM
+            desc: >
+                A single domain term, named with its canonical, preferred form (capitalized as it
+                should appear in all artifacts) and defined in a concise (1-3 sentence) paragraph in
+                business language, independent of any implementation, referencing other terms by
+                their name where helpful.
+            props:
+                -   name: SYNONYMS
+                    desc: >
+                        Comma-separated list of alternative names or abbreviations that refer to the
+                        same term but are *not* the preferred form.
+                    optional: true
+
+-   kind: SPEC
+    name: Use Cases
+    id: UC
+    file: SPEC-10-UC-Use-Cases.md
+    desc: >
+        The discrete goals users pursue with the solution, each describing an actor's interaction to
+        achieve a specific outcome, together with the concrete step-by-step flows for main,
+        alternative, and exceptional paths.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:UC.USE-CASE:*]]"
+    childs:
+        -   kind: USE-CASE
+            desc: >
+                A discrete goal a user pursues with the solution, named with a short (3-8 word)
+                summary phrased as an actor goal (e.g. `Reset Forgotten Password`) and described in
+                a concise (1-3 sentence) paragraph at a glance, without prescribing the step-by-step
+                flow (which belongs to its `SCENARIO` objects).
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[SPEC:UC.USE-CASE:*]], [[SPEC:UP.PERSONA:*]], [[SPEC:FR.REQUIREMENT:*]]"
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: ACTOR
+                    desc: >
+                        Reference to the PERSONAS object denoting the primary actor pursuing the
+                        goal.
+                    value: "[[SPEC:UP.PERSONA:*]]"
+                -   name: REQUIREMENTS
+                    desc: >
+                        Comma-separated references to the FUNCTIONAL-REQUIREMENTS objects the use
+                        case realizes.
+                    value: list([[SPEC:FR.*]])
+                    optional: true
+                -   name: GOAL
+                    desc: >
+                        The 1-sentence statement of what the actor wants to achieve through this use
+                        case.
+                -   name: PRE-CONDITION
+                    desc: >
+                        The condition that must hold before the use case can begin.
+                    optional: true
+                -   name: POST-CONDITION
+                    desc: >
+                        The condition that holds after the use case completes successfully.
+                    optional: true
+            childs:
+                -   kind: SCENARIO
+                    desc: >
+                        A concrete step-by-step flow of the use case, named with a short (3-8 word)
+                        summary and comprised of sequentially numbered, imperative steps, each
+                        naming the acting party (actor or system) and the action taken (e.g. `The
+                        user submits the login form.`).
+                    props:
+                        -   name: TYPE
+                            desc: >
+                                The path the scenario represents: `Main` (the primary, happy-path
+                                flow), `Alternative` (a valid but secondary flow), or `Exceptional`
+                                (an error or failure-handling flow).
+                            value: enum(Main,Alternative,Exceptional)
+
+-   kind: SPEC
+    name: Test Cases
+    id: TC
+    file: SPEC-11-TC-Test-Cases.md
+    desc: >
+        The verifiable conditions and steps used to confirm that requirements are correctly
+        implemented, with mandatory defined inputs, mandatory expected outcomes, and optional pre-
+        and post-conditions.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:TC.TEST-CASE:*]]"
+    childs:
+        -   kind: TEST-CASE
+            desc: >
+                A single verifiable test case, named with a short (3-8 word) summary and defined by
+                its mandatory input and expected outcome plus its optional pre- and post-conditions.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[SPEC:TC.TEST-CASE:*]], [[SPEC:FR.REQUIREMENT:*]], [[SPEC:NR.REQUIREMENT:*]]"
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: VERIFIES
+                    desc: >
+                        Reference to the FUNCTIONAL-REQUIREMENTS or NON-FUNCTIONAL-REQUIREMENTS
+                        object the test case verifies.
+                    value: "[[SPEC:*.REQUIREMENT:*]]"
+                -   name: PRE-CONDITION
+                    desc: >
+                        The state or setup that must hold before the test is executed.
+                    optional: true
+                -   name: INPUT
+                    desc: >
+                        The mandatory, concrete input data or actions applied during the test.
+                -   name: EXPECTED
+                    desc: >
+                        The mandatory, concrete expected outcome or observable result that defines a
+                        passing test.
+                -   name: POST-CONDITION
+                    desc: >
+                        The state that must hold after the test completes.
+                    optional: true
+
+-   kind: SPEC
+    name: Interaction Concept
+    id: IC
+    file: SPEC-12-IC-Interaction-Concept.md
+    desc: >
+        The overarching idea of how users interact with the solution, describing the intended
+        workflows and interaction philosophy (e.g. auto-save behavior).
+    childs:
+        -   kind: PRINCIPLE
+            desc: >
+                A single interaction principle, named with a short (2-5 word) summary (e.g.
+                `Auto-Save`, `Optimistic Updates`, `Undo over Confirm`) and described in a concise
+                (1-3 sentence) paragraph by how it governs the user's experience across the
+                solution, plus a 1-sentence rationale ("why").
+            props:
+                -   name: CATEGORY
+                    desc: The aspect of interaction the principle governs.
+                    value: enum(Onboarding,Navigation,Input,Feedback,Workflow,Personalization,Awareness,Resilience,Privacy)
+
+-   kind: SPEC
+    name: Language Conventions
+    id: LC
+    file: SPEC-13-LC-Language-Conventions.md
+    desc: >
+        The terminology, naming, tone, and wording standards used consistently across the solution
+        and its content.
+    childs:
+        -   kind: CONVENTION
+            desc: >
+                A single language convention, named with a short (2-5 word) summary and described in
+                a concise (1-3 sentence) paragraph as the convention to be applied consistently
+                across the solution, optionally illustrated by a short, concrete example of the
+                convention in practice.
+            props:
+                -   name: CATEGORY
+                    desc: >
+                        The aspect of language the convention governs: `Terminology` (preferred and
+                        forbidden terms), `Naming` (naming patterns), `Tone` (voice and register),
+                        `Capitalization`, `Punctuation`, or `Formatting`.
+                    value: enum(Terminology,Naming,Tone,Capitalization,Punctuation,Formatting)
+
+-   kind: SPEC
+    name: Dialog Patterns
+    id: DP
+    file: SPEC-14-DP-Dialog-Patterns.md
+    desc: >
+        The reusable interaction structures governing how the system and user exchange information
+        across recurring conversational or UI flows (e.g. master-detail dialog).
+    childs:
+        -   kind: PATTERN
+            desc: >
+                A single reusable dialog pattern, named with a short (2-5 word) summary (e.g.
+                `Master-Detail`, `Wizard`, `Inline Edit`) and described in a concise (1-3 sentence)
+                paragraph by the interaction structure and how the system and user exchange
+                information within it, plus a 1-sentence rationale ("why") stating why this
+                particular structure is worth adopting -- the benefit it secures or the trade-off it
+                wins.
+            props:
+                -   name: CONTEXT
+                    desc: >
+                        The recurring situation or flow in which the pattern is applied.
+                -   name: PROBLEM
+                    desc: >
+                        The 1-sentence tension or difficulty the pattern resolves ("why is the
+                        pattern needed"), stated independently of its solution (which belongs to the
+                        description) and of its rationale (which states why this particular solution
+                        is worth adopting).
+
+-   kind: SPEC
+    name: Dialog Storyboard
+    id: DS
+    file: SPEC-15-DS-Dialog-Storyboard.md
+    desc: >
+        The sequenced visual or textual depiction of a specific dialog flow, illustrating how an
+        interaction unfolds screen by screen or turn by turn.
+    diagram:
+        type: grid
+        nodes: "[[SPEC:DS.STORYBOARD:*]]"
+    childs:
+        -   kind: STORYBOARD
+            desc: >
+                A single depicted dialog flow, named with a short (3-8 word) summary of the flow and
+                comprised of sequentially numbered frames.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[SPEC:DS.STORYBOARD:*]], [[SPEC:UC.USE-CASE:*]],
+                    [[SPEC:UC.USE-CASE:*.SCENARIO:*]], [[SPEC:DP.PATTERN:*]]"
+                qualified: true
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: USE-CASE
+                    desc: >
+                        Reference to the USE-CASES object the storyboard visualizes.
+                    value: "[[SPEC:UC.USE-CASE:*]]"
+                    optional: true
+                -   name: SCENARIO
+                    desc: >
+                        Reference to the USE-CASES scenario object the storyboard visualizes.
+                    value: "[[SPEC:UC.USE-CASE:*.SCENARIO:*]]"
+                    optional: true
+                -   name: PATTERN
+                    desc: >
+                        Reference to the DIALOG-PATTERNS object the storyboard instantiates.
+                    value: "[[SPEC:DP.PATTERN:*]]"
+                    optional: true
+            childs:
+                -   kind: FRAME
+                    desc: >
+                        A single frame of the storyboard, named with a short (2-5 word) label for
+                        the screen, turn, or state depicted and described in a concise (1-2
+                        sentence) paragraph by what the user sees and does at this frame of the
+                        interaction.
+
+-   kind: SPEC
+    name: Visual Design
+    id: VD
+    file: SPEC-16-VD-Visual-Design.md
+    desc: >
+        The aesthetic and layout aspects of the solution, defining colors, typography, spacing,
+        imagery, and overall look and feel.
+    childs:
+        -   kind: ELEMENT
+            desc: >
+                A single visual design element, named with a short (2-5 word) summary and described
+                in a concise (1-3 sentence) paragraph specifying the concrete values, tokens, or
+                rules that define it (e.g. palette, font family, scale), plus a 1-sentence rationale
+                ("why").
+            props:
+                -   name: CATEGORY
+                    desc: The aspects of visual design the element governs.
+                    value: tags(Color,Typography,Iconography,Imagery,Layout,Animation)
+
+-   kind: ARCH
+    name: Context View
+    id: CV
+    file: ARCH-01-CV-Context-View.md
+    desc: >
+        The relationships, dependencies, and interactions between the solution and its environment,
+        defining the system's scope, external entities, and boundaries.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:CV.ENTITY:*]]"
+        properties:
+            -   KIND
+            -   DIRECTION
+    childs:
+        -   kind: ENTITY
+            desc: >
+                A single external entity the solution interacts with, named with a short (2-5 word)
+                summary (e.g. `Payment Gateway`, `Identity Provider`, `End User`) and described in a
+                concise (1-3 sentence) paragraph by the relationship and dependency between the
+                solution and the entity, plus a 1-sentence rationale ("why") for the entity being
+                part of the system context.
+            props:
+                -   name: KIND
+                    desc: |
+                        The kind of the external entity, one of:
+                        -   `Person`:       A human actor interacting with the solution.
+                        -   `System`:       An external software system the solution integrates
+                                            with.
+                        -   `Service`:      A third-party or managed service the solution consumes.
+                        -   `Datastore`:    An external data repository the solution reads from or
+                                            writes to.
+                        -   `Device`:       A physical device or sensor the solution communicates
+                                            with.
+                        -   `Organization`: An external organizational party.
+                    value: enum(Person,System,Service,Datastore,Device,Organization)
+                -   name: DIRECTION
+                    desc: >
+                        The flow of interaction relative to the solution: `Inbound` (the entity
+                        drives the solution), `Outbound` (the solution drives the entity), or
+                        `Bidirectional` (both directions).
+                    value: enum(Inbound,Outbound,Bidirectional)
+                -   name: INTERFACE
+                    desc: >
+                        How the interaction happens (e.g. REST API, message queue, file exchange,
+                        web UI).
+                -   name: DATA
+                    desc: >
+                        The principal information exchanged across the boundary with this entity.
+
+-   kind: ARCH
+    name: Functionality View
+    id: FV
+    file: ARCH-02-FV-Functionality-View.md
+    desc: >
+        The functional components of the solution, their responsibilities, interfaces, and primary
+        interactions, describing *what* the system does at runtime.
+    diagram:
+        type: graph
+        nodes: "[[ARCH:FV.COMPONENT:*]]"
+        properties:
+            -   KIND
+    childs:
+        -   kind: COMPONENT
+            desc: >
+                A single functional component, named with a short (2-5 word) summary (e.g.
+                `Authentication Service`, `Order Processor`, `Notification Dispatcher`) and
+                described in a concise (1-3 sentence) paragraph by *what* it does and how it
+                collaborates with the components it depends on, plus a 1-sentence rationale ("why")
+                for the component's existence and boundary.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:FV.COMPONENT:*]]"
+                properties:
+                    -   KIND
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: KIND
+                    desc: |
+                        The kind of the functional component, one of:
+                        -   `Component`: Cohesive unit of functionality with a defined interface.
+                        -   `Service`:   Independently deployable provider of functionality.
+                        -   `Module`:    Logical grouping of related functionality within a
+                                         component.
+                        -   `Connector`: Mediator that conveys interactions between components
+                                         (e.g. bus, gateway).
+                        -   `Subsystem`: Larger composite grouping several components.
+                    value: enum(Component,Service,Module,Connector,Subsystem)
+                -   name: RESPONSIBILITY
+                    desc: >
+                        The 1-sentence statement of the single, primary responsibility the component
+                        owns.
+                -   name: INTERFACE
+                    desc: >
+                        How other components interact with this component (e.g. REST API, library
+                        API, message topic, CLI).
+                -   name: DEPENDS-ON
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW objects this component
+                        depends on at runtime.
+                    value: list([[ARCH:FV.COMPONENT:*]])
+                    optional: true
+
+-   kind: ARCH
+    name: Information View
+    id: IV
+    file: ARCH-03-IV-Information-View.md
+    desc: >
+        The way the solution stores, manages, manipulates, and distributes information, defining the
+        static data structure and dynamic information flow.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:IV.ASPECT:*]]"
+        properties:
+            -   CONCERN
+    childs:
+        -   kind: ASPECT
+            desc: >
+                A single information aspect, named with a short (2-5 word) summary (e.g. `Order
+                Persistence`, `Event Stream`, `Cache Coherency`) and described in a concise (1-3
+                sentence) paragraph by how the solution stores, manages, or distributes the
+                information and how its consistency is upheld, plus a 1-sentence rationale ("why")
+                for handling the information this way.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:IV.ASPECT:*]], [[SPEC:DM.ENTITY:*]], [[ARCH:FV.COMPONENT:*]]"
+                qualified: true
+                properties:
+                    -   CONCERN
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: CONCERN
+                    desc: >
+                        The information-handling concern the aspect addresses: `Persistence`,
+                        `Flow`, `Ownership`, `Consistency`, `Replication`, `Caching`, `Retention`,
+                        or `Migration`.
+                    value: enum(Persistence,Flow,Ownership,Consistency,Replication,Caching,Retention,Migration)
+                -   name: ENTITIES
+                    desc: >
+                        Comma-separated references to the DATA-MODEL entities the aspect governs.
+                    value: list([[SPEC:DM.ENTITY:*]])
+                    optional: true
+                -   name: OWNER
+                    desc: >
+                        Reference to the FUNCTIONALITY-VIEW object that owns this information.
+                    value: "[[ARCH:FV.COMPONENT:*]]"
+                    optional: true
+                -   name: LIFECYCLE
+                    desc: >
+                        How the information comes into being, changes, and is disposed of (e.g.
+                        `created on order, retained 7 years, then purged`).
+
+-   kind: ARCH
+    name: Concurrency View
+    id: CO
+    file: ARCH-04-CO-Concurrency-View.md
+    desc: >
+        The concurrency structure of the solution, mapping functional components to processes and
+        threads, and defining how they coordinate and communicate.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:CO.UNIT:*]]"
+        properties:
+            -   KIND
+    childs:
+        -   kind: UNIT
+            desc: >
+                A single concurrency unit, named with a short (2-5 word) summary (e.g. `Web Worker
+                Pool`, `Background Scheduler`, `Ingest Queue Consumer`) and described in a concise
+                (1-3 sentence) paragraph by how it executes and how it avoids or manages contention,
+                races, and deadlocks, plus a 1-sentence rationale ("why") for the chosen concurrency
+                structure.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:CO.UNIT:*]], [[ARCH:FV.COMPONENT:*]]"
+                qualified: true
+                properties:
+                    -   KIND
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: KIND
+                    desc: |
+                        The kind of the concurrency unit, one of:
+
+                        -   `Process`:   An independent OS process with its own address space.
+                        -   `Thread`:    A thread of execution within a process.
+                        -   `Pool`:      A managed group of interchangeable workers.
+                        -   `Queue`:     An asynchronous buffer decoupling producers and consumers.
+                        -   `EventLoop`: A single-threaded cooperative scheduler of tasks.
+                    value: enum(Process,Thread,Pool,Queue,EventLoop)
+                -   name: HOSTS
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW objects that run inside
+                        this concurrency unit.
+                    value: list([[ARCH:FV.COMPONENT:*]])
+                    optional: true
+                -   name: MULTIPLICITY
+                    desc: >
+                        How many instances of the unit run (e.g. `1`, `1 per CPU core`, `0..n
+                        auto-scaled`).
+                -   name: COORDINATION
+                    desc: >
+                        The mechanism by which the unit coordinates or communicates with other units
+                        (e.g. `shared queue`, `mutex`, `message passing`, `optimistic locking`).
+
+-   kind: ARCH
+    name: Development View
+    id: DV
+    file: ARCH-05-DV-Development-View.md
+    desc: >
+        The architecture supporting the software development process, defining the module
+        organization, build approach, and codeline conventions.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:DV.ASPECT:*]]"
+    childs:
+        -   kind: ASPECT
+            desc: >
+                A single development aspect, named with a short (2-5 word) summary (e.g. `Module
+                Layering`, `Build Pipeline`, `Branching Model`) and described in a concise (1-3
+                sentence) paragraph by the development convention or structure and the rule
+                developers must follow, plus a 1-sentence rationale ("why").
+            props:
+                -   name: CATEGORY
+                    desc: >
+                        The development concern the aspect governs: `Structure` (module/package
+                        organization), `Build` (compilation and packaging), `Dependency` (dependency
+                        management and layering rules), `Codeline` (branching, merging, versioning),
+                        `Standardization` (coding standards and conventions), or `Tooling`
+                        (development tools and automation).
+                    value: enum(Structure,Build,Dependency,Codeline,Standardization,Tooling)
+
+-   kind: ARCH
+    name: Deployment View
+    id: DP
+    file: ARCH-06-DP-Deployment-View.md
+    desc: >
+        The environment into which the solution is deployed, mapping software elements to the
+        runtime platform, hardware, and network topology.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:DP.NODE:*]]"
+        properties:
+            -   KIND
+            -   PLATFORM
+    childs:
+        -   kind: NODE
+            desc: >
+                A single deployment node, named with a short (2-5 word) summary (e.g. `Web Tier`,
+                `Database Cluster`, `Edge CDN`) and described in a concise (1-3 sentence) paragraph
+                by the node, its sizing, and its place in the deployment topology, plus a 1-sentence
+                rationale ("why") for the node's placement and platform choice.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:DP.NODE:*]], [[ARCH:FV.COMPONENT:*]]"
+                qualified: true
+                properties:
+                    -   KIND
+                    -   PLATFORM
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: KIND
+                    desc: |
+                        The kind of the deployment node, one of:
+
+                        -   `Server`:    A physical or virtual machine.
+                        -   `Container`: A containerized runtime (e.g. Docker, OCI).
+                        -   `Cluster`:   A managed group of nodes (e.g. Kubernetes cluster).
+                        -   `Function`:  A serverless / function-as-a-service runtime.
+                        -   `Device`:    An edge or client device.
+                        -   `Managed`:   A managed cloud service (e.g. managed database, queue).
+                    value: enum(Server,Container,Cluster,Function,Device,Managed)
+                -   name: PLATFORM
+                    desc: >
+                        The runtime platform of the node (e.g. `Linux x86-64`, `Kubernetes 1.30`,
+                        `AWS Lambda (Node.js)`).
+                -   name: HOSTS
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW objects deployed onto
+                        this node.
+                    value: list([[ARCH:FV.COMPONENT:*]])
+                    optional: true
+                -   name: NETWORK
+                    desc: >
+                        The network placement and connectivity of the node (e.g. `public subnet, TLS
+                        443`, `private VLAN`).
+
+-   kind: ARCH
+    name: Operations View
+    id: OV
+    file: ARCH-07-OV-Operations-View.md
+    desc: >
+        The way the solution is operated, administered, and supported in production, defining
+        installation, monitoring, and management concerns.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:OV.CONCERN:*]]"
+        properties:
+            -   CATEGORY
+    childs:
+        -   kind: CONCERN
+            desc: >
+                A single operational concern, named with a short (2-5 word) summary (e.g. `Rolling
+                Deployment`, `Metrics Collection`, `Backup and Restore`) and described in a concise
+                (1-3 sentence) paragraph by how it is handled in production and which procedures or
+                tools support it, plus a 1-sentence rationale ("why") for the operational approach.
+            props:
+                -   name: CATEGORY
+                    desc: >
+                        The category of the concern: `Installation`, `Configuration`,
+                        `Provisioning`, `Monitoring`, `Logging`, `Alerting`, `Backup`, `Recovery`,
+                        `Upgrade`, or `Support`.
+                    value: enum(Installation,Configuration,Provisioning,Monitoring,Logging,Alerting,Backup,Recovery,Upgrade,Support)
+                -   name: ELEMENT
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
+                        objects the concern applies to.
+                    value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
+                    optional: true
+
+-   kind: ARCH
+    name: Quality Perspectives
+    id: QP
+    file: ARCH-08-QP-Quality-Perspectives.md
+    desc: >
+        How the Non-Functional Requirements (NR) are addressed.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:QP.PERSPECTIVE:*]]"
+        properties:
+            -   QUALITY
+    childs:
+        -   kind: PERSPECTIVE
+            desc: >
+                A single quality perspective, named with a short (2-5 word) summary (e.g.
+                `Horizontal Scaling`, `Defense in Depth`, `Graceful Degradation`) and described in a
+                concise (1-3 sentence) paragraph by how the architecture satisfies the quality
+                attribute across the affected elements, plus a 1-sentence rationale ("why") for the
+                chosen tactic over alternatives.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:QP.PERSPECTIVE:*]], [[SPEC:NR.REQUIREMENT:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]]"
+                qualified: true
+                properties:
+                    -   QUALITY
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: QUALITY
+                    desc: >
+                        The quality attribute the perspective addresses, a solution-oriented
+                        refinement of the NON-FUNCTIONAL-REQUIREMENTS categories which intentionally
+                        differs from them.
+
+                        The NR categories follow the ISO/IEC 25010:2023 top-level characteristics
+                        (and include `Safety` and `Flexibility`), whereas the perspective qualities
+                        decompose some of these into the finer-grained, architecturally actionable
+                        attributes `Scalability`, `Availability`, `Privacy`, `Accessibility`, and
+                        `Portability`. The quality therefore need not match the category of the
+                        requirements it addresses.
+                    value: enum(Performance,Scalability,Reliability,Availability,Security,Privacy,Usability,Accessibility,Maintainability,Portability,Compatibility,Compliance)
+                -   name: ADDRESSES
+                    desc: >
+                        Comma-separated references to the NON-FUNCTIONAL-REQUIREMENTS objects the
+                        perspective addresses.
+                    value: list([[SPEC:NR.*]])
+                -   name: TACTIC
+                    desc: >
+                        The architectural tactic or strategy applied to achieve the quality (e.g.
+                        `stateless replication behind a load balancer`, `read-through cache`,
+                        `circuit breaker`).
+                -   name: AFFECTS
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
+                        objects the tactic affects.
+                    value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
+                    optional: true
+
+-   kind: ARCH
+    name: Decision Record
+    id: DR
+    file: ARCH-09-DR-Decision-Record.md
+    desc: >
+        The major decisions related to the architecture, each recording the forces at play, the
+        chosen response, and the reasoning that justifies it.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:DR.DECISION:*]]"
+        properties:
+            -   STATUS
+        config:
+            size-node-width-max: 440
+            grid-columns-max: 5
+    childs:
+        -   kind: DECISION
+            desc: |
+                A single architecture decision, named with a short summary of the decision, not
+                longer than 80 characters, and recorded as its context (`WHEN`), the decision
+                itself (`WHAT`), its rationale (`WHY`), and optional background (`NOTES`).
+
+                A decision *MUST* qualify on all of the following three tenets:
+
+                -   **Hard to Reverse**: the cost of changing it later is meaningful ("Oh my god,
+                    this would result in a dramatic refactoring!"). So, if a decision is easy to
+                    reverse, just skip it.
+
+                -   **Surprising without Context**: a future architect will look at the code and
+                    wonder ("Why on earth did they do it this way?"). So, if a decision is not
+                    surprising, nobody will wonder why.
+
+                -   **Result of a Real Trade-Off**: there were genuine alternatives and one was
+                    picked for specific reasons ("We deliberately chose this, because..."). So, if
+                    there was no real alternative, there's nothing to record beyond "we did the
+                    obvious thing."
+
+                The following typically qualify as a decision:
+
+                -   **Architectural shape.** "We're using a monorepo." "The write model is
+                    event-sourced, the read model is projected into PostgreSQL."
+
+                -   **Integration patterns between contexts.** "Ordering and Billing communicate
+                    via domain events, not synchronous HTTP."
+
+                -   **Technology choices that carry lock-in.** Database, message bus, auth
+                    provider, deployment target. Not every library - just the ones that would take
+                    a quarter to swap out.
+
+                -   **Boundary and scope decisions.** "Customer data is owned by the Customer
+                    context; other contexts reference it by ID only." The explicit no's are as
+                    valuable as the yes's.
+
+                -   **Deliberate deviations from the obvious path.** "We're using manual SQL
+                    instead of an ORM because X." Anything where a reasonable reader would assume
+                    the opposite. These stop the next engineer from "fixing" something that was
+                    deliberate.
+
+                -   **Constraints not visible in the code.** "We can't use AWS because of
+                    compliance requirements." "Response times must be under 200ms because of the
+                    partner API contract."
+
+                -   **Rejected alternatives when the rejection is non-obvious.** If you considered
+                    GraphQL and picked REST for subtle reasons, record it - otherwise someone will
+                    suggest GraphQL again in six months.
+
+                `WHEN`, `WHAT`, and `WHY` are each just a single paragraph of concise and brief
+                prose text, usually comprised of just 1 to 3 sentences. The value of a decision is
+                in recording *that* a decision was made and *why* - not in filling out sections of
+                a document.
+
+                For the relationship between context, decision, and rationale, good checks are:
+                the "litmus test" is that context = forces, decision = response to those forces,
+                rationale = why the decision answers the forces in the context. The decision
+                should feel like the natural, almost inevitable answer to the context - if a reader
+                is surprised by the decision, either the context is missing a force, or the
+                decision is under-justified. The rationale should make the decision feel earned,
+                not asserted - if you delete the rationale and the decision suddenly looks
+                arbitrary, the rationale was doing its job.
+            diagram:
+                type: hub
+                center: self
+                nodes: "[[ARCH:DR.DECISION:*]], [[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]]"
+                qualified: true
+                properties:
+                    -   STATUS
+                config:
+                    size-node-width-max: 440
+            props:
+                -   name: STATUS
+                    desc: >
+                        The status of the decision: `proposed`, `accepted`, `deprecated`, or
+                        `superseded`.
+                    value: enum(proposed,accepted,deprecated,superseded)
+                -   name: AFFECTS
+                    desc: >
+                        Comma-separated references to the FUNCTIONALITY-VIEW or DEPLOYMENT-VIEW
+                        objects the decision affects.
+                    value: list([[ARCH:FV.COMPONENT:*]], [[ARCH:DP.NODE:*]])
+                    optional: true
+                -   name: SUPERSEDED-BY
+                    desc: >
+                        Reference to the DECISION-RECORD object that supersedes this decision.
+                        Should be present if and only if `STATUS` is `superseded`.
+                    value: "[[ARCH:DR.DECISION:*]]"
+                    optional: true
+                -   name: WHEN
+                    desc: |
+                        The **Context** of the decision: it captures the situation that forces the
+                        decision - the "why are we even talking about this" part. It describes the
+                        situation as it is, before the decision is made. The following usually
+                        goes into it:
+
+                        -   the problem or need (what's broken, missing, or about to change that
+                            requires a decision);
+                        -   the forces at play (technical constraints, business requirements,
+                            deadlines, team skills, existing systems, regulatory/compliance
+                            pressures - often competing, and that tension is the whole point);
+                        -   relevant facts (current architecture, prior decisions, assumptions,
+                            what's known and what's uncertain); and
+                        -   scope/boundaries (what this decision is and isn't about).
+
+                        It is written neutrally and factually. It should not contain the decision
+                        itself, nor advocate for an option - a reader should be able to read it,
+                        pause, and arrive at the decision themselves because the forces make it
+                        (nearly) inevitable.
+                -   name: WHAT
+                    desc: |
+                        The **Decision** itself: it states what is actually going to be done - the
+                        chosen response to the forces laid out in the context. It is written in
+                        active, assertive voice, in the present or imperative tense, as a committed
+                        position rather than a discussion. The following usually goes into it:
+
+                        -   the choice itself (clearly and unambiguously); and
+                        -   the essence of how (enough of the approach to make the choice concrete
+                            - the mechanism, pattern, or technology - but not a full implementation
+                            specification).
+
+                        It is a declaration, not a deliberation, usually using the wording "We
+                        use..." or "We do...", active, definite, owning the choice. Avoid hedging
+                        ("we might", "we could consider") - the deliberation already happened, the
+                        decision records the verdict.
+                -   name: WHY
+                    desc: |
+                        The **Rationale** of the decision: it is the reasoning that justifies the
+                        decision - the bridge that explains why this choice, given those forces. It
+                        answers "Of all the things we could have done, why was this the right
+                        one?". Where the context states the forces and the decision states the
+                        choice, the rationale is the logical connective tissue between them - it
+                        shows that the decision actually follows from the context. The following
+                        usually goes into it:
+
+                        -   the deciding factors (which forces from the context carried the most
+                            weight, and how the chosen option satisfies them best);
+                        -   the trade-off reasoning (what was optimized for and what was knowingly
+                            sacrificed - naming the trade-off is the heart of rationale);
+                        -   why the alternatives lost (the comparative argument: "option B failed
+                            on X, option C cost too much on Y"); and
+                        -   assumptions and evidence (benchmarks, prior experience, constraints, or
+                            principles the reasoning rests on).
+                -   name: NOTES
+                    desc: |
+                        The **Background** of the decision: it is *OPTIONAL* and can be omitted
+                        when it does not add genuine value - most decisions won't need it. The
+                        following usually goes into it:
+
+                        -   information about the decision *process* (e.g. a weighted decision
+                            matrix of considered alternatives);
+                        -   consequences of the decision (but only when non-obvious downstream
+                            effects need to be called out); and
+                        -   links to strongly related decisions.
+                    optional: true
+
+-   kind: ARCH
+    name: Technology Stack
+    id: TS
+    file: ARCH-10-TS-Technology-Stack.md
+    desc: >
+        The concrete technology products the solution is built upon, organized by tier and lifecycle
+        phase, recording for each component its chosen product, its purpose, and the alternatives
+        that were considered but not chosen.
+    diagram:
+        type: grid
+        nodes: "[[ARCH:TS.TIER:*]]"
+    childs:
+        -   kind: TIER
+            name: (?:Client|Server|Middleware|Database)
+            desc: |
+                The architectural tier grouping the technology components belonging to it, one of:
+
+                -   `Client`:     Runs on the client side (e.g. browser, desktop, mobile).
+                -   `Server`:     Runs on the server side (e.g. backend, application, API).
+                -   `Middleware`: Runs between client and server (e.g. message broker, gateway).
+                -   `Database`:   Runs as the data store (e.g. relational or document database).
+            format:
+                maxTableColumns: 5
+            diagram:
+                type: hub
+                center: self
+                hierarchy: true
+                properties:
+                    -   PRODUCT
+                config:
+                    size-node-width-max: 440
+            childs:
+                -   kind: COMPONENT
+                    desc: >
+                        A single technology component, named with a short (2-5 word) summary (e.g.
+                        `UI Framework`, `Web Server`, `Relational Database`) and described in a
+                        concise (1-3 sentence) paragraph by how the product is used within the
+                        solution and how it fits into the overall technology stack, plus a
+                        1-sentence rationale ("why") for choosing this product over the
+                        alternatives.
+                    props:
+                        -   name: PRODUCT
+                            desc: >
+                                The concrete product, library, or framework chosen for this
+                                component (e.g. `VueJS`, `Node.js`, `PostgreSQL`).
+                        -   name: ALTERNATIVES
+                            desc: >
+                                Comma-separated names of products which would also fit this
+                                component but were not chosen (e.g. `React, Svelte`).
+                            optional: true
+                        -   name: COVERAGE
+                            desc: |
+                                A comma-separated list of either one or more of the *Client
+                                Aspects* or one or more of the *Server Aspects* (or their
+                                sub-aspects) defined below. The general goal is to achieve a
+                                maximum coverage of all aspects per `TIER` with the minimum
+                                total number of `PRODUCT`s.
+
+                                The known *Client Aspects* which usually have to be covered (at
+                                least for clients in a Rich-Client architecture):
+
+                                -   **Interface Theme**:
+                                    Style Reset, Shape, Color, Gradient, Shadow, Font, Icon.
+
+                                -   **Interface Widgets**:
+                                    Icon, Label, Text Paragraph, Image, Form, Text-Field,
+                                    Text-Area, Date Picker, Toggle, Radio Button, Checkbox,
+                                    Select List, Slider, Progress Bar, Hyperlink, Popup Menu,
+                                    Dropdown Menu, Toolbar, Tooltip, Tab, Pill, Breadcrumb,
+                                    Pagination, Badge, Alert, Panel, Modal, Table, Scrollbar,
+                                    Carousel.
+
+                                -   **Interface Layouting**:
+                                    Responsive Design, Media Query, Frame, Grid, Padding, Border,
+                                    Margin, Alignment, Force, Magnetism.
+
+                                -   **Interface Effects**:
+                                    Transition, Transformation, Keyframes, Easing Function, Sound
+                                    Effect, Physics.
+
+                                -   **Interface Interactions**:
+                                    Mouse, Keyboard, Touchscreen, Gesture, Clipboard, Drag & Drop.
+
+                                -   **Interface States**:
+                                    Rendered, Enabled, Visible, Focused, Warning, Error, Floating.
+
+                                -   **Interface Mask**:
+                                    Markup Loading, Markup Generation, Virtual DOM, Text, Bitmaps,
+                                    Vectors, 2D/3D Canvas, Accessibility.
+
+                                -   **Interface Internationalization**:
+                                    Text Internationalization (I18N).
+
+                                -   **Data Conversion**:
+                                    Value Formatting, Value Parsing, Localization (L10N).
+
+                                -   **Data Binding**:
+                                    Reactive, Observer, Unidirectional, Bidirectional, Incremental.
+
+                                -   **Presentation Model**:
+                                    Parameter Value, Command Value, State Value, Data Value, Event
+                                    Value, Value Validation, Presentation Logic.
+
+                                -   **Dialog Navigation**:
+                                    Deep Linking, Routing, Dialog Flow.
+
+                                -   **Dialog Automation**:
+                                    Dialog Macros, Click-Through, Smoke Testing.
+
+                                -   **Dialog Communication**:
+                                    Service, Event, Model, Socket, Hooks.
+
+                                -   **Dialog Life-Cycle**:
+                                    Component States, Component State Transitions.
+
+                                -   **Dialog Structure**:
+                                    Component, Model/View/Controller Roles, Hierarchical
+                                    Composition.
+
+                                -   **State Persistence**:
+                                    Local Storage, Cookies, Caching.
+
+                                -   **Business Model**:
+                                    Entity, Field, Relationship, Universally Unique Identifiers
+                                    (UUID).
+
+                                -   **Use-Case Authorization**:
+                                    User Experience, Dialog Restriction, User, Group, Role,
+                                    Use-Case, Data, Access.
+
+                                -   **Client Networking**:
+                                    Request/Response, Synchronization, Push, Pull, Pulled-Push,
+                                    REST, GraphQL, Authentication, Session.
+
+                                -   **Environment Detection**:
+                                    Runtime Detection, Feature Detection.
+
+                                The known *Server Aspects* which usually have to be covered (at
+                                least for servers, sometimes called Thin-Servers, in a Rich-Client
+                                architecture):
+
+                                -   **Environment Detection**:
+                                    Detect the run-time environment, like underlying operating
+                                    system, execution platform, network topology, feature toggles,
+                                    etc.
+
+                                -   **Argument Parsing**:
+                                    Parse options and arguments of the Command-Line Interface
+                                    (CLI) to bootstrap application parameters.
+
+                                -   **Configuration Parsing**:
+                                    Load and parse directives from a configuration file to
+                                    bootstrap application parameters.
+
+                                -   **Process Daemonizing**:
+                                    Detach from the startup terminal and host process in order to
+                                    run fully independently.
+
+                                -   **Process Management**:
+                                    (Pre-)fork child processes and/or threads of execution and
+                                    monitor and control them during the life-cycle of the
+                                    application.
+
+                                -   **Component Management**:
+                                    Structure the code into components, instantiate them at
+                                    run-time and manage them in a stateful component life-cycle.
+
+                                -   **Component Communication**:
+                                    Provide inter-component communication mechanisms like events,
+                                    hooks, registry, etc.
+
+                                -   **Server Networking**:
+                                    Listen to network sockets, accept connections and manage
+                                    request/response and message communication.
+
+                                -   **Peer Information**:
+                                    Determine unique identification and add-on information about
+                                    the client peer.
+
+                                -   **Session Handling**:
+                                    Manage secured per-connection sessions to keep state between
+                                    communication requests and/or client sessions.
+
+                                -   **User Authentication**:
+                                    Determine and validate the unique identity of the user
+                                    communicating over the current network connection.
+
+                                -   **Request Validation**:
+                                    Validate the syntactical and semantical compliance of the
+                                    requests and sanitize the requests.
+
+                                -   **Request Processing**:
+                                    Process the request by dispatching execution according to the
+                                    provided request and determined context information.
+
+                                -   **Role Authorization**:
+                                    Determine whether the role of the current user is allowed to
+                                    execute the current request.
+
+                                -   **Client Networking**:
+                                    Provide mechanisms to connect to peers over the network and
+                                    perform request/response and/or publish/subscribe
+                                    communication.
+
+                                -   **Task Scheduling**:
+                                    Schedule and execute recurring tasks independent of regular
+                                    I/O operations.
+
+                                -   **Execution Tracing**:
+                                    Provide mechanisms for tracing the execution by logging event
+                                    and measurement information at certain points of interest.
+
+                                -   **Database Access**:
+                                    Map in-memory domain entities onto a data-store-dependent
+                                    persistent data structure.
+
+                                -   **Database Connectivity**:
+                                    Locally or remotely connect the database access layer to the
+                                    underlying data store.
+
+                                -   **Database Schema**:
+                                    Create, update or downgrade the data schema inside the
+                                    underlying data store.
+
+                                -   **Database Bootstrapping**:
+                                    Create, update or downgrade both mandatory bootstrapping and
+                                    optional domain-specific data inside the underlying data
+                                    store.
+                            optional: true
+                        -   name: WHEN
+                            desc: |
+                                The lifecycle phase in which the component is relevant, one of:
+
+                                -   `Build-Time`: Used during development, compilation, or
+                                                  packaging.
+                                -   `Run-Time`:   Used while the solution executes in production.
+                            value: enum(Build-Time,Run-Time)
+                            optional: true
+