Skip to content
LQMS
8. Crosscutting Concepts
Initializing search
nburri/lqms
LQMS
nburri/lqms
Home
Evaluate LQMS
Evaluate LQMS
LQMS Known Limits
LQMS Security Posture
Architecture
Architecture
1. Introduction and Goals
2. Architecture Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Runtime View
7. Deployment View
8. Crosscutting Concepts
8. Crosscutting Concepts
Table of contents
8.1 Domain Model
Entities
Human-readable document IDs
Provenance
Content record (tree record + projection)
8.2 Multi-Mandator Data Separation
8.3 Document Life Cycles
8.4 Security & Access Control
8.5 Persistence
8.6 Internationalization
8.7 Search
8.8 Error Handling, Logging, Audit
8.9 Data Protection & Retention
8.10 Derived state & parity contracts
8.11 Trace items & the traceability web
9. Architecture Decisions
10. Quality Requirements
11. Risks and Technical Debt
12. Glossary
The arrival bundle format
Decisions (ADRs)
Decisions (ADRs)
ADR-0001: Content-Addressed Document Storage with PostgreSQL as Source of Truth
ADR-0002: Single Instance with Scope Hierarchy and Copy-on-Derive
ADR-0003: Fixed Life Cycle States with Configurable Review Processes
ADR-0004: Global Catalogs for Roles and Document Types with Per-Scope Activation
ADR-0005: Modular Monolith
ADR-0006: Three-Layer Search with In-Database Index and Pluggable LLM
ADR-0007: Angular Frontend with Server-Side-Only Enforcement
ADR-0008: Flyway Migrations and jOOQ Codegen from the Migrated Schema
ADR-0009: RLS Enforcement via a Session-Scoped Authorized Scope Set
ADR-0010: Self-Managed QMS via an Internal Mandator
ADR-0011: Authentication via OIDC SSO with Server-Side (BFF) Sessions
ADR-0012: Permission-Based Authorization and System Bootstrap
ADR-0013: User Identity Lifecycle
ADR-0014: Electronic Signatures (Part 11 / Annex 11-Capable)
ADR-0015: Document Effectivity, Periodic Review & Validity
ADR-0016: Data Retention, Disposal & Privacy (FADP / GDPR)
ADR-0017: Multi-Part Version Content
ADR-0018: Non-Functional Targets (Capacity, Availability, Security)
ADR-0019: Notifications & Tasks
ADR-0020: Internationalization (Content Language, Time Zones, Formatting)
ADR-0021: General Typed Document Relationships
ADR-0022: Read-Acknowledgement & Questionnaires
ADR-0023: Migration / Import — Current Released State
ADR-0024: Draft / In-Review Cancellation
ADR-0025: Disposal & Erasure Mechanics (Storage, Index, Backups)
ADR-0026: RLS Runtime Safety — Connection-Pool Scope Isolation
ADR-0027: RLS Boundary — Content-Plane vs Control-Plane
ADR-0028: Stateless Encrypted Token-State Cookie (no server-side session store)
ADR-0029: Document Content Model — Draft-Freeze, Content-Table RLS, Append-Only Audit
ADR-0030: Review & Life-Cycle Realization Model
ADR-0031: Released-base readability enforcement & copy-on-derive mechanics
ADR-0032: Frontend realization — Quinoa, Angular Material, i18n & E2E
ADR-0033: CSRF control for the BFF session — SameSite + JSON content-type
ADR-0034: Notification realization — in-process domain events + system-context fan-out
ADR-0035: Fan-out contract as shipped — gate semantics, count disclosure, audit protocol
ADR-0036: Repository layer — services carry rules, repositories carry jOOQ
ADR-0037: Task scheduler — in-process tick, advisory-lock election, SQL sweep
ADR-0038: Periodic-review realization — derived due date, policy-gated confirmation
ADR-0039: Sweep & periodic-review contract as shipped — grants, guards, addressing
ADR-0040: Disposal-due surfacing — closure-anchored retention, scope-level legal hold
ADR-0041: Email channel & notification i18n — notification-as-outbox, structured messages
ADR-0042: Disposal execution — document tombstoning, single-actor hard-gated destruction
ADR-0043: Disposal blob deletion is post-commit, GC-backstopped
ADR-0044: Search FTS baseline — event-indexed, RLS-scoped search_index
ADR-0045: Image Attachments as Content Parts (Rich-Content Slice R2)
ADR-0046: Four-Eyes — Submitter Excluded from Approval
ADR-0047: Four-Eyes — Submitter-Only Exclusion
ADR-0048: Document Organization — Folder Tree per Scope
ADR-0049: Content Model Round 2 — Type Categories, Template Instantiation, Trace Relations, Completeness Rules
ADR-0050: Live Frontend — SSE State Push, CodeMirror 6, Draft Presence
ADR-0051: In-Text Document Links (doc: Scheme)
ADR-0052: Addressees & Read-Acknowledgement (REQ-TRN Realization)
ADR-0053: Addressees Per Document + Process Owner (amends ADR-0052 K-1)
ADR-0054: Process Owner Is a Role (amends ADR-0053 P-3)
ADR-0055: WYSIWYG Editing Mode over Markdown (editor step R4)
ADR-0056: Visual-Editor Chrome via Milkdown Crepe (gated adoption)
ADR-0057: Content Record Is the ProseMirror Document Tree; Markdown Becomes a Derived Projection
ADR-0058: PM_DOC Is the Only Content Format (pre-production cut; amends ADR-0057 §5)
ADR-0059: Editor Engine Switches to TipTap (spike-gated; supersedes the Milkdown/Crepe choice)
ADR-0060: Backup & Restore — Scripted Ordered Backup with Automated Restore Rehearsal
ADR-0061: CSV — Generated Validation Package per Release
ADR-0062: SBOM — CycloneDX over the Production Layers, Validated Against the Artifact
ADR-0063: User Identity Binds on Subject Only (Issuer Becomes Provenance)
ADR-0064: Per-Document Workflow Role Bindings (Author / Reviewer / Releaser), Enforced
ADR-0065: Diagrams — Excalidraw as the Manual Layer, Mermaid Stays for Text-First/UML
ADR-0066: WITHDRAW — the Author Side May Reclaim a Version from Review
ADR-0067: Review Comments — Anchored, Immutable, Resolvable
ADR-0068: Confluence/Jira QMS Import — Staged, Read-Only, Repeatable
ADR-0069: Arbitrary File Attachments — Download-Only Confinement
ADR-0070: Training Questionnaires — Versioned, Auto-Scored, Release-Gated
ADR-0071: Training Plans — Document Obligations + External Trainings & Certifications
ADR-0072: Diagrams — Self-Hosted draw.io Replaces Excalidraw
ADR-0073: Per-Scope QMS Configuration Surface
ADR-0074: PDF Export of Released Documents — Server-Side via Apache FOP over the Canonical Projection
ADR-0075: Source History Import — Continuity Without Forged Audit
ADR-0076: Periodic-review status visibility (completing MVP gap #2)
ADR-0077: Requirement Items — Keyed Blocks Inside Controlled Documents
ADR-0078: Generalized Trace Items (Traceability Model — Stage A)
ADR-0079: Risk & Risk-Control Items (Traceability Model — Stage B)
ADR-0080: Traceability Workspace — Hub, Sub-Pages, and Role-Gated Views
ADR-0081: Draft-Only Trace-Structure Changes, Server-Enforced
ADR-0082: Table-Shaped Risk Authoring over Risk Blocks
ADR-0083: The TD Dossier — a Versioned, Cross-Scope, Regulatory-Structured Deliverable
ADR-0084: Validation & Regulatory Axes (Traceability Model — Stage C)
ADR-0085: Relation-Layer Consolidation — One Trace Vocabulary, One Surface
ADR-0086: Requirement Traceability Chains — End-to-End Path View + Flat Path Export
ADR-0087: The Scope Traceability Report — One Derived Overview Artifact, Never a Controlled Document
ADR-0088: Verification Evidence Classes — Planned vs. Verified, Derived at the Read Layer
ADR-0089: Recurring Obligations — Periodic Tasks With Record Evidence, Not Calendar Series
ADR-0090: Release & Versioning Policy — Deliberate Releases, One Auditor-Facing Number
ADR-0091: Release Modes — Single-Person Record Release With a Structural Four-Eyes Floor
ADR-0092: Orphan-Blob Garbage Collection With a Quarantine Bin
ADR-0093: One Scope Context — the Toolbar Switcher Is the Only Scope Selector
ADR-0094: Calendar-Anchored Obligation Schedules (Clamped, Never Too Late)
ADR-0095: Key-Rule Governance — Free Until First Use, Then Frozen
ADR-0096: Transition Permissions — Always Visible, Deny Unless Granted
ADR-0097: A Governed Provisioning Surface — MANAGE_SCOPES
ADR-0098: Org Chart × Role System — Marriage at the Evidence Level, Never in Authorization
ADR-0099: The User Manual is an In-App Topic Reference, Not a Document
ADR-0100: LQMS Is the Living Quality Management System
ADR-0101: The Executable Validation Journey (PQ Evidence That Cannot Drift)
ADR-0102: Typed Template Variables (text | date | number — and Deliberately No Enum)
ADR-0103: npm audit Joins the Verification Gate as a Second Standing Input
ADR-0104: The Issued Dossier Is a Persisted Artifact of Record — and Clones to a New Draft
ADR-0105: Navigation Information Architecture — Group by Moment-of-Use
ADR-0106: The Client Reflection Follows Assignments, Not Only Content Reach
ADR-0107: The Audit Append Gate Follows Assignment Reach, Not Content Reach
ADR-0108: Mandator Membership — Invite-Accept, with Pre-Assigned Responsibilities
ADR-0109: Organization Founding Is Its Own Process
ADR-0110: The Audit Trail Is Not a Read Model
ADR-0111: The Imported-Person Model, and Project Portability's First Doctrines
ADR-0112: The Element-Kind Catalog — Semantics in the Model, Not Only in the Code
ADR-0113: Project Arrival Import — Records Arrive as They Are, People Arrive as They Were
ADR-0114: The Operating Model Arrives — Roles as Functions, Names as Words, People as This Instance's Decision
ADR-0115: Collaborative Draft Editing — Two Carets, One Truth, Honest Credit
ADR-0116: The System Maintenance Surface — the App Backs Itself Up, the Host Keeps One Dumb Job
ADR-0117: Role Documentation — a Link, a Finding, Per-Source Recognizers; Substitution Rejected
ADR-0118: The Offline QMS Copy — the Repo Carries the Audit Pack, Not a Second Renderer
ADR-0119: Module-Internal Package Structure — Capabilities First, Layers Second, the Root Is the Surface
ADR-0120: The Shared Kernel — the Domain-Exception Vocabulary Leaves the Authorization Module
ADR-0121: The Project Administrator Role — Per-Scope Administration With Read Access, Seeded in the Base Catalog
ADR-0122: Organization-Level Administration — the Cascade Stays, Becomes Visible, and Founds Projects
ADR-0123: Draft Save-Points — Every Save Restorable, Kept for the Life of the Version
ADR-0124: The Birth Path Completes Without Borrowing Content Clothes
ADR-0125: The Export Twin — Export Emits an Arrival Bundle
ADR-0126: Project Dissolution — the Un-Birth of an Unused Scope
ADR-0127: The Base-QMS Layers — One Library, Derived Adaptations, Local Records
ADR-0128: The GLOBAL Cascade Carries Administration, Never Content
ADR-0129: Role Identity from a GLOBAL Assignment Acts in GLOBAL Alone
ADR-0130: Break-Glass — the Project Administrator's Escalation Is a First-Class, Witnessed, Self-Expiring Act
ADR-0131: Role Substitution as Declared Adoption Edges — Emergency Cover Is Governed, Own-Name, Timed Staffing
ADR-0132: Dual-Hat Reviewer Satisfaction Is a Declared Policy Choice — the Strict Floor Stays the Default
ADR-NNNN:
</span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" > <div class="md-nav__link md-nav__container"> <a href="../../requirements/" class="md-nav__link "> <span class="md-ellipsis"> Requirements </span> </a> <label class="md-nav__link " for="__nav_5" id="__nav_5_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_5"> <span class="md-nav__icon md-icon"></span> Requirements </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../requirements/stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_api_ui/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_audit_reporting/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_catalogs/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Catalogs, Roles & Users </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_data_protection/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Data Protection, Retention & Disposal </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_documents/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Documents, Versions & Storage </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_dossiers/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Technical Documentation Dossiers </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_effectivity/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Effectivity, Periodic Review & Validity </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_gspr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Regulatory Conformity (GSPR / Essential Principles) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Life Cycle & Reviews </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_memberships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Mandator Membership & Invitations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_risk/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Risk Management (ISO 14971 Hazards & Controls) </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_sbom/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Software Bill of Materials & Supply-Chain Assurance </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_separation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Scopes, Mandators & Separation </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_training/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Read-Acknowledgement & Questionnaires </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_users/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: User Identity & Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../requirements/req_validation/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Design Validation & the Validation Traceability Axis </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" > <div class="md-nav__link md-nav__container"> <a href="../../process/" class="md-nav__link "> <span class="md-ellipsis"> Process (IEC 62304) </span> </a> <label class="md-nav__link " for="__nav_6" id="__nav_6_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_6"> <span class="md-nav__icon md-icon"></span> Process (IEC 62304) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../process/configuration_management_plan/" class="md-nav__link"> <span class="md-ellipsis"> Configuration Management Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/problem_resolution/" class="md-nav__link"> <span class="md-ellipsis"> Problem Resolution Process </span> </a> </li> <li class="md-nav__item"> <a href="../../process/risk_management/" class="md-nav__link"> <span class="md-ellipsis"> Risk Management </span> </a> </li> <li class="md-nav__item"> <a href="../../process/software_development_plan/" class="md-nav__link"> <span class="md-ellipsis"> Software Development Plan </span> </a> </li> <li class="md-nav__item"> <a href="../../process/verification_plan/" class="md-nav__link"> <span class="md-ellipsis"> Verification Plan </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" > <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0"> <span class="md-ellipsis"> Operations </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_7"> <span class="md-nav__icon md-icon"></span> Operations </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../operations/genesis-installation/" class="md-nav__link"> <span class="md-ellipsis"> Genesis: Birthing an LQMS Installation with a Base Library </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Deployment Guide </span> </a> </li> <li class="md-nav__item"> <a href="../../operations/server-deployment/" class="md-nav__link"> <span class="md-ellipsis"> LQMS Server Deployment (single Linux host, public HTTPS) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" > <div class="md-nav__link md-nav__container"> <a href="../../traceability/" class="md-nav__link "> <span class="md-ellipsis"> Traceability </span> </a> <label class="md-nav__link " for="__nav_8" id="__nav_8_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_8"> <span class="md-nav__icon md-icon"></span> Traceability </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../traceability/matrix/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Traceability Matrix </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" > <div class="md-nav__link md-nav__container"> <a href="../../validation/" class="md-nav__link "> <span class="md-ellipsis"> Validation (tool lane) </span> </a> <label class="md-nav__link " for="__nav_9" id="__nav_9_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_9"> <span class="md-nav__icon md-icon"></span> Validation (tool lane) </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../validation/templates/ai-authorship-posture/" class="md-nav__link"> <span class="md-ellipsis"> AI-Authorship Posture — How LQMS Is Built, and Why the Validation Evidence Does Not Rest on It (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/intended-use/" class="md-nav__link"> <span class="md-ellipsis"> Intended-Use Specification — LQMS as a QMS / Document-Control Tool (TEMPLATE) </span> </a> </li> <li class="md-nav__item"> <a href="../../validation/templates/tool-risk-assessment/" class="md-nav__link"> <span class="md-ellipsis"> Tool-Risk Assessment — LQMS as a QMS Tool (TEMPLATE) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" > <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0"> <span class="md-ellipsis"> Regulatory </span> <span class="md-nav__icon md-icon"></span> </label> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_10"> <span class="md-nav__icon md-icon"></span> Regulatory </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../regulatory/mdr-annex-i-skeleton/" class="md-nav__link"> <span class="md-ellipsis"> MDR Annex I — GSPR authoring skeleton (paraphrased) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" > <div class="md-nav__link md-nav__container"> <a href="../../user-guide/" class="md-nav__link "> <span class="md-ellipsis"> User guide </span> </a> <label class="md-nav__link " for="__nav_11" id="__nav_11_label" tabindex="0"> <span class="md-nav__icon md-icon"></span> </label> </div> <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false"> <label class="md-nav__title" for="__nav_11"> <span class="md-nav__icon md-icon"></span> User guide </label> <ul class="md-nav__list" data-md-scrollfix> <li class="md-nav__item"> <a href="../../user-guide/tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/project-context/" class="md-nav__link"> <span class="md-ellipsis"> The Project Context & App Version </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/activity-trail/" class="md-nav__link"> <span class="md-ellipsis"> Who did what, when — reading a project's activity </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/admin-scopes/" class="md-nav__link"> <span class="md-ellipsis"> Renaming a project, and what can never change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/authority-view/" class="md-nav__link"> <span class="md-ellipsis"> Who holds each function here, and what may it do </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/break-glass/" class="md-nav__link"> <span class="md-ellipsis"> The permission I need is held by a role I do not hold — what now? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/coverage-and-chains/" class="md-nav__link"> <span class="md-ellipsis"> Coverage or chains? — which requirement view answers your question </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/credentials/" class="md-nav__link"> <span class="md-ellipsis"> Your password: changing it, resetting it — and why LQMS never sees it </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/emergency-cover/" class="md-nav__link"> <span class="md-ellipsis"> Who may cover for whom here — declaring emergency cover, and reading where the glass was broken </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/key-rules/" class="md-nav__link"> <span class="md-ellipsis"> Special elements: what a project declares, and when its names freeze </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/memberships/" class="md-nav__link"> <span class="md-ellipsis"> Belonging to an organization: invitations, acceptance, and what they change </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/provisioning-birth-path/" class="md-nav__link"> <span class="md-ellipsis"> How a new organization and project are born </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/review-policies/" class="md-nav__link"> <span class="md-ellipsis"> What a review policy controls, and what an empty grant means </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/setup-wizard-lanes/" class="md-nav__link"> <span class="md-ellipsis"> The setup wizard: the lanes, and what it writes </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/staffing-and-assignments/" class="md-nav__link"> <span class="md-ellipsis"> Staffing people into roles, and the accountable holder </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/topics/technical-dossier/" class="md-nav__link"> <span class="md-ellipsis"> How do I assemble a technical dossier? </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-items/" class="md-nav__link"> <span class="md-ellipsis"> Trace Items — Requirements, Risks & Risk Controls </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/trace-links/" class="md-nav__link"> <span class="md-ellipsis"> Trace Links & the Suspect Cycle </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../../user-guide/training/" class="md-nav__link"> <span class="md-ellipsis"> Training & Acknowledgements </span> </a> </li> </ul> </nav> </li> </ul> </nav> </div> </div> </div> <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" > <div class="md-sidebar__scrollwrap"> <div class="md-sidebar__inner"> <nav class="md-nav md-nav--secondary" aria-label="Table of contents"> <label class="md-nav__title" for="__toc"> <span class="md-nav__icon md-icon"></span> Table of contents </label> <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix> <li class="md-nav__item"> <a href="#81-domain-model" class="md-nav__link"> <span class="md-ellipsis"> 8.1 Domain Model </span> </a> <nav class="md-nav" aria-label="8.1 Domain Model"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#entities" class="md-nav__link"> <span class="md-ellipsis"> Entities </span> </a> </li> <li class="md-nav__item"> <a href="#human-readable-document-ids" class="md-nav__link"> <span class="md-ellipsis"> Human-readable document IDs </span> </a> </li> <li class="md-nav__item"> <a href="#provenance" class="md-nav__link"> <span class="md-ellipsis"> Provenance </span> </a> </li> <li class="md-nav__item"> <a href="#content-record-tree-record--projection" class="md-nav__link"> <span class="md-ellipsis"> Content record (tree record + projection) </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#82-multi-mandator-data-separation" class="md-nav__link"> <span class="md-ellipsis"> 8.2 Multi-Mandator Data Separation </span> </a> </li> <li class="md-nav__item"> <a href="#83-document-life-cycles" class="md-nav__link"> <span class="md-ellipsis"> 8.3 Document Life Cycles </span> </a> </li> <li class="md-nav__item"> <a href="#84-security--access-control" class="md-nav__link"> <span class="md-ellipsis"> 8.4 Security & Access Control </span> </a> </li> <li class="md-nav__item"> <a href="#85-persistence" class="md-nav__link"> <span class="md-ellipsis"> 8.5 Persistence </span> </a> </li> <li class="md-nav__item"> <a href="#86-internationalization" class="md-nav__link"> <span class="md-ellipsis"> 8.6 Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="#87-search" class="md-nav__link"> <span class="md-ellipsis"> 8.7 Search </span> </a> </li> <li class="md-nav__item"> <a href="#88-error-handling-logging-audit" class="md-nav__link"> <span class="md-ellipsis"> 8.8 Error Handling, Logging, Audit </span> </a> </li> <li class="md-nav__item"> <a href="#89-data-protection--retention" class="md-nav__link"> <span class="md-ellipsis"> 8.9 Data Protection & Retention </span> </a> </li> <li class="md-nav__item"> <a href="#810-derived-state--parity-contracts" class="md-nav__link"> <span class="md-ellipsis"> 8.10 Derived state & parity contracts </span> </a> </li> <li class="md-nav__item"> <a href="#811-trace-items--the-traceability-web" class="md-nav__link"> <span class="md-ellipsis"> 8.11 Trace items & the traceability web </span> </a> </li> </ul> </nav> </div> </div> </div> <div class="md-content" data-md-component="content"> <article class="md-content__inner md-typeset"> <a href="https://github.com/nburri/lqms/edit/main/docs/architecture/08_crosscutting_concepts.md" title="Edit this page" class="md-content__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M10 20H6V4h7v5h5v3.1l2-2V8l-6-6H6c-1.1 0-2 .9-2 2v16c0 1.1.9 2 2 2h4zm10.2-7c.1 0 .3.1.4.2l1.3 1.3c.2.2.2.6 0 .8l-1 1-2.1-2.1 1-1c.1-.1.2-.2.4-.2m0 3.9L14.1 23H12v-2.1l6.1-6.1z"/></svg> </a> <h1 id="8-crosscutting-concepts">8. Crosscutting Concepts<a class="headerlink" href="#8-crosscutting-concepts" title="Permanent link">¶</a></h1> <h2 id="81-domain-model">8.1 Domain Model<a class="headerlink" href="#81-domain-model" title="Permanent link">¶</a></h2> <pre class="mermaid"><code>erDiagram MANDATOR ||--o{ SCOPE : "owns (null for global)" SCOPE ||--o{ DOCUMENT : contains SCOPE ||--o{ ROLE_ACTIVATION : activates SCOPE ||--o{ TYPE_ACTIVATION : activates ROLE ||--o{ ROLE_ACTIVATION : "from catalog" DOCUMENT_TYPE ||--o{ TYPE_ACTIVATION : "from catalog" ROLE_ACTIVATION ||--o{ ROLE_ASSIGNMENT : staffs USER ||--o{ ROLE_ASSIGNMENT : holds DOCUMENT ||--|{ DOCUMENT_VERSION : "has versions" DOCUMENT_VERSION ||--|{ CONTENT_PART : comprises DOCUMENT }o--|| DOCUMENT_TYPE : "is a" DOCUMENT_VERSION }o--o| DOCUMENT_VERSION : "derived-from (provenance)" DOCUMENT ||--o{ RELATIONSHIP : "source of" DOCUMENT ||--o{ RELATIONSHIP : "target of" DOCUMENT ||--o{ ACKNOWLEDGEMENT : "acknowledged via" USER ||--o{ ACKNOWLEDGEMENT : makes SCOPE ||--o{ REVIEW_POLICY : configures DOCUMENT_TYPE ||--o{ REVIEW_POLICY : "per type" REVIEW_POLICY ||--|{ APPROVAL_REQUIREMENT : requires DOCUMENT_VERSION ||--o{ APPROVAL : "approved by" DOCUMENT_VERSION ||--o{ SIGNATURE : "signed by" DOCUMENT_VERSION ||--o{ REVIEW_COMMENT : "commented in review" DOCUMENT ||--o{ PERIODIC_REVIEW : "periodically reviewed" SCOPE ||--o{ AUDIT_EVENT : "logged in" SCOPE ||--o{ TASK : "scoped in" SCOPE ||--o{ NOTIFICATION : "scoped in" USER ||--o{ TASK : "assigned / acts on"</code></pre> <h3 id="entities">Entities<a class="headerlink" href="#entities" title="Permanent link">¶</a></h3> <table> <thead> <tr> <th>Entity</th> <th>Description</th> <th>Decided by</th> </tr> </thead> <tbody> <tr> <td><code>MANDATOR</code></td> <td>Customer, or the operating organization itself; the hard data separation boundary. Carries an <code>internal</code> classification (operating org vs. customer) — a reporting attribute, not a behaviour switch</td> <td>ADR-0002, ADR-0010</td> </tr> <tr> <td><code>SCOPE</code></td> <td>Workspace: type <code>GLOBAL</code> / <code>MANDATOR</code> / <code>PROJECT</code>, capability flags, nullable mandator FK. Every content-bearing table hangs off a scope for RLS enforcement</td> <td>ADR-0002</td> </tr> <tr> <td><code>USER</code></td> <td>Individual identity anchored to a stable OIDC subject (table <code>app_user</code>, V003); lifecycle state (invited/active/deactivated); global (no RLS); acts within scopes via role assignments. Deactivation preserves attribution; never deleted</td> <td>ADR-0011, ADR-0013</td> </tr> <tr> <td><code>ROLE</code></td> <td>Global catalog entry (name, description, translations); configurably mapped to a set of permissions</td> <td>ADR-0004, ADR-0012</td> </tr> <tr> <td><code>PERMISSION</code></td> <td>System-defined, closed-set named capability (content/functional or administrative); referenced by role mappings</td> <td>ADR-0012</td> </tr> <tr> <td><code>ROLE_ACTIVATION</code></td> <td>A scope opting in to a catalog role</td> <td>ADR-0004</td> </tr> <tr> <td><code>ROLE_ASSIGNMENT</code></td> <td>A user staffing an activated role in a scope; users may hold several roles</td> <td>ADR-0004</td> </tr> <tr> <td><code>DOCUMENT_TYPE</code></td> <td>Global catalog entry (SOP, WI, template, record, …); activated per scope like roles; carries the ID prefix (see below)</td> <td>ADR-0004</td> </tr> <tr> <td><code>DOCUMENT</code></td> <td>Identity + metadata of a managed document; lives in exactly one scope; carries the human-readable document ID and a content <code>language</code>; may link to a source via <code>translation-of</code></td> <td>ADR-0001, ADR-0020</td> </tr> <tr> <td><code>DOCUMENT_VERSION</code></td> <td>The unit all processes operate on: life-cycle state, version number, author, content (one or more parts; frozen as blobs on content-freezing, with a manifest hash), a <code>content_format</code> marker (<code>PM_DOC</code> — the tree record — is the only format written since ADR-0058; <code>MARKDOWN</code> is retained as unused schema headroom), version-level provenance link, <code>effective_from</code> date</td> <td>ADR-0001/0002/0003/0015/0017/0057</td> </tr> <tr> <td><code>CONTENT_PART</code></td> <td>A named file within a version, stored as an immutable SHA-256 blob, carrying a <code>kind</code> (TEXT / IMAGE / TREE); the version's manifest hash binds the ordered set. A PM_DOC version (ADR-0057/0058) freezes TWO body parts — the authoritative ProseMirror <strong>tree</strong> (<code>kind=TREE</code>, media type <code>application/prosemirror+json</code>) and its derived canonical Markdown <strong>projection</strong> (<code>kind=TEXT</code>, the human-readable and searchable body) — plus any IMAGE attachment parts (PNG/JPEG, edited in a per-draft working area, frozen on release). The tree is the record; the projection is computed from it</td> <td>ADR-0017, ADR-0045, ADR-0057/0058</td> </tr> <tr> <td><code>RELATIONSHIP</code></td> <td>A typed, directional link between documents (<code>derived-from</code>, <code>translation-of</code>, <code>supersedes</code>, <code>references</code>, <code>related-to</code>); provenance and translation are instances</td> <td>ADR-0021</td> </tr> <tr> <td><code>ACKNOWLEDGEMENT</code></td> <td>A controlled record that a user read/acknowledged a document version, with an optional simple-questionnaire result; required roles per document drive who must acknowledge</td> <td>ADR-0022</td> </tr> <tr> <td><code>PERIODIC_REVIEW</code></td> <td>A recorded periodic review of a document: reviewer(s), date, outcome (confirmed unchanged / revision initiated), next-review-due; may carry a signature</td> <td>ADR-0015</td> </tr> <tr> <td><code>REVIEW_POLICY</code></td> <td>Per scope × document type: approval requirements, four-eyes flag (default on), transition permissions, release mode</td> <td>ADR-0003</td> </tr> <tr> <td><code>APPROVAL_REQUIREMENT</code></td> <td>Part of a policy: role + minimum count</td> <td>ADR-0003</td> </tr> <tr> <td><code>APPROVAL</code></td> <td>Recorded per version: user, role-in-which-approved, timestamp</td> <td>ADR-0003</td> </tr> <tr> <td><code>SIGNATURE</code></td> <td>Electronic signature on a version (when the policy requires it): signer, meaning (authored/reviewed/approved/released), timestamp, bound content hash, authentication proof; manifested and immutable</td> <td>ADR-0014</td> </tr> <tr> <td><code>REVIEW_COMMENT</code></td> <td>Review/rejection feedback, attached to the reviewed version</td> <td>ADR-0003</td> </tr> <tr> <td><code>AUDIT_EVENT</code></td> <td>Append-only: every state transition and security-relevant action (who, what, when, from → to state)</td> <td>—</td> </tr> <tr> <td><code>TASK</code></td> <td>Actionable item generated from a domain event, assigned by role/user, tracked <code>open → done/cancelled</code>, auto-resolving; operational (not the record of truth)</td> <td>ADR-0019</td> </tr> <tr> <td><code>NOTIFICATION</code></td> <td>Informational message (read/unread), scope-keyed; may reference a task/event</td> <td>ADR-0019</td> </tr> </tbody> </table> <h3 id="human-readable-document-ids">Human-readable document IDs<a class="headerlink" href="#human-readable-document-ids" title="Permanent link">¶</a></h3> <ul> <li>Every scope has a short, unique, immutable <strong>scope code</strong> (e.g. <code>P42</code>, <code>ACME</code>); the global scope is the unprefixed root namespace.</li> <li>Format: <code>[<SCOPE-CODE>-]<TYPE-PREFIX>-<DESIGNATOR></code> — the type prefix comes from the document type's catalog entry; the designator is either an auto-sequence number (<strong>per scope and type</strong>) or a short human-readable slug (charset <code>[A-Z0-9_]</code>, length-limited, validated against reserved words such as type prefixes and scope codes). Examples: <code>SOP-007</code>, <code>SOP-SALES</code> (global), <code>ACME-WI-003</code> (mandator scope), <code>P42-SOP-001</code>, <code>P42-SOP-CUSTOMER_CARE</code> (created in project P42).</li> <li>The <strong>numbering mode</strong> (<code>sequence</code> / <code>slug</code> / author's choice) is configured per document type in the catalog: slugs suit low-volume governing documents (SOPs, WIs), auto-sequences suit high-volume records (test reports, minutes).</li> <li>IDs are immutable once assigned; display form appends the version: <code>SOP-007 v3</code>. This applies to slugs too: a slug whose meaning has drifted is <strong>not renamed</strong> — the title carries current meaning, and a truly misleading slug is resolved by superseding (new document, revoke the old), as in any paper QMS.</li> <li><strong>Derived documents inherit the source's full document ID unchanged</strong> — the project's tailored <code>SOP-007</code> is recognizably <em>the</em> <code>SOP-007</code> everywhere, with provenance recording the exact source version.</li> <li><strong>Collision-free by construction:</strong> locally created documents always carry their scope's prefix, inherited IDs always carry the (different) source scope's namespace, and derivation only flows downward in the hierarchy — the namespaces are disjoint.</li> <li>Bonus: the ID alone reveals a document's origin (base-derived vs. project-specific) — provenance at a glance for auditors and daily work.</li> </ul> <h3 id="provenance">Provenance<a class="headerlink" href="#provenance" title="Permanent link">¶</a></h3> <p>The <code>derived-from</code> link points <strong>version → version</strong> ("derived from base SOP-007 v3", never just "from SOP-007") so the audit question "which exact base version governed this project on date X" is answerable by a single lookup (ADR-0002).</p> <h3 id="content-record-tree-record--projection">Content record (tree record + projection)<a class="headerlink" href="#content-record-tree-record--projection" title="Permanent link">¶</a></h3> <p>The authoritative content of a document version is a <strong>ProseMirror document tree</strong> (the TipTap schema, format <code>PM_DOC</code>), not markdown text — the Confluence/ADF pattern (<a href="../../decisions/adr-0057-tree-as-record/">ADR-0057</a>). Markdown is a <strong>derived, deterministic, canonical projection</strong> computed from the tree by ONE shared projection function at save time and stored alongside it (the human-readable record copy, the text-diff surface, the AI/MCP content surface, and schema-lock-in exit insurance). The projection's correctness is pinned by a standing fixed-point test — <code>project(import(project(t))) == project(t)</code> — over the repurposed fidelity corpus (<code>npm run projection</code>). Editing modes over the tree: visual (TipTap — the engine chosen by <a href="../../decisions/adr-0059-editor-engine-tiptap/">ADR-0059</a>, which superseded the Milkdown/Crepe choice of ADR-0055/0056) loads/saves the tree natively with NO round-trip guard (the guard/fidelity machinery of ADR-0055/0056 is retired); source mode edits the projection and re-imports text→tree on leave (normalization is by design and immediately visible). Plain-text search extraction is computed <strong>server-side</strong> by structurally walking the tree JSON (<code>PmDocText</code>, the Kotlin port of the projection module's <code>extractText</code>) into a per-version <code>search_text</code> column, so the extraction can never drift from the record and never depends on the client-computed projection (§8.7).</p> <p><strong>PM_DOC is the only content format</strong> (<a href="../../decisions/adr-0058-v2-only-pre-production/">ADR-0058</a>, pre-production cut): every content write REQUIRES <code>{treeJson, projection}</code> (markdown-only writes are rejected, 400), the dual-format coexistence and v1 markdown-it record path of ADR-0057 §5 are retired, and dev/demo databases are reseeded rather than migrated. ONE narrow as-built exception remains: server-side <strong>template instantiation</strong> builds a <code>MARKDOWN</code> draft where no JS runtime can construct a tree; such a draft converts to <code>PM_DOC</code> on its first editor save, so the V040 record-integrity CHECK is state-qualified (a live PM_DOC draft must carry its tree) rather than universal. Adding node types (math, color, block-in-cell tables) is backward-compatible schema evolution under ADR-0057's known-limitations mechanism; renaming or removing a node type requires an explicit, tested tree-blob migration with its own ADR.</p> <h2 id="82-multi-mandator-data-separation">8.2 Multi-Mandator Data Separation<a class="headerlink" href="#82-multi-mandator-data-separation" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0002-single-instance-scope-hierarchy/">ADR-0002</a>: row-level tenancy keys on all content-bearing tables enforced by PostgreSQL Row-Level Security, blob storage partitioned per scope (ADR-0001), automated separation test suite in CI (RISK-001). Database-per-mandator is the documented fallback for contractual demands.</p> <p>RLS boundary (<a href="../../decisions/adr-0027-rls-content-vs-control-plane/">ADR-0027</a>): the RLS backstop guards <strong>content-bearing tables</strong> (documents, versions, content parts, audit events, search index) keyed to <code>lqms.authorized_scope_ids</code>. <strong>Control-plane tables</strong> (<code>scope</code>, <code>mandator</code>, catalogs, identity, authorization tables) are <strong>not</strong> under per-request content RLS — their access is governed by the permission model (ADR-0012). (Realized: 39 tables carry <code>ENABLE</code>/<code>FORCE ROW LEVEL SECURITY</code> with their policies, from the V002 scope/mandator pattern through the content tables added by later migrations.)</p> <p>RLS mechanism (<a href="../../decisions/adr-0009-rls-session-scope-context/">ADR-0009</a>): policies key off the session variable <code>lqms.authorized_scope_ids</code>; every content-bearing table has <code>ENABLE</code>/<code>FORCE</code> RLS and a policy granting the session its authorized scopes plus the shared global base (REQ-SEP-005). The application connects as the RLS-subject role <code>lqms_app</code>. The pattern and its proof are established on <code>scope</code>/<code>mandator</code> (V002, <code>RlsSeparationTest</code>); every future content table follows it.</p> <p>One deliberate exception to "policies key off <code>lqms.authorized_scope_ids</code>", and only one (<a href="../../decisions/adr-0107-audit-append-follows-assignment-reach/">ADR-0107</a>, V080): the <code>audit_event</code> <strong>append</strong> policy keys off the acting user's <em>assignment reach</em> (<code>lqms_assignment_reach_ids()</code>, resolved live from <code>lqms.current_user_id</code>), not their VIEW-derived scope set. Its <strong>read</strong> policy is unchanged. <em>Write where you are staffed, read what you may view</em> — so an administration-only account (admin ≠ content, REQ-ADM-004) can record the acts its authority produces without being handed customer content.</p> <p>Runtime mechanism (<code>RlsScopeContext</code>, ADR-0026): a unit of work runs inside a transaction that sets <code>SET LOCAL ROLE lqms_app</code> and <code>SET LOCAL lqms.authorized_scope_ids = …</code>. Both are transaction-local, so a pooled connection cannot carry a role or scope set into the next request (<code>RlsConnectionReuseTest</code>), and even a superuser datasource (Quarkus Dev Services in dev) is RLS-enforced inside the work (<code>RlsScopeContextTest</code>).</p> <p><strong>Runtime status (RISK-002):</strong> the mechanism is implemented, proven, and <strong>adopted</strong> — the authenticated request path routes its work through <code>AuthorizedRequestContext.runAs</code> with the caller's authorized scopes (241 <code>runAs</code> call sites across 55 main-source files as of 2026-08-18), so content transactions run transaction-locally as <code>lqms_app</code>. The residual exposure is defence-in-depth, not a live separation gap: a <em>new</em> code path that forgot the <code>runAs</code> wrapper would run with the datasource's privileges rather than failing closed, because the two-role datasource split is not packaged yet — tracked as DEBT-001 in §11. The technical mitigation is therefore complete; formal risk acceptance is still open in <a href="../../process/risk_management/">process/risk_management.md</a> (severity/probability scales and acceptance criteria are undecided).</p> <h2 id="83-document-life-cycles">8.3 Document Life Cycles<a class="headerlink" href="#83-document-life-cycles" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0003-fixed-lifecycle-configurable-reviews/">ADR-0003</a>: fixed states <code>DRAFT → IN_REVIEW → RELEASED → REVOKED</code>, plus the terminal <code>CANCELLED</code> (from DRAFT or IN_REVIEW, ADR-0024); configurable review policies per scope and document type; four-eyes rule default-on; editing a released document starts a new draft version. Creating a new version requires a change description (REQ-DOC-017, §4.2.4©).</p> <p><strong>Release flow — STANDARD vs DIRECT</strong> (<a href="../../decisions/adr-0091-record-release-modes/">ADR-0091</a>): the per-(scope, type) review policy carries a <code>release_flow</code> (V062). <code>STANDARD</code> is the submit→approve→release ceremony above; <code>DIRECT</code> lets an authorized role holder release straight from <code>DRAFT</code> (no <code>IN_REVIEW</code>) — the friction-free path for records ("proof the process ran"). This is a <em>policy-permitted transition</em>, not a new state: effectivity, retention, disposal, acknowledgement, training fan-out and audit are all unchanged, and the comments-resolved + training-questionnaire gates still evaluate (only the approvals gate is N/A). A <strong>structural floor</strong> bars <code>DIRECT</code> for PRESCRIPTIVE and TEMPLATE types (§4.2.4 requires their independent review) — enforced server-side and in the schema, never by convention. <code>release_flow</code> is orthogonal to the pre-existing <code>release_mode</code> (AUTOMATIC/EXPLICIT, V013), which only qualifies a STANDARD flow's release trigger. The runtime walkthrough is §6.1.</p> <p>Effectivity & periodic review (<a href="../../decisions/adr-0015-effectivity-periodic-review/">ADR-0015</a>): a released version has an <code>effective_from</code> date (default = release, may be future); the currently effective version is derived by date, not a stored state. Documents have a configurable periodic-review interval (per type, per-document override); a periodic review records reviewer/date/outcome and either resets the review clock (confirmed unchanged) or starts a new draft. Overdue review / passed <code>valid_until</code> are flagged and surfaced, never auto-revoked.</p> <h2 id="84-security--access-control">8.4 Security & Access Control<a class="headerlink" href="#84-security--access-control" title="Permanent link">¶</a></h2> <p><strong>Authentication</strong> (<a href="../../decisions/adr-0011-authentication-oidc-bff/">ADR-0011</a>, <a href="../../decisions/adr-0028-stateless-session-cookie/">ADR-0028</a>): delegated to an external OIDC provider (SSO; corporate IdP or bundled Keycloak) — LQMS stores no credentials. The web client uses a server-side (BFF) session held in an <strong>encrypted, httpOnly, Secure, SameSite token-state cookie</strong> — there is <strong>no server-side session store</strong> (stateless, so any instance serves any request), with idle/absolute timeouts and CSRF protection. The cookie is opaque to the client (no extractable claims) but is not server-revocable mid-lifetime; instead <strong>authorization is re-evaluated per request</strong> against live state, so administrative revocation (deactivation / role removal) takes effect on the next request (ADR-0028). Machine / MCP clients use OAuth2 bearer tokens (hybrid mode). Authentication grants no authorization; users are JIT-provisioned and gain access only via role assignments.</p> <p>Authorization (<a href="../../decisions/adr-0012-authorization-and-bootstrap/">ADR-0012</a>): the system defines a fixed, closed set of <strong>permissions</strong>; catalog <strong>roles are configurably mapped to permission sets</strong>; holding a role in a scope grants its permissions across that scope and its descendants (global-scope role = installation-wide admin; mandator-scope = delegated admin over its projects). Administrative and content permissions are independent — system administration does <strong>not</strong> implicitly grant content read, preserving mandator separation. Document life-cycle transitions remain governed by review policies (§8.3); the permission model governs all other functional and administrative actions. Audit trail via <code>AUDIT_EVENT</code>. <strong>All enforcement is server-side — the frontend only reflects permissions</strong> (<a href="../../decisions/adr-0007-angular-frontend/">ADR-0007</a>); the API exposes effective permissions for that purpose. On each authenticated request the user's authorized scope set is resolved from role assignments and applied as the RLS context (<code>lqms.authorized_scope_ids</code>, ADR-0009) — closing RISK-002 at runtime.</p> <p><strong>Bootstrap:</strong> a deployment-configured identity is granted system administration idempotently on startup (break-glass, no lock-out); first initialization auto-creates the global base scope and an internal mandator with a QMS-operations scope (ADR-0010, ADR-0012).</p> <p><strong>Authorization resolution</strong> (ADR-0009 hardening path): role activations and assignments (<code>role_activation</code>, <code>role_assignment</code>, V005) are scope-bearing but <strong>not</strong> under per-request RLS — they are read by SECURITY DEFINER functions that resolve, across scopes, (a) <code>lqms_authorized_scopes(user)</code> — the scopes whose content the user may see (those where the user has the <code>VIEW</code> permission effective, expanded over the scope subtree), which feeds <code>lqms.authorized_scope_ids</code>; and (b) <code>lqms_effective_permissions(user, scope)</code>. Because the authorized set is gated on a content-read permission, an admin-only role grants no content visibility — realizing "admin ≠ content" (REQ-ADM-004) at the RLS level. The functions' owner must bypass RLS (superuser in dev; a BYPASSRLS admin role in prod).</p> <p><strong>Operation-scoped RLS exceptions</strong> (ADR-0031/0034/0035): beyond the resolution functions, several narrow SECURITY DEFINER paths deliberately cross the per-request RLS boundary, each self-gating on the caller's authorization (the caller-less system sweeps gate on being run only by the owner-connection scheduler):</p> <ul> <li><em>Derive-source read</em> (V017): a <code>DERIVE</code> holder reads exactly the one released base version being derived — no standing base visibility.</li> <li><em>Overdue sweep</em> (V022/V023/V024, <code>lqms_sweep_overdue_tasks</code>) — the SYSTEM-context detector (ADR-0037/0039): a scheduler tick (advisory-lock elected, one instance) runs reminders, escalations, periodic-review-due and validity-expired detection across <strong>all</strong> scopes as the function owner. It has no caller gate (there is no acting user); its EXECUTE grant is deliberately <strong>not</strong> given to <code>lqms_app</code> — only the owner-connection scheduler path may run it (ADR-0039). Idempotent via stamps and role-qualified open-task guards; recipients resolve by the same V005 role cascade as enforcement.</li> <li><em>Recurring-obligation sweep</em> (V063/V066/V069, <code>lqms_sweep_recurring_obligations</code>) and <em>certification-renewal sweep</em> (V050, <code>lqms_sweep_certification_renewals</code>) — additional SYSTEM-context detectors on the same pattern, each with its <strong>own</strong> advisory-lock-elected scheduler (<code>RecurringObligationScheduler</code> / <code>CertificationRenewalScheduler</code>) and its EXECUTE grant revoked from <code>PUBLIC</code>. The obligation sweep raises <code>OBLIGATION_DUE</code> tasks to a duty's responsible-role holders when its <strong>derived</strong> next-due window opens, and reconciles (marks DONE) an open task the moment a completing release moves next-due out of window (ADR-0089/0094, §6.2); like the overdue sweep it writes no per-raise audit row and stays scope-local per row.</li> <li><em>Source-event fan-out </em><em>write</em><strong> (V021, <code>lqms_fanout_source_event</code>) — </strong>the only mechanism that carries one tenant's event into another tenant's scope<em><em> (the sweep above writes system-side but strictly scope-locally): on release/revoke of a derive-source version, the SYSTEM inserts one SOURCE_UPDATED/SOURCE_REVOKED task + notification per affected derived document into the </em>derived</em> scopes (REQ-DOC-012/REQ-LC-013). Gates: event/state match, derive-source scope, caller authorized for the source scope; idempotent via a partial unique index; payload limited to derived-scope-local identifiers; every evaluated fan-out is audited in the source scope; the recipient-count return is an accepted, documented disclosure (ADR-0035). A startup check refuses to boot if the function owner cannot bypass RLS (the silent-failure deployment case).</li> </ul> <p><strong>Notification delivery</strong> (ADR-0041): the notification row is the outbox — a scheduler tick (its own advisory lock, distinct from the sweep's) pushes undelivered rows through the pluggable <code>NotificationChannel</code> interface (email via quarkus-mailer, disabled by default); per-row stamping gives at-least-once delivery, poison rows are skipped and retried; content renders from structured params in the recipient's locale.</p> <p><strong>Disposal execution</strong> (ADR-0042/0043): the one destructive path — a <code>DISPOSE_RECORDS</code> holder disposes a fully-closed document in one hard-gated, locked transaction (legal hold, closure, retention re-verified; tombstoning, retained disposal record, audit, index-purge hook); blob deletion follows post-commit, manifest-aware and GC-backstopped (ADR-0043).</p> <p><strong>Orphan-blob garbage collection</strong> (<a href="../../decisions/adr-0092-orphan-blob-gc/">ADR-0092</a>, REQ-DOC-013): the sweep that discharges the disposal path's GC-backstop promise. A nightly maintenance sweep (system-scheduled, no acting user: <code>BlobGcScheduler</code> with its own advisory session lock; the <code>BlobGcSweepService</code>/<code>BlobGcRepository</code> in <code>document</code>) iterates the content store's scopes and runs each pass <strong>inside that scope's own RLS bounds</strong> (<code>rls.withAuthorizedScopes</code>), so <code>blob_quarantine</code> (itself FORCE-RLS) is never read or written across scopes. Per scope it runs <strong>two-phase quarantine, then purge</strong>: it computes stored blobs (<code>ContentStore.list</code>, off the file system) minus the live reference set, records new orphans in a <code>blob_quarantine</code> registry (V065), and only permanently deletes a quarantined blob once it has aged past the configured window (default <strong>30 days</strong>) <strong>and</strong> re-verifies unreferenced at purge time. The bin is a registry row, not a file move, so the content-addressed store's invariants hold — an idempotent re-<code>put</code> (dedup re-reference) simply works and rescue is a registry-row delete. The safety invariant (<strong>referenced blobs are never deleted</strong>) is structural: reference check and registry mutation share one transaction, file deletion is post-commit and idempotent, and a failed deletion is simply re-quarantined next pass. The set of hash-carrying blob-reference columns is enumerated in one place and an architecture test asserts the schema's column set equals that enumeration — so a new blob-referencing column fails the test until the GC inventory is extended (the schema-extension lifecycle trap, made structural).</p> <p><strong>Domain events</strong> (ADR-0034): life-cycle transitions publish typed events (<code>DomainEventPublisher</code>, lifecycle module) synchronously <em>inside the transition's transaction</em>; the notification module's handler persists the review workload atomically with the transition. Emitting modules never reference consumers; the <code>api</code> module wires subscriptions at startup. The registry is shaped for a later outbox replacement.</p> <h2 id="85-persistence">8.5 Persistence<a class="headerlink" href="#85-persistence" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0001-content-addressed-document-storage/">ADR-0001</a>: PostgreSQL (via jOOQ) is the single source of truth; version content as immutable SHA-256-keyed blobs behind a storage interface (file system now, S3 later); blob-first write protocol; orphan-blob garbage collection.</p> <p>Schema evolution: Flyway plain-SQL migrations in <code>backend/persistence</code>; jOOQ classes are generated from the real migrated schema at build time (<a href="../../decisions/adr-0008-flyway-and-jooq-codegen/">ADR-0008</a>).</p> <p><strong>Transactional boundaries and jOOQ usage patterns</strong> are settled by <a href="../../decisions/adr-0036-repository-layer/">ADR-0036</a> (2026-07-02) — <em>services carry rules, repositories carry jOOQ</em>:</p> <ul> <li>The <strong>only</strong> transaction/RLS boundary is the service's <code>AuthorizedRequestContext.runAs</code> block (§8.2). Repositories never open transactions and never own connections — each repository method takes the transaction's <code>DSLContext</code> as its first parameter, so the RLS discipline cannot be sidestepped from below.</li> <li>Repositories own <strong>all</strong> persistence access: the generated <code>ch.lqms.persistence.jooq.*</code> imports, query construction, row↔domain mapping, and the raw-SQL calls into the <code>lqms_*</code> SECURITY DEFINER functions. One repository per domain concept, in the module that owns it.</li> <li>Services hold authorization checks, state-machine guards, policy evaluation, event publication and orchestration, and carry no persistence-model imports. The <code>api</code> module contains no persistence access at all.</li> <li>Enforced by a Konsist architecture test: outside <code>persistence</code>, test code, and the two RLS plumbing classes in <code>scope</code>, only files named <code>*Repository</code> may import <code>ch.lqms.persistence.jooq</code>.</li> <li>Repositories are deliberately <strong>not</strong> interfaces (ADR-0001 commits to PostgreSQL as the single source of truth, so swappability buys nothing).</li> </ul> <h2 id="86-internationalization">8.6 Internationalization<a class="headerlink" href="#86-internationalization" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0020-internationalization/">ADR-0020</a>: UI text per-user translatable (REQ-UI-002) and catalog entries carry translations (ADR-0004); timestamps stored in UTC, displayed in the user's time zone, and manifested unambiguously on signatures/audit; dates/numbers formatted per the user's locale. Document <strong>content language</strong> is a per-document attribute; a <strong>translation is a separate, independently controlled document</strong> linked via <code>translation-of</code>, with one optionally designated the authoritative source. Search indexing is language-aware.</p> <h2 id="87-search">8.7 Search<a class="headerlink" href="#87-search" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0006-three-layer-search/">ADR-0006</a>: three layers — (1) PostgreSQL full-text search as the baseline, (2) local RAG with locally computed embeddings stored in pgvector under RLS, (3) pluggable LLM provider (cloud/on-prem) receiving only retrieved, permission-filtered chunks. LLM policy per mandator (cloud / on-prem / none); every LLM call audit-logged with the chunks sent. The index is derived data — rebuildable, skippable in backups.</p> <p><strong>Layer 1 is realized</strong> (<a href="../../decisions/adr-0044-search-fts-baseline/">ADR-0044</a>): a PostgreSQL FTS <code>search_index</code> (V029, under FORCE RLS so results are scope-filtered like all content) is populated event-driven at content-freeze; drafts are searchable by metadata, frozen bodies by full text; disposal/cancellation scrub the index. Exposed as <code>GET /api/search</code> with an admin reindex path. Layers 2–3 (RAG + pluggable LLM) remain future work.</p> <p><strong>Tree record and the extraction column (ADR-0057/0058).</strong> The frozen body that the FTS indexes is now the derived Markdown <strong>projection</strong> of the PM_DOC tree (§8.1), so full-text search already indexes the record's canonical text — the projection tokenizes to the same lexemes the tree carries. Separately, each PM_DOC version carries a server-computed <code>search_text</code> (V039), produced by a structural walk of the tree JSON (<code>PmDocText</code>, ADR-0057 §3) that can never drift from the record and never trusts a client extraction. This column is <strong>not</strong> on the FTS query path: the M5′ "search cutover" was evaluated and shipped as a deliberate <strong>no-op</strong> for user-visible search (the projection FTS already covers it); it becomes load-bearing at the RAG/AI layer 2 (<a href="../../decisions/adr-0058-v2-only-pre-production/">ADR-0058</a>).</p> <h2 id="88-error-handling-logging-audit">8.8 Error Handling, Logging, Audit<a class="headerlink" href="#88-error-handling-logging-audit" title="Permanent link">¶</a></h2> <p><code>AUDIT_EVENT</code> (§8.1) is the domain-level audit trail. It records not only life-cycle transitions but <strong>field-level changes (old → new values)</strong> to mutable records and security-relevant configuration (REQ-AUD-001/005, Part 11 §11.10(e) / Annex 11 §9), and supports a complete human-readable <strong>inspection copy</strong> of a record (REQ-AUD-006). Technical logging is separate from the domain audit trail.</p> <p>The trail is <strong>evidence, not a read model</strong> (<a href="../../decisions/adr-0110-audit-trail-is-not-a-read-model/">ADR-0110</a>): every act writes it, but at runtime it is read only to be shown (activity surfaces, evidence exports) or counted — never to answer a business question. A lifecycle fact a surface needs (who released, who invited) lives on the domain row, written in the same transaction as its trail event; if it exists only in the trail, a migration promotes it to state (the V088 shape).</p> <h2 id="89-data-protection--retention">8.9 Data Protection & Retention<a class="headerlink" href="#89-data-protection--retention" title="Permanent link">¶</a></h2> <p>See <a href="../../decisions/adr-0016-retention-disposal-privacy/">ADR-0016</a>: retention-primary (for regulated records, retention obligations override the right to erasure during the retention period); configurable retention per type/scope with a retention-start event, legal hold, and deliberate, audited disposal at end of retention. Personal data is minimized and attribution is pseudonymous (stable internal id; PII only in the user record), so PII can be severed without breaking record integrity. Erasure is narrow (no-retention-basis data, non-regulated scopes, end of retention) and done by physical deletion or user-record anonymization. Access and rectification are supported. Encryption-at-rest / crypto-shredding is deferred to the security NFRs (GAP-10). Swiss revised FADP + EU GDPR; ISO 13485 §4.2.5.</p> <h2 id="810-derived-state--parity-contracts">8.10 Derived state & parity contracts<a class="headerlink" href="#810-derived-state--parity-contracts" title="Permanent link">¶</a></h2> <p><strong>Derived-never-stored is a house doctrine.</strong> Anything that can be computed from the record set is derived live at read time, not persisted as a status that could silently drift. Instances: effective version (by date, not a stored flag — §8.3, REQ-EFF-002); periodic-review due/overdue (ADR-0076); requirement/risk coverage and the requirement/risk <strong>trace chains</strong> (<code>TraceCoverage</code> edge-type-set engine, <code>RequirementChainService</code>, <code>RiskTraceabilityService</code> — ADR-0086); the <strong>verification evidence class</strong> (planned vs. verified, derived from a per-type <code>verification_evidence</code> flag + source-release state, no link-type change — ADR-0088); recurring-obligation due/overdue (ADR-0089/0094); the <strong>validation matrix</strong> and <strong>GSPR-conformity</strong> views (<code>ValidationMatrixService</code>, <code>GsprConformityService</code> — Stage C, ADR-0084: <em>mirror-of-chains</em> derivations that reuse the same ADR-0088 evidence classing, nothing stored); and the scope <strong>traceability report</strong> — a point-in-time compilation over the existing read models (its digest now spans all five axes, incl. the two Stage-C views' sections), deliberately <em>never</em> a controlled document (ADR-0087). The pathology this avoids is matrix-as-content: a stored overview is stale the moment a link changes and either rots or forces perpetual re-release. Two exports on two days may legitimately differ, and say so.</p> <p><strong>Parity contracts</strong> are the load-bearing consequence: when the same fact is computed in two places, a test pins the two implementations against each other so they can never disagree. The standing ones:</p> <ul> <li><strong>Markdown projection ↔ tree</strong> — the fixed-point <code>project(import(project(t))) == project(t)</code> over the fidelity corpus (<code>npm run projection</code>, §8.1).</li> <li><strong><code>PmDocText</code> (Kotlin) ↔ <code>extractText</code> (JS)</strong> — the server search extraction is a structural walk that must yield what the shared projection module would (§8.1/§8.7).</li> <li><strong>Obligation sweep (SQL) ↔ oversight derivation (Kotlin)</strong> — RESOLVED into a single encoding by V069: <code>lqms_sweep_recurring_obligations</code> (both its RAISE and RESOLVE passes) and <code>RecurringObligationService</code> all call the shared function <code>lqms_obligation_next_due</code>, so the raised task and the reported verdict cannot diverge by construction (ADR-0089 §3, ADR-0094 §7 — the V049/V068 "one predicate, one encoding" precedent). Since V070 that rule is a FOLD over the obligation's completion history (each completion discharges the occurrence outstanding at its moment, ADR-0094's 2026-07-25 clarification); the function stays PURE and receives the history as an argument, so the data access — and with it the RLS boundary — remains on each caller's side while the encoding stays single. The test that used to pin two implementations against each other now pins the RULE itself on the hostile calendar histories (Jan-31→Feb, leap years, a completion exactly on an occurrence, LATE completions, cross-period late completions, and multi-completion periods).</li> <li><strong>Reflection ↔ enforcement</strong> — one <code>WorkflowActionEvaluator</code> seam (extracted from <code>DocumentService</code>, 2026-07) computes both what <code>getVersion.actions</code> advertises to the UI and what the transition actually enforces, so a "hidden or greyed tile" can never diverge from the server's decision (the "server is the authority" principle, ADR-0080; the DIRECT-release action is one consumer, ADR-0091 §4).</li> </ul> <p>Where a duplicated computation can instead be <strong>collapsed to a single source</strong>, that is preferred over pinning two encodings: the reflection↔enforcement seam above is one instance, and since <strong>V068</strong> the effective training <strong>baseline</strong> anchor is a single SQL function (<code>lqms_effective_training_baseline</code>) that the acknowledgement-coverage card and the training compliance roll-up both read — the two former hand-coded encodings are gone (ADR-0070 §5's rule made structural; <code>TrainingBaselineParityTest</code> stays as a guard), mirroring the <code>lqms_effective_training_mode</code> single-source (V049).</p> <h2 id="811-trace-items--the-traceability-web">8.11 Trace items & the traceability web<a class="headerlink" href="#811-trace-items--the-traceability-web" title="Permanent link">¶</a></h2> <p>Controlled documents carry <strong>keyed trace items</strong> — typed blocks inside the content tree, each with a scope-unique <code>key</code> — and <strong>trace links</strong> between those items (or between whole documents). The machinery is <strong>type-agnostic</strong> (<a href="../../decisions/adr-0078-generalized-trace-items/">ADR-0078</a>): one set of engines (extraction, the per-type registry, key-ownership/suspect resolution, coverage) reads a <strong>type registry</strong> instead of hard-coding any single type, so adding a type is <em>register a type</em> — the engines show a zero diff (the ADR-0078 acceptance property, guarded by <code>TraceItemGeneralizationTest</code>).</p> <p><strong>Registered types</strong> (<code>TraceItemRegistry.DEFAULT</code>, in registration order): <code>requirement</code> (<a href="../../decisions/adr-0077-requirement-items/">ADR-0077</a>); <code>risk</code> + <code>risk-control</code> (<a href="../../decisions/adr-0079-risk-items/">ADR-0079</a>); and — Stage C (<a href="../../decisions/adr-0084-validation-regulatory-axes/">ADR-0084</a>) — <code>user-need</code>, <code>validation-case</code>, <code>design-element</code>, and <code>regulatory-ref</code>. Each type's <em>ordered</em> attribute list is the content-hash input and is <strong>hash-frozen once released content exists</strong> (a changed attribute flips the link <em>suspect</em> flag; the <code>key</code> is identity and is not hashed). <strong>Edge vocabulary</strong> (<code>trace_link.type</code>): <code>verifies</code>, <code>satisfies</code>, <code>derives-from</code>, <code>references</code>, <code>mitigates</code>, <code>implemented-by</code>, and — Stage C (V067) — <code>validates</code> (validation-case/document → user-need) and <code>complies-with</code> (requirement/design-element/document → regulatory-ref). These complete the five trace axes of the traceability model: requirements, risk, design, validation, regulatory. <strong>Keys are one keyspace per scope</strong> across all types, so key extraction, ownership and suspect resolution walk <em>every</em> registered type over a document's tree (ADR-0078 §4).</p> <p><strong>May-define governance is configuration, not code.</strong> Whether a (scope, document-type) may <em>define</em> items of a type is a policy row: <code>requirement</code> uses the <code>may_define_requirements</code> column, and the six non-requirement types are gated per-(scope, type) via <code>type_trace_item_definition</code> (V058). One <em>attribute value set</em> is itself per-scope configuration rather than a fixed tool enum — the design-element <code>designKind</code> is validated on save against the scope's <strong>design-kind vocabulary</strong> (<code>design_kind_vocabulary</code>, V067; shipped default <code>architecture | interface | component | unit</code>, editable per scope, <strong>422</strong> on an unknown value) — a proven variation point per the opinionated-by-default principle, in contrast to the <em>normative</em> fixed enums (risk-control <code>controlKind</code>, regulatory-ref <code>applicability</code>) that the authoring UI constrains but the server does not value-check. <strong>One deliberate exception to that last clause</strong> (<a href="../../decisions/adr-0102-typed-template-variables/">ADR-0102</a>): a template variable declared <code>date</code> or <code>number</code> <em>is</em> value-checked server-side at instantiation and stored normalized (ISO-8601 / plain decimal) — the second server-side value rule after <code>designKind</code>, placed exactly where a wrong value becomes a frozen record.</p> <p><strong>Table surfaces are views over the one tree</strong> (<a href="../../decisions/adr-0082-table-shaped-risk-authoring/">ADR-0082</a>): a grid holds no second store — it drives the live content tree through generic, node-name-parameterized editor seams (<code>listTraceNodes</code> / <code>updateTraceAttrsAt</code> / <code>insertTraceItemAtEnd</code> / <code>deleteTraceAt</code>). The risk grid and the GSPR authoring grid are <strong>structural twins</strong> over that same four-method handle (the four bespoke risk seams were folded into the generic ones), so the projection round-trips byte-identically no matter which grid did the editing.</p> <p>The derived read models over this web — coverage, the requirement/risk trace chains, the validation matrix and the GSPR-conformity view — are all <em>derived-never-stored</em> and RLS-bounded (§8.10); item authoring/dialogs and PDF rendering are covered by the content-record concept (§8.1) and the registry-driven PDF fence expansion (ADR-0074).</p> </article> </div> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M13 20h-2V8l-5.5 5.5-1.42-1.42L12 4.16l7.92 7.92-1.42 1.42L13 8z"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../07_deployment_view/" class="md-footer__link md-footer__link--prev" aria-label="Previous: 7. Deployment View"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11z"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> 7. Deployment View </div> </div> </a> <a href="../09_architecture_decisions/" class="md-footer__link md-footer__link--next" aria-label="Next: 9. Architecture Decisions"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> 9. Architecture Decisions </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M4 11v2h12l-5.5 5.5 1.42 1.42L19.84 12l-7.92-7.92L10.5 5.5 16 11z"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> Built from <code>v0.9.56-4-g06c7f811</code> (commit <code>06c7f811</code>, 2026-09-09) — the same Markdown the repository ships. </div> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"base": "../..", "features": ["navigation.instant", "navigation.tracking", "navigation.top", "navigation.footer", "navigation.indexes", "toc.follow", "search.suggest", "search.highlight", "content.code.copy", "content.action.edit"], "search": "../../assets/javascripts/workers/search.6ce7567c.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script> <script src="../../assets/javascripts/bundle.83f73b43.min.js"></script> </body> </html>