Skip to content
LQMS
Software Requirements: API & User Interface
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
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--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" checked> <div class="md-nav__link md-nav__container"> <a href="../" 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="true"> <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="../stakeholder_requirements/" class="md-nav__link"> <span class="md-ellipsis"> Stakeholder Requirements </span> </a> </li> <li class="md-nav__item"> <a href="../gap-analysis/" class="md-nav__link"> <span class="md-ellipsis"> Requirements Gap Analysis </span> </a> </li> <li class="md-nav__item"> <a href="../req_admin/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Administration, Permissions & Onboarding </span> </a> </li> <li class="md-nav__item md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> Software Requirements: API & User Interface </span> </a> </li> <li class="md-nav__item"> <a href="../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="../req_auth/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Authentication & Session </span> </a> </li> <li class="md-nav__item"> <a href="../req_backup/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Backup & Restore </span> </a> </li> <li class="md-nav__item"> <a href="../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="../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="../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="../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="../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="../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="../req_i18n/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Internationalization </span> </a> </li> <li class="md-nav__item"> <a href="../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="../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="../req_migration/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Migration & Import </span> </a> </li> <li class="md-nav__item"> <a href="../req_nfr/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Non-Functional </span> </a> </li> <li class="md-nav__item"> <a href="../req_notifications/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Notifications & Tasks </span> </a> </li> <li class="md-nav__item"> <a href="../req_obligations/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../req_relationships/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Document Relationships </span> </a> </li> <li class="md-nav__item"> <a href="../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="../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="../req_search/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Search </span> </a> </li> <li class="md-nav__item"> <a href="../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="../req_signatures/" class="md-nav__link"> <span class="md-ellipsis"> Software Requirements: Electronic Signatures </span> </a> </li> <li class="md-nav__item"> <a href="../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="../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="../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"> </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/requirements/req_api_ui.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="software-requirements-api--user-interface">Software Requirements: API & User Interface<a class="headerlink" href="#software-requirements-api--user-interface" title="Permanent link">¶</a></h1> <table> <thead> <tr> <th>ID</th> <th>Requirement</th> <th>Trace</th> </tr> </thead> <tbody> <tr> <td>REQ-API-001</td> <td>All system functionality shall be exposed via a REST API; the frontend shall use no other channel.</td> <td>STR-013; ADR-0005, ADR-0007</td> </tr> <tr> <td>REQ-API-002</td> <td>Every API request shall be authenticated and executed under the requesting user's permissions; RLS shall apply to all API-initiated database access.</td> <td>STR-003; ADR-0002</td> </tr> <tr> <td>REQ-API-003</td> <td>The API shall expose the requesting user's effective permissions per resource so clients can reflect them without duplicating rule logic.</td> <td>STR-007; ADR-0007</td> </tr> <tr> <td>REQ-API-004</td> <td>The API shall be documented in an OpenAPI specification generated from the implementation.</td> <td>STR-013, STR-014</td> </tr> <tr> <td>REQ-API-005</td> <td>The API layer shall be structured so an MCP interface can be added as an additional consumer of the same services, subject to the same enforcement.</td> <td>STR-013; ADR-0005</td> </tr> <tr> <td>REQ-API-006</td> <td>The system shall expose a product version (plain semver, per the release ritual) via <code>GET /api/version</code> — a <code>productVersion</code> field alongside the build SHA and timestamp — and surface it in the UI build/version display where the product version leads the build stamps; a pre-release build (no release tag) shall render as "unreleased". The exporting tool version shall be recorded in the <code>EXPORTED</code> audit event (queryable evidence), never printed on a controlled-copy face.</td> <td>STR-014; ADR-0090</td> </tr> <tr> <td>REQ-UI-001</td> <td>The web frontend shall be an Angular application consuming the REST API.</td> <td>STR-007; ADR-0007</td> </tr> <tr> <td>REQ-UI-002</td> <td>All UI texts shall be translatable; language shall be selectable per user. Initial languages: TBD (expected: EN, DE, FR, IT).</td> <td>STR-012; ADR-0007</td> </tr> <tr> <td>REQ-UI-003</td> <td>The UI shall reflect permissions (hide/disable unavailable actions) but never be the enforcement point.</td> <td>STR-003; ADR-0007</td> </tr> <tr> <td>REQ-UI-004</td> <td>UI elements shall carry stable test selectors, and E2E flows shall be runnable against seeded test data, enabling the E2E suite to serve as CSV regression evidence.</td> <td>STR-014; ADR-0007</td> </tr> <tr> <td>REQ-UI-005</td> <td>The web frontend shall target WCAG 2.2 level AA accessibility.</td> <td>STR-007, STR-012; ADR-0007</td> </tr> <tr> <td>REQ-UI-006</td> <td>The web frontend shall support current evergreen browsers (latest stable Chrome, Edge, Firefox, Safari).</td> <td>STR-007; ADR-0007</td> </tr> <tr> <td>REQ-UI-007</td> <td>The UI shall present the differences between two versions of a document at the content-source level, distinguishing added, removed, and changed content, to support informed review and approval.</td> <td>STR-001, STR-002; ADR-0007</td> </tr> <tr> <td>REQ-UI-008</td> <td>The documents view shall present the scope's folder tree as a navigation panel; selecting a folder shall filter the document list to that folder, the document detail page shall show its folder path as a breadcrumb, the create flow shall allow preselecting a target folder, a move dialog shall relocate a document, and search hits shall show the resolved folder path. (Drag-and-drop is out of scope for this baseline.)</td> <td>STR-007; ADR-0048, ADR-0007</td> </tr> <tr> <td>REQ-UI-009</td> <td>The documents view shall present category tabs (PRESCRIPTIVE as "Documents", RECORD as "Records", TEMPLATE as "Templates"), the folder-tree filter applying within the selected tab, and search shall offer a document-category facet.</td> <td>STR-007; ADR-0049, ADR-0007</td> </tr> <tr> <td>REQ-UI-010</td> <td>The document detail page shall present a References section listing outgoing relationships grouped by type and incoming relationships as "referenced by", with both directions always visible; authorized users shall add edges via a search-backed document picker and remove edges per relationship, subject to permission (REQ-REL-005).</td> <td>STR-001, STR-007; ADR-0049, ADR-0007</td> </tr> <tr> <td>REQ-UI-011</td> <td>The system shall provide a per-scope traceability/completeness page presenting coverage rules as entry points phrased in natural language, each with its list of uncovered documents and the ability to close a gap in place (adding the missing relationship without leaving the page), plus a coverage matrix (source type × relation type × counterpart type).</td> <td>STR-011, STR-007; ADR-0049, ADR-0007</td> </tr> <tr> <td>REQ-UI-012</td> <td>The draft editor shall use a CodeMirror 6 markdown editor providing syntax highlighting, a selection/transaction API for the existing formatting toolbar, and editor keymaps; it shall be lazy-loaded and shall not change the server-side markdown preview/rendering pipeline. <em>Delta note (2026-07-10, ADR-0055/0056/0057/0058): the draft editor now DEFAULTS to a visual WYSIWYG tree editor (Milkdown Crepe) that loads/saves the ProseMirror tree record directly, with NO round-trip guard (retired by ADR-0057). The CodeMirror 6 editor is the <strong>source mode</strong>, editing the derived Markdown <strong>projection</strong>; leaving source mode re-imports text→tree. Both modes save <code>{treeJson, projection}</code> (PM_DOC only, ADR-0058).</em></td> <td>STR-007; ADR-0050, ADR-0032, ADR-0055, ADR-0056, ADR-0057, ADR-0007</td> </tr> <tr> <td>REQ-UI-013</td> <td>In the CM6 editor, typing <code>[[</code> shall trigger a document-link autocompletion (fed by the document lookup, REQ-SRCH-012) that inserts a <code>[Current Title](doc:<DOC-ID>)</code> link on selection; the relationship picker (REQ-UI-010) shall use the same search-backed lookup.</td> <td>STR-007, STR-008; ADR-0051, ADR-0049, ADR-0007</td> </tr> <tr> <td>REQ-UI-015</td> <td>The draft editor shall offer a diagram slash-command that opens a lazily-loaded Excalidraw editor island; a created diagram shall render in the reading/content surface and re-render after editing (double-click to edit). <em>Delta note (2026-07-15, ADR-0072): the island is now a self-hosted draw.io editor in a sandboxed same-origin iframe, taking over the full frame with the canvas maximized (one slim top bar: back · title · caption/alt toggle · save); the slash entry is disabled on the create form (no version yet) with a save-first hint. Double-click re-opens the diagram for editing.</em></td> <td>STR-007; ADR-0065, ADR-0072, ADR-0007</td> </tr> <tr> <td>REQ-UI-016</td> <td>The version detail shall present an Attachments section (name, media type, size, download link) and the draft editor shall provide an upload affordance; in-content references to non-image attachments shall be ordinary links to the attachment URL, never embeds.</td> <td>STR-007, STR-001; ADR-0069, ADR-0007</td> </tr> <tr> <td>REQ-UI-017</td> <td>When the effective training mode is QUESTIONNAIRE, the draft surface shall present a training section with an author-gated questionnaire editor, and addressees shall take the questionnaire from the task/inbox (with per-attempt scoring shown); questionnaire and acknowledgement status shall be reported per document, role, and scope (extending REQ-TRN-006).</td> <td>STR-025, STR-007; ADR-0070, ADR-0007</td> </tr> <tr> <td>REQ-UI-018</td> <td>The system shall present a per-scope QMS-configuration surface (route <code>/scope-config</code>, reached via a gear affordance next to Admin rather than a top-level nav word, with a scope picker) whose tabs each appear only when the caller holds that tab's governing permission (UI reflects, server enforces): Review policies (CONFIGURE_REVIEW_POLICY — four-eyes, release mode, comment gate, approval requirements, transition roles), Training policies (MANAGE_TRAINING — requires-ack/mode, addressee roles, training due-window), and Document types (ACTIVATE_CATALOG_ENTRIES — read-only activation/category view). The former top-level "Acknowledgements" nav item shall be removed and its route shall redirect here. New per-scope policy knobs shall land as fields in these tabs, never as new nav items. <em>(the ADR-0091 release-flow knob — STANDARD/DIRECT, offered for RECORD-category types only — landed as a Review-policies field per this rule; REQ-LC-027. The ADR-0084 per-scope design-kind vocabulary editor landed as an ACTIVATE_CATALOG_ENTRIES-gated field on the Document-types tab per this rule; REQ-VAL-004.)</em></td> <td>STR-007, STR-003; ADR-0073, ADR-0030, ADR-0007, ADR-0091, ADR-0084</td> </tr> <tr> <td>REQ-UI-019</td> <td>The system shall present a personal "My training" page (document-training obligations and external entries with mode/status chips, plus add/plan/complete/correct affordances and evidence upload/download) and, for MANAGE_TRAINING holders, a training-management dashboard (compliance summary chips, a worst-first per-document compliance table with click-through, an oldest-first aging tab, and expiring certifications with a per-person plan lookup).</td> <td>STR-025, STR-007; ADR-0071, ADR-0007</td> </tr> <tr> <td>REQ-UI-020</td> <td>The version detail shall offer a "Download PDF" affordance on post-working versions (RELEASED, REVOKED) that retrieves the server-rendered export (REQ-DOC-033); it shall not be offered for DRAFT, IN_REVIEW, CANCELLED, or disposed versions. <em>(scope-level audit-pack export menu added by REQ-UI-024)</em></td> <td>STR-007, STR-011; ADR-0074, ADR-0007</td> </tr> <tr> <td>REQ-UI-021</td> <td>The revise flow shall require a reason for change and accept an optional impact note (REQ-DOC-031); the version detail shall show the change-info block whenever a reason exists (highlighted, with a review hint while IN_REVIEW), the version history shall list per-version reasons, and the draft editor shall show the reason/impact read-only with an inline edit affordance while DRAFT.</td> <td>STR-007, STR-009; ADR-0001, ADR-0007</td> </tr> <tr> <td>REQ-UI-022</td> <td>The traceability page shall be a WORKSPACE: an overview hub whose tiles each show a headline metric + status (e.g. "Requirement coverage 36/77 · 5 gaps") and link to a focused sub-page (<code>/traceability/{coverage,risk,relations,training}</code>), reserving tiles for later views (validation / GSPR). Each tile and route shall appear only where the caller holds the governing permission in a scope (REQ-ADM-010), the hub aggregating per-scope rows across the caller's permitted scopes; when the caller holds none in any scope the Traceability nav entry shall hide entirely (like Admin / scope-config). The QMB training-compliance oversight roll-up shall MOVE here (<code>/traceability/training</code>) while the personal "My training" page keeps only the personal view. UI gating reflects the permissions; the server enforces them (REQ-ADM-010, REQ-UI-003). <em>(the reserved validation / GSPR tiles are now live — the validation-matrix and gspr-conformity sub-pages, REQ-VAL-005 / REQ-GSP-002; ADR-0084.)</em></td> <td>STR-007, STR-011, STR-027; ADR-0080, ADR-0071, ADR-0007, ADR-0084</td> </tr> <tr> <td>REQ-UI-023</td> <td>Risk-analysis-capable documents shall offer a TABLE-SHAPED authoring and reading surface over their risk items in which each grid row IS a <code>:::risk</code> block in the document tree — add row inserts a block, edit cell edits that block's attribute, delete row deletes the block — with NO second record and no parallel serialization path (the frozen tree, content hashes and projection fidelity stay byte-unaffected). Columns shall be the fixed risk attribute set (REQ-RISK-001) plus read-only DERIVED columns from the link substrate (mitigating controls, implemented-by, verified-by, gap flags), scoped to the document. Read mode shall render the same grid read-only on the version detail; the single-item block dialog and prose-embedded risks shall remain first-class; scores shall render as recorded tokens, never as a computed (<code>=</code>) column.</td> <td>STR-001, STR-007, STR-027; ADR-0082, ADR-0079, ADR-0057, ADR-0007</td> </tr> <tr> <td>REQ-UI-024</td> <td>The scope's documents surface shall offer a scope-level export menu for the audit pack (REQ-DOC-037): the merged reviewer's-copy PDF shall LEAD the menu and the per-document zip entry shall carry the caveat that its relative cross-file links are viewer-dependent (they resolve in a desktop PDF viewer such as Acrobat, with the files kept in one folder). Both entries retrieve the server-rendered artifacts and are permission-gated (VIEW in the scope; the affordance follows the server gate, not the reverse).</td> <td>STR-007, STR-011; ADR-0083, ADR-0074, ADR-0007</td> </tr> <tr> <td>REQ-UI-025</td> <td>The toolbar scope switcher (a scope id or ALL, persisted) shall be the application's single scope-filter state; per-view scope selectors are removed. Views that can honor ALL (the documents list, search) keep client-side filtering and show everything on ALL; views that require one scope (the per-scope traceability pages — coverage, chains, risk, training compliance, obligations oversight, validation matrix, GSPR conformity, report download — and the scope-config surface) shall read the context: a chosen scope is used directly with no view-level selector, while on ALL the view renders a neutral "Select a project" picker (no preselection) and fetches nothing until a scope is picked. Picking in a neutral picker shall write the one context (the toolbar switcher follows, applying the filter everywhere); a deep link naming a scope shall apply it to the context on load. The context is a display filter only — every per-scope API call remains server-authorized (REQ-API-002); a stored context the caller can no longer see falls back to ALL. Admin pages, action-target pickers, and the inbox stay excluded.</td> <td>STR-007, STR-003; ADR-0093, ADR-0080, ADR-0007</td> </tr> <tr> <td>REQ-UI-026</td> <td>GSPR/applicability documents shall offer a TABLE-SHAPED authoring and reading surface over their regulatory-ref items in which each grid row IS a <code>:::regulatory-ref</code> block in the document tree — add row inserts a block (born applicability <code>applicable</code>, the "all applicable, mark exceptions" GSPR default), edit cell edits that block's attribute, delete row deletes the block — with NO second store and no parallel serialization path (the frozen tree, content hashes and projection fidelity stay byte-unaffected), mirroring the risk grid (REQ-UI-023) for the regulatory-ref type (REQ-GSP-001). Read mode shall render the same grid read-only; the single-item block dialog and prose-embedded references shall remain first-class.</td> <td>STR-001, STR-007, STR-027; ADR-0084, ADR-0082, ADR-0057, ADR-0007</td> </tr> <tr> <td>REQ-UI-014</td> <td>The frontend shall consume the live event channel (REQ-NOT-010) to refetch and refresh affected views (document list, open detail, inbox) with a subtle "updated" affordance (no toasts in this baseline) and shall display ephemeral "is editing" presence chips (REQ-NOT-011) on the draft editor and document detail page.</td> <td>STR-007; ADR-0050, ADR-0007</td> </tr> <tr> <td>REQ-UI-027</td> <td>The user manual shall ship inside the application, versioned with it; help affordances on a surface shall open the topic that documents that surface, and the build shall fail if a referenced topic, scene capture or surface link is missing (bidirectionality enforced).</td> <td>STR-030; ADR-0099</td> </tr> </tbody> </table> </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="../req_admin/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Software Requirements: Administration, Permissions & Onboarding"> <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"> Software Requirements: Administration, Permissions & Onboarding </div> </div> </a> <a href="../req_audit_reporting/" class="md-footer__link md-footer__link--next" aria-label="Next: Software Requirements: Audit Trail & Regulatory Reporting"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Software Requirements: Audit Trail & Regulatory Reporting </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>