Skip to content
LQMS
Tutorial — from zero to a released document
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--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--active md-nav__item--nested"> <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" checked> <div class="md-nav__link md-nav__container"> <a href="../" 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="true"> <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 md-nav__item--active"> <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc"> <label class="md-nav__link md-nav__link--active" for="__toc"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> <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="#before-you-start--the-demo-stack-the-personas-the-project" class="md-nav__link"> <span class="md-ellipsis"> Before you start — the demo stack, the personas, the project </span> </a> </li> <li class="md-nav__item"> <a href="#part-0--register-a-new-project" class="md-nav__link"> <span class="md-ellipsis"> Part 0 — Register a new project </span> </a> </li> <li class="md-nav__item"> <a href="#part-1--configure-the-project-as-the-quality-manager" class="md-nav__link"> <span class="md-ellipsis"> Part 1 — Configure the project (as the Quality Manager) </span> </a> <nav class="md-nav" aria-label="Part 1 — Configure the project (as the Quality Manager)"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#1a-review-policies--and-four-eyes-vs-direct" class="md-nav__link"> <span class="md-ellipsis"> 1a. Review policies — and four-eyes vs. direct </span> </a> </li> <li class="md-nav__item"> <a href="#1b-training-policy-on-one-type" class="md-nav__link"> <span class="md-ellipsis"> 1b. Training policy on one type </span> </a> </li> <li class="md-nav__item"> <a href="#1c-let-a-type-define-requirement-trace-items" class="md-nav__link"> <span class="md-ellipsis"> 1c. Let a type define requirement trace items </span> </a> </li> <li class="md-nav__item"> <a href="#1d-staff-a-person-into-a-role" class="md-nav__link"> <span class="md-ellipsis"> 1d. Staff a person into a role </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-2--author-a-draft" class="md-nav__link"> <span class="md-ellipsis"> Part 2 — Author a draft </span> </a> <nav class="md-nav" aria-label="Part 2 — Author a draft"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#2a-create-the-draft" class="md-nav__link"> <span class="md-ellipsis"> 2a. Create the draft </span> </a> </li> <li class="md-nav__item"> <a href="#2b-write-in-the-visual-editor" class="md-nav__link"> <span class="md-ellipsis"> 2b. Write, in the visual editor </span> </a> </li> <li class="md-nav__item"> <a href="#2c-insert-a-requirement-trace-item" class="md-nav__link"> <span class="md-ellipsis"> 2c. Insert a requirement trace item </span> </a> </li> <li class="md-nav__item"> <a href="#2d-attach-a-file-and-link-another-document" class="md-nav__link"> <span class="md-ellipsis"> 2d. Attach a file and link another document </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-3--review--release" class="md-nav__link"> <span class="md-ellipsis"> Part 3 — Review & release </span> </a> <nav class="md-nav" aria-label="Part 3 — Review & release"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#3a-submit-as-the-author" class="md-nav__link"> <span class="md-ellipsis"> 3a. Submit (as the author) </span> </a> </li> <li class="md-nav__item"> <a href="#3b-review-and-approve-as-the-reviewer" class="md-nav__link"> <span class="md-ellipsis"> 3b. Review and approve (as the reviewer) </span> </a> </li> <li class="md-nav__item"> <a href="#3c-release" class="md-nav__link"> <span class="md-ellipsis"> 3c. Release </span> </a> </li> <li class="md-nav__item"> <a href="#3d-the-counter-example--direct-release-of-a-record" class="md-nav__link"> <span class="md-ellipsis"> 3d. The counter-example — direct release of a record </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-4--training--acknowledgement" class="md-nav__link"> <span class="md-ellipsis"> Part 4 — Training & acknowledgement </span> </a> </li> <li class="md-nav__item"> <a href="#part-5--trace--prove" class="md-nav__link"> <span class="md-ellipsis"> Part 5 — Trace & prove </span> </a> <nav class="md-nav" aria-label="Part 5 — Trace & prove"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#5a-author-a-verifies-link-in-your-project" class="md-nav__link"> <span class="md-ellipsis"> 5a. Author a Verifies link (in your project) </span> </a> </li> <li class="md-nav__item"> <a href="#5b-read-the-coverage--and-the-new-validation-matrix" class="md-nav__link"> <span class="md-ellipsis"> 5b. Read the coverage — and the new validation matrix </span> </a> </li> <li class="md-nav__item"> <a href="#5c-export-the-proof" class="md-nav__link"> <span class="md-ellipsis"> 5c. Export the proof </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-6--operate-a-recurring-obligation" class="md-nav__link"> <span class="md-ellipsis"> Part 6 — Operate: a recurring obligation </span> </a> </li> <li class="md-nav__item"> <a href="#part-7--wrap-up-what-you-now-know" class="md-nav__link"> <span class="md-ellipsis"> Part 7 — Wrap-up: what you now know </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../administration/" class="md-nav__link"> <span class="md-ellipsis"> Administering an LQMS Installation </span> </a> </li> <li class="md-nav__item"> <a href="../diagrams/" class="md-nav__link"> <span class="md-ellipsis"> Diagrams </span> </a> </li> <li class="md-nav__item"> <a href="../documents-lifecycle/" class="md-nav__link"> <span class="md-ellipsis"> Documents & the Lifecycle </span> </a> </li> <li class="md-nav__item"> <a href="../exports/" class="md-nav__link"> <span class="md-ellipsis"> PDF Exports & the Audit Pack </span> </a> </li> <li class="md-nav__item"> <a href="../obligations/" class="md-nav__link"> <span class="md-ellipsis"> Recurring Obligations </span> </a> </li> <li class="md-nav__item"> <a href="../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="../review-comments/" class="md-nav__link"> <span class="md-ellipsis"> Review Comments </span> </a> </li> <li class="md-nav__item"> <a href="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../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="../traceability-workspace/" class="md-nav__link"> <span class="md-ellipsis"> The Traceability Workspace </span> </a> </li> <li class="md-nav__item"> <a href="../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="#before-you-start--the-demo-stack-the-personas-the-project" class="md-nav__link"> <span class="md-ellipsis"> Before you start — the demo stack, the personas, the project </span> </a> </li> <li class="md-nav__item"> <a href="#part-0--register-a-new-project" class="md-nav__link"> <span class="md-ellipsis"> Part 0 — Register a new project </span> </a> </li> <li class="md-nav__item"> <a href="#part-1--configure-the-project-as-the-quality-manager" class="md-nav__link"> <span class="md-ellipsis"> Part 1 — Configure the project (as the Quality Manager) </span> </a> <nav class="md-nav" aria-label="Part 1 — Configure the project (as the Quality Manager)"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#1a-review-policies--and-four-eyes-vs-direct" class="md-nav__link"> <span class="md-ellipsis"> 1a. Review policies — and four-eyes vs. direct </span> </a> </li> <li class="md-nav__item"> <a href="#1b-training-policy-on-one-type" class="md-nav__link"> <span class="md-ellipsis"> 1b. Training policy on one type </span> </a> </li> <li class="md-nav__item"> <a href="#1c-let-a-type-define-requirement-trace-items" class="md-nav__link"> <span class="md-ellipsis"> 1c. Let a type define requirement trace items </span> </a> </li> <li class="md-nav__item"> <a href="#1d-staff-a-person-into-a-role" class="md-nav__link"> <span class="md-ellipsis"> 1d. Staff a person into a role </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-2--author-a-draft" class="md-nav__link"> <span class="md-ellipsis"> Part 2 — Author a draft </span> </a> <nav class="md-nav" aria-label="Part 2 — Author a draft"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#2a-create-the-draft" class="md-nav__link"> <span class="md-ellipsis"> 2a. Create the draft </span> </a> </li> <li class="md-nav__item"> <a href="#2b-write-in-the-visual-editor" class="md-nav__link"> <span class="md-ellipsis"> 2b. Write, in the visual editor </span> </a> </li> <li class="md-nav__item"> <a href="#2c-insert-a-requirement-trace-item" class="md-nav__link"> <span class="md-ellipsis"> 2c. Insert a requirement trace item </span> </a> </li> <li class="md-nav__item"> <a href="#2d-attach-a-file-and-link-another-document" class="md-nav__link"> <span class="md-ellipsis"> 2d. Attach a file and link another document </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-3--review--release" class="md-nav__link"> <span class="md-ellipsis"> Part 3 — Review & release </span> </a> <nav class="md-nav" aria-label="Part 3 — Review & release"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#3a-submit-as-the-author" class="md-nav__link"> <span class="md-ellipsis"> 3a. Submit (as the author) </span> </a> </li> <li class="md-nav__item"> <a href="#3b-review-and-approve-as-the-reviewer" class="md-nav__link"> <span class="md-ellipsis"> 3b. Review and approve (as the reviewer) </span> </a> </li> <li class="md-nav__item"> <a href="#3c-release" class="md-nav__link"> <span class="md-ellipsis"> 3c. Release </span> </a> </li> <li class="md-nav__item"> <a href="#3d-the-counter-example--direct-release-of-a-record" class="md-nav__link"> <span class="md-ellipsis"> 3d. The counter-example — direct release of a record </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-4--training--acknowledgement" class="md-nav__link"> <span class="md-ellipsis"> Part 4 — Training & acknowledgement </span> </a> </li> <li class="md-nav__item"> <a href="#part-5--trace--prove" class="md-nav__link"> <span class="md-ellipsis"> Part 5 — Trace & prove </span> </a> <nav class="md-nav" aria-label="Part 5 — Trace & prove"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#5a-author-a-verifies-link-in-your-project" class="md-nav__link"> <span class="md-ellipsis"> 5a. Author a Verifies link (in your project) </span> </a> </li> <li class="md-nav__item"> <a href="#5b-read-the-coverage--and-the-new-validation-matrix" class="md-nav__link"> <span class="md-ellipsis"> 5b. Read the coverage — and the new validation matrix </span> </a> </li> <li class="md-nav__item"> <a href="#5c-export-the-proof" class="md-nav__link"> <span class="md-ellipsis"> 5c. Export the proof </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#part-6--operate-a-recurring-obligation" class="md-nav__link"> <span class="md-ellipsis"> Part 6 — Operate: a recurring obligation </span> </a> </li> <li class="md-nav__item"> <a href="#part-7--wrap-up-what-you-now-know" class="md-nav__link"> <span class="md-ellipsis"> Part 7 — Wrap-up: what you now know </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/user-guide/tutorial.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="tutorial--from-zero-to-a-released-document">Tutorial — from zero to a released document<a class="headerlink" href="#tutorial--from-zero-to-a-released-document" title="Permanent link">¶</a></h1> <p><em>Audience: a brand-new user, following along on a running demo stack. No prior LQMS knowledge is assumed beyond being able to log in.</em></p> <p>This is a hands-on <strong>tutorial</strong>, not a reference. You will follow a single project from the moment it is registered, through configuration, authoring, review, release, training, traceability, and a recurring operational duty — doing each step yourself and checking the result before moving on. Every part ends with a <strong>✔ Checkpoint</strong> so you always know whether you are on track. The reference chapters (linked from each part and from the <a href="../">README</a>) carry the depth; this tutorial walks the happy path.</p> <blockquote> <p><strong>An honest aside about this document.</strong> This tutorial lives in the repository today, as a Markdown file. It is a <em>candidate</em> to become a controlled <strong>training document inside LQMS</strong> later — brought in the same dogfooding way the early controlled-vocabulary drafts were, so that "learn to use LQMS" is itself a released, acknowledged QMS document. Until that happens it is uncontrolled repo documentation. Nothing below depends on that move.</p> </blockquote> <h2 id="before-you-start--the-demo-stack-the-personas-the-project">Before you start — the demo stack, the personas, the project<a class="headerlink" href="#before-you-start--the-demo-stack-the-personas-the-project" title="Permanent link">¶</a></h2> <p>You need a <strong>running demo instance and its address</strong> — most readers get both from whoever operates their stack: ask for the URL and the demo credentials, open it, and you will be redirected to the login page.</p> <p><em>Running the demo stack yourself</em> (operators with a source checkout only): <code>deploy/DEMO.md</code> carries the two commands and the host prerequisites; the app then answers on <code>http://localhost:8080/</code>.</p> <p>You will switch between four seeded people. Each is a real login; to change persona, open the <strong>user menu</strong> (your name, top right) and <strong>Log out</strong>, then log in as the next one.</p> <table> <thead> <tr> <th>Persona</th> <th>Login / password</th> <th>Their part in this tutorial</th> </tr> </thead> <tbody> <tr> <td>Quality Manager</td> <td><code>carla.fischer</code> / <code>carla</code></td> <td>configures the project; staffs people (also a User Administrator)</td> </tr> <tr> <td>Document Author</td> <td><code>ben.keller</code> / <code>ben</code></td> <td>writes drafts, submits them, authors trace links</td> </tr> <tr> <td>Quality Reviewer</td> <td><code>anna.sommer</code> / <code>anna</code></td> <td>reviews, approves and releases (the second pair of eyes)</td> </tr> <tr> <td>Administrator</td> <td><code>demo</code> / <code>demo</code></td> <td>the system administrator — note <em>admin ≠ content</em>: they manage the role catalog but see no project documents</td> </tr> </tbody> </table> <p><strong>The project you will work in.</strong> In Part 0 you register a project of your own. From Part 1 on, the hands-on steps run in a project the demo world already carries — <strong>Cardio Monitor</strong> (code <code>MEDTECH-CARDIO</code>), a software project — because the later lessons need content that is already there. Treat it as the project you just registered. Two other seeded projects appear where they show a feature best and you will only <em>observe</em> them:</p> <ul> <li><strong>SAMPLE</strong> — a compact ISO 14971 / IEC 62304 teaching corpus with a complete item-level trace chain already built (Part 5).</li> <li><strong>QMS-OPS</strong> — the internal operations QMS, which carries a ready recurring obligation (Part 6).</li> </ul> <p>Wherever the demo stack already contains something this tutorial would have you create, a <strong>> On the demo stack</strong> note tells you to skip or just observe.</p> <hr /> <h2 id="part-0--register-a-new-project">Part 0 — Register a new project<a class="headerlink" href="#part-0--register-a-new-project" title="Permanent link">¶</a></h2> <p><em>Manual topics:</em> <a href="../topics/provisioning-birth-path/">How a new organization and project are born</a> · <a href="../topics/setup-wizard-lanes/">The setup wizard's lanes</a></p> <p>In LQMS a <strong>project</strong> is a <em>scope</em>: a strictly separated space that holds one project's documents, records, roles and configuration. Every project belongs to an <strong>organization</strong> — the customer or company the work is done for, and the hard boundary between one tenant's data and another's. Both are created in the app, and that is what you are about to do: found an organization and register a project inside it, before you spend six parts working in that project.</p> <p><strong>They are two acts, deliberately.</strong> Founding an organization creates a separation boundary — its own space, its own membership, its own permanent trail — and starting a project is routine work inside a boundary that already exists. The app keeps them apart so the first can never happen as a side effect of the second.</p> <p><em>Log in as </em><em><code>carla.fischer</code></em><strong>. On this stack she is also a </strong>User Administrator**, which is what lets her found an organization, create a project and staff people into it.</p> <ol> <li>Click <strong>Admin</strong> in the top bar. → The left sub-nav lists the governance surfaces, and the two acts of this part are two separate entries in it: <strong>Project setup</strong> and <strong>Found an organization</strong>. That separation is the point — you cannot wander into founding a customer while doing routine work.</li> <li>You need a customer of your own first, so click <strong>Found an organization</strong>. → A page of its own opens, and before it asks anything it states what founding creates: its own space, its own membership, its own audit trail.</li> <li>Type <code>Muster Diagnostics AG</code> into <strong>Organization name</strong> and click <strong>Found the organization</strong>. → It exists, and the page says what that means: <em>"It has no project and nobody in it yet"</em> — both are separate next acts. Click <strong>Set up its first project</strong>, the first of the two beats offered.</li> <li>The project wizard opens on its <strong>Project</strong> step, already in the <strong>The new project</strong> block, with the boundary stated at the top: <em>"This project will belong to: Muster Diagnostics AG"</em>. (The wizard is subtitled <em>"Set a project up in four steps — the house-validated configuration, editable before it is written."</em> All four steps — <strong>Project</strong>, <strong>Lane</strong>, <strong>Configuration</strong>, <strong>Apply & verify</strong> — are listed from the start, so you see the whole checklist instead of meeting it one screen at a time. <strong>Nothing is written until the last step</strong>, so you can go back and change anything on the way.) Fill in the rest:</li> <li><strong>Project code</strong> — a code of your choosing, e.g. <code>PULSE</code> (the field upper-cases as you type). Read its hint: <em>"Unique and immutable; it prefixes every document id in this project."</em> Take that literally, because this is the one entry nobody can correct later: with <code>PULSE</code>, the first SW requirement you write here is called <code>PULSE-SWREQ-001</code> — and that name is what every export, cross-reference and audit trail will carry from now on.</li> <li><strong>Project name</strong> — <code>Pulse Analyzer</code>, or whatever you like. The form asks for nothing else, and says so: it does <strong>not</strong> ask whether the project keeps its own records (that follows from the project type) nor whether it may be a <em>derive source</em> — the latter is a governed setting on an existing project, set later on <strong>the project's own configuration page</strong> (or under <strong>Admin → Scopes</strong>), not a birth-time choice. A brand-new project is not one anyway: base procedures are derived <em>into</em> a project from the operating organization's own, not out of a fresh one. Click <strong>Next</strong>.</li> </ol> <p><strong>Why the boundary is never quietly filled in.</strong> The organization a project belongs to is the one thing here that can never be corrected later, so the wizard only ever <em>asks</em> for it when there is a real choice and always <em>states</em> it before you commit. Where several organizations exist, the picker has <strong>no default</strong> and <strong>Next</strong> stays disabled until you choose — <em>"Pick the customer this project belongs to — there is no default, and it cannot be changed later."</em> Where only one does, or where you arrived from the founding workflow as you just did, there is no question to answer, but the binding is stated as a fact in front of you. And founding a second organization under a name that already exists is refused rather than quietly adopted: two customers collapsing into one tenant is exactly the failure the boundary exists to prevent.</p> <ol> <li>Step <strong>Lane</strong> asks what kind of scope this is. Three cards, differing in kind rather than degree:</li> <li><strong>Supplier lane (IEC 62304)</strong> — <em>"Software supplier: requirements, design, tests and the risk file — verification against the customer's requirements. No validation or GSPR axis."</em></li> <li><strong>Manufacturer lane (ISO 13485)</strong> — <em>"Legal manufacturer: everything the supplier lane carries plus stakeholder needs, the validation axis and the GSPR applicability matrix."</em></li> <li><strong>QMS / process scope (ISO 13485)</strong> — <em>"The organisation's own QMS: SOPs, work instructions, templates and records — no product traceability."</em> Pick <strong>Supplier lane (IEC 62304)</strong> for this lesson, then <strong>Next</strong>. (How to choose for a real project — and why the manufacturer lane is the safe answer when you are torn between the two product lanes: <a href="../topics/setup-wizard-lanes/">The setup wizard's lanes</a>.)</li> </ol> <p>The lane is a <strong>starting proposal</strong>, not a label you are stuck with. It decides which document types, special elements and folders the next step suggests — all of them editable before anything is written.</p> <ol> <li>Step <strong>Configuration</strong> opens pre-filled: <em>"This is the proposal, not a decision: everything below is editable before anything is written."</em> Work down it:</li> <li><strong>Roles</strong> — three questions in plain words: <em>Who authors documents in this project?</em>, <em>Who reviews them?</em>, <em>Who manages quality?</em> Here they resolve to <strong>Document Author</strong>, <strong>Quality Reviewer</strong> and <strong>Quality Manager</strong>; because a new project carries no roles yet, the dropdown marks each of them <strong>will be activated</strong>, and the list below the three questions names exactly those — with <strong>Remove</strong> per row and <strong>Also activate a role</strong> if you need a fourth.</li> <li><strong>Staff yourself now</strong> — confirm <strong>Quality Manager</strong> is ticked (it already is; tick any other role you mean to work in). Do not clear it; the paragraph after this list says why.</li> <li><strong>Document types and their policies</strong> — one expandable panel per proposed type, each carrying its four-eyes toggle and its workflow grants (<strong>Authors (may submit)</strong> / <strong>Reviewers (must approve)</strong> / <strong>Releasers (may release)</strong>). At the foot of each panel a quiet line states what that type will be allowed to mint — <em>Defines: Risk, Risk control</em> on the Risk Analysis panel, <em>Defines no special elements</em> on most of the others. It is a <strong>statement</strong>, not a control: the decision behind it is made one section further down. Leave the proposal as it stands — Part 1 is where you learn to change it.</li> <li><strong>Folder skeleton</strong> — leave <strong>Create these folders</strong> ticked (<em>Procedures, Requirements, Design, Verification, Records</em> for this lane).</li> <li><strong>Special elements</strong> — the keyed things this project traces. Every kind the product knows is listed, grouped by what it is for (<em>Requirements and design</em>, <em>Risk management</em>, <em>Validation</em>, <em>Regulatory</em>); the four this lane uses are already ticked (<em>Software requirement</em>, <em>Design element</em>, and <em>Risk & Risk control</em>, which is one tick for two kinds). Each ticked row carries the <strong>name in this project</strong> — <em>Software requirement</em>, say, with the product's own default (<em>"System requirement"</em>) named underneath; change it if your people say <em>Systemanforderung</em> — the <strong>key prefix</strong> (<strong>REQ-</strong>, <strong>DE-</strong>, <strong>RISK-</strong>, <strong>RC-</strong>, each showing the key it would mint first: <em>First key: REQ-001</em>), an <strong>Add a category</strong> button, and the <strong>document types that may define it</strong> — that last one is the relationship the panels above only report. Two things are worth reading rather than clicking past. Under <em>Risk management</em>: <strong>risks and risk controls come as a pair</strong> — they share <strong>one</strong> tick (<em>Risk & Risk control</em>), because a control exists to reduce a risk, so this project uses both or neither. And under the whole section: a name and a prefix are free to change until this project mints its first item of that kind, and <strong>frozen together</strong> after that, because existing keys are never renamed. Try it if you like — tick <strong>Validation case</strong> and watch <strong>User need</strong> switch itself on, saying which kind brought it (<em>"Activated together with Validation case, which needs it."</em>) — then untick both again: unticking the case does <strong>not</strong> take the need back off, and a kind left on with no document type allowed to define it says so in its own warning line. Depth: <a href="../topics/key-rules/">Special elements</a>. Click <strong>Next</strong>.</li> </ol> <p><strong>Why "Staff yourself now" is not optional in practice.</strong> Activating a role makes it <em>bindable</em> in the project — <strong>it staffs nobody</strong>. So a project born ten seconds ago contains no people at all, its creator included, and a project's own configuration is gated <em>inside</em> that project. Without the checkbox the run would create your project and then hand its review policies, folders and acknowledgement policies back to you as work to come and do later. The section states the reason itself: <em>"Activating a role staffs nobody, so a brand-new project leaves even its creator holding nothing in it."</em> Ticking it puts a <strong>Staff yourself</strong> act into the plan right after the role activations, so everything it unlocks runs in this same pass.</p> <ol> <li>Step <strong>Apply & verify</strong> lists the plan one act at a time — the project (naming the organization it will belong to, in words), each role activation, <strong>Staff yourself</strong>, each document-type activation and what it may define, the folders, the special elements. The organization is not in this plan: you founded it a few minutes ago, in its own act. The <strong>review policies</strong> are not in it <em>yet</em> either, and that is the staffing bridge at work: you hold nothing in a project that does not exist, so the run derives the rest of the plan again the moment <strong>Staff yourself</strong> succeeds — a <strong>Review policy — …</strong> row then appears after each type. Read the list, then click <strong>Apply</strong>. → Each row reports its own outcome: <strong>Pending</strong> → <strong>Running…</strong> → <strong>Done</strong>, or <strong>Already there</strong> where something was already true. A failure stops the run at that row and leaves it resumable — nothing after it has run. Every act is recorded in the audit trail under your name, with its before and after values.</li> <li>Under the finished list, read the <strong>Setup check</strong> — the project's own status, re-read against what was just written. It either says <em>"This project's setup is complete."</em> or names what the system will still flag, <strong>grouped one entry per cause</strong> instead of as a wall of rows. Here you should expect <strong>Document Author — no holder yet</strong> and <strong>Quality Reviewer — no holder yet</strong>, because you staffed only yourself: each group is summarised by how many workflow gates and standing permissions stay blocked until somebody holds that role, with <strong>Details</strong> to read the individual findings and <strong>Staff it — Admin › Users</strong> to go and fix it (that act is Part 1d). Below them, a <strong>The project itself</strong> section adds one more honest finding about the role you <em>did</em> staff: <em>"This role is staffed here but nothing says what it is for: no released document describes its duties in this project."</em> — a duty description is a document you have not written yet. Take the line above the list at face value: <em>"Unstaffed roles are normal on day one: invited users bind on first login, and the project is already usable."</em> This step <strong>checks; it does not gate</strong> — finishing on warnings is fine, and meeting them here rather than at your first submit is the entire point.</li> <li>Click <strong>Done — open the project configuration</strong>. → You land on <strong>Scope configuration</strong> for the project you just made, which is exactly where Part 1 starts.</li> </ol> <p>If <strong>Project setup</strong> hands you <strong>"Hand this to an administrator"</strong> panels instead of live forms, nothing is broken: creating projects is a governance right, and the panel names the right, the roles that carry it in your installation, and what to ask for. The step is real — it just belongs to someone else. The same holds for <strong>Found a new organization</strong>: it carries a right of its own, so an installation may well let you set projects up while an administrator founds the organizations. Ask them to found <code>Muster Diagnostics AG</code>, then start this part again at step 4 — the picker will offer it. Depth: <a href="../topics/provisioning-birth-path/">How a new organization and project are born</a>.</p> <p>✔ <strong>Checkpoint</strong> — Open the <strong>Project context</strong> switcher in the top bar (the <em>workspaces</em> icon beside the search box): your new project is in the list under the name you gave it. Pick it, then open <strong>Documents</strong> — the navigation tree carries the five folders the wizard created and not a single document. That is what a newborn project looks like. (More on the switcher: <a href="../project-context/">The project context</a>.)</p> <blockquote> <p><strong>On the demo stack:</strong> the demo world — the MedTech projects and the four personas — is already there, so the later parts have content to work with from the first click. The project you just registered is yours, alongside it; nothing you did in Part 0 touched it.</p> </blockquote> <p><strong>Where the rest of the tutorial happens.</strong> From Part 1 on, the hands-on steps run in <strong>Cardio Monitor</strong> (code <code>MEDTECH-CARDIO</code>) — a project that already has neighbours to link to, a corpus to trace and released documents to acknowledge. Treat it as the project you just registered. If you want the harder path, run every remaining lesson in your own new project instead: every step works the same, but it starts empty, so Part 5's tour has only what you author yourself in it.</p> <hr /> <h2 id="part-1--configure-the-project-as-the-quality-manager">Part 1 — Configure the project (as the Quality Manager)<a class="headerlink" href="#part-1--configure-the-project-as-the-quality-manager" title="Permanent link">¶</a></h2> <p><em>Stay logged in as <code>carla.fischer</code>.</em> Configuration is governance: the rules a project runs by. It lives behind the <strong>gear</strong> icon in the top bar (its tooltip reads <strong>Scope configuration</strong>) — a settings affordance next to <em>Admin</em>, deliberately not another navigation word.</p> <ol> <li>First switch the <strong>Project context</strong> (the <em>workspaces</em> switcher in the top bar) to <strong>Cardio Monitor</strong> — Part 0 left it on the project you just registered, and from here on the hands-on steps run in Cardio. Then click the <strong>gear</strong> (<strong>Scope configuration</strong>): with a project named in the switcher, that project's configuration opens directly; if the switcher says <em>All projects</em>, a <strong>Select a project</strong> prompt appears — pick <strong>Cardio Monitor</strong> there and the toolbar follows. → You should now see a page titled <strong>Scope configuration</strong> with a row of tabs (<strong>Review policies</strong>, <strong>Training policies</strong>, <strong>Obligations</strong>, <strong>Document types</strong>, <strong>Emergency cover</strong>).</li> </ol> <h3 id="1a-review-policies--and-four-eyes-vs-direct">1a. Review policies — and four-eyes vs. direct<a class="headerlink" href="#1a-review-policies--and-four-eyes-vs-direct" title="Permanent link">¶</a></h3> <p><em>Manual topic:</em> <a href="../topics/review-policies/">Review policies — what they control</a></p> <ol> <li>Open the <strong>Review policies</strong> tab. Each document type in the project is an expandable panel marked <strong>Configured</strong> or <strong>Using built-in default</strong>. Expand <strong>SW Requirement</strong>.</li> <li>Read the two toggles and the dropdown:</li> <li><strong>Four-eyes review (approver must differ from the author)</strong> — leave this <strong>on</strong>.</li> <li><strong>Block release while review comments are unresolved</strong> — leave this <strong>on</strong>.</li> <li><strong>Release mode</strong> — <strong>Explicit (a releaser releases)</strong> vs <strong>Automatic (on last approval)</strong>. Leave it <strong>Explicit</strong>. Under <strong>Workflow defaults for new documents</strong>, confirm the <strong>Reviewers — who must approve</strong> grid names one role (e.g. <em>Quality Reviewer</em>) with <strong>Min. approvers</strong> 1. Leave it and click <strong>Save</strong> — the filled button at the very BOTTOM of the expanded policy panel, below <strong>Standing permissions on this type</strong> (scroll down inside the panel if you don't see it).</li> </ol> <p><strong>The one paragraph to internalise — four-eyes vs. direct.</strong> <em>Four-eyes</em> means the person who submits a version for review can <strong>never</strong> be the person who approves it: a second, independent pair of eyes must approve before release. That independence is right for <em>prescriptive</em> documents — procedures, specifications — whose correctness someone else must attest. A <strong>record</strong> is different: a record is <em>proof that a process ran</em> (a meeting minute, a verification record), not an instruction to be independently approved (ISO 13485 §4.2.5). Forcing the full submit → approve → release ceremony on every record is pure friction. So for <strong>record</strong> types LQMS offers a second choice:</p> <ol> <li>Still on the <strong>Review policies</strong> tab, expand the <strong>Quality Record</strong> type (a <em>Record</em>-category type). Because it is a record, an extra control appears: <strong>Release flow (records)</strong>. Change it from <strong>Standard (submit → approve → release)</strong> to <strong>Direct (single-person release from draft)</strong>. A quiet line reminds you to ask first whether the record — and the step producing it — is needed at all. Click <strong>Save</strong>.</li> </ol> <p>You have just made records of this type releasable in one attributed step (you will use this in Part 3 and Part 6). Note this is a <em>permission, not a rule</em>: the full review flow stays available on a direct-mode type whenever you want the extra ceremony. Depth: <a href="../documents-lifecycle/#4a-direct-release-records-only">Documents & the lifecycle §4a</a> and <a href="../training/#4-scope-configuration-the-gear-icon--the-rules-per-document-type">training §4</a>.</p> <h3 id="1b-training-policy-on-one-type">1b. Training policy on one type<a class="headerlink" href="#1b-training-policy-on-one-type" title="Permanent link">¶</a></h3> <ol> <li>Open the <strong>Training policies</strong> tab. Find the <strong>SW Requirement</strong> row and set:</li> <li><strong>Requires acknowledgement</strong> — turn <strong>on</strong>.</li> <li><strong>Addressee roles</strong> — open the multi-select and add <strong>Document Author</strong> and <strong>Quality Reviewer</strong> (roles that actually have holders in this project, so a release later produces real tasks).</li> <li><strong>Training deadline (days)</strong> — optional; leave it empty for "no objective <em>training</em> deadline", or enter a number to make the training <em>overdue</em> after that many days. (Leaving it empty does not make the inbox task dateless: an acknowledgement task always carries the installation's own working deadline, which the addressee sees as a <em>Due</em> date.) Click <strong>Save</strong>.</li> </ol> <p>These are <em>creation-time defaults</em>: a new document of the type copies this addressee list into its own editable addressee set — <strong>when its creator may read the policy</strong>. That read is part of training management, so an author who does not hold it (Ben, in Part 2) gets a draft with an <em>empty</em> addressee set and no warning; Part 2d has you fill it in by hand. (The training <strong>mode</strong> — none / acknowledge / questionnaire — is chosen <em>per document</em> in the draft editor, not here; you will meet it in Part 4.)</p> <h3 id="1c-let-a-type-define-requirement-trace-items">1c. Let a type define requirement trace items<a class="headerlink" href="#1c-let-a-type-define-requirement-trace-items" title="Permanent link">¶</a></h3> <ol> <li>Open the <strong>Document types</strong> tab. This tab <strong>displays</strong> each type — its prefix and name, its category chip, review interval and retention, and an <strong>Activated</strong> / <strong>Not activated</strong> status. <em>Activating a type happens where the project is set up — </em><em>Admin → Project setup</em><em>, as in Part 0</em> — so there is no activate button here; the chips are read-only status.</li> <li>For an <strong>Activated</strong> type you <em>can</em> change what it may define. On the <strong>SW Requirement</strong> row, check that <strong>May define requirements</strong> is <strong>on</strong> — on the demo stack Cardio already has it on, so there is nothing to click; leave it that way, because Part 2c writes a requirement item into this very type. The row carries <strong>one toggle per special element the project has activated</strong> (Cardio activated only the requirement kind, so that is the only one here; a project that also uses risks would show <strong>May define risks</strong>, and so on). Beside them sits a read-only chip — <em>Does not count as verification evidence</em> — a catalog-wide fact stated here, not a switch.</li> <li>At the TOP of the same tab (above the document-type rows), note the <strong>Design kinds</strong> editor — the vocabulary a design element's <em>kind</em> is chosen from (default: architecture, interface, component, unit). You can <strong>Add</strong> a value and <strong>Save design kinds</strong>; leave it at the default for now.</li> </ol> <blockquote> <p>The scope's <strong>key prefixes</strong> (the ones the <em>Suggest</em> button uses when you author a trace item) come from the <strong>Special elements</strong> section you read in Part 0 — one row per kind, carrying the project's name for it, its prefix and the types that may define it — so every key in the project is consistent and collision-free. This tab is the other face of the same model: the switches here and the <em>document types that may define it</em> selection there write the same fact. If your project declared no kind at all, you simply type the key yourself. Depth: <a href="../topics/key-rules/">Special elements</a>.</p> </blockquote> <h3 id="1d-staff-a-person-into-a-role">1d. Staff a person into a role<a class="headerlink" href="#1d-staff-a-person-into-a-role" title="Permanent link">¶</a></h3> <p><em>Manual topic:</em> <a href="../topics/staffing-and-assignments/">Staffing, assignments & the accountable holder</a></p> <p>Configuration decides <em>what</em> a role may do; <strong>staffing</strong> decides <em>who holds it</em>. Staffing is an administration act (it needs <code>MANAGE_USERS</code>, which <code>carla.fischer</code> holds as a <strong>User Administrator</strong>).</p> <ol> <li>Click <strong>Admin</strong> in the top bar, then <strong>Users</strong>. → You see a table of users with their <strong>Role assignments</strong> shown as <code>scope: role</code> chips.</li> <li>On any user's row, click <strong>Assignments</strong>. In the <strong>Manage role assignments</strong> dialog, pick a <strong>Scope</strong> (e.g. <em>MEDTECH-CARDIO</em>), pick a <strong>Role</strong>, and click <strong>Add</strong> — the assignment appears in the list immediately. Click <strong>Done</strong>.</li> </ol> <blockquote> <p><strong>On the demo stack:</strong> <code>ben.keller</code>, <code>anna.sommer</code> and <code>carla.fischer</code> are already staffed in every project, so you can just <em>observe</em> the assignment chips rather than add new ones. (The role <em>catalog</em> and its per-scope activation live under <strong>Admin → Roles</strong>, which needs the broader <code>MANAGE_CATALOG</code> permission held only by the <code>demo</code> administrator — another governance surface, not the Quality Manager's job.)</p> </blockquote> <p>✔ <strong>Checkpoint</strong> — On <strong>Review policies</strong>, the <strong>SW Requirement</strong> panel shows <strong>Configured</strong>; expand the <strong>Quality Record</strong> panel and <strong>Release flow (records)</strong> reads <strong>Direct (single-person release from draft)</strong> (the collapsed header states only <em>Configured</em> — the flow is inside). On <strong>Training policies</strong>, <strong>SW Requirement</strong> shows <strong>Requires acknowledgement</strong> on with two addressee roles. On <strong>Document types</strong>, <strong>SW Requirement</strong> shows <strong>May define requirements</strong> on.</p> <hr /> <h2 id="part-2--author-a-draft">Part 2 — Author a draft<a class="headerlink" href="#part-2--author-a-draft" title="Permanent link">¶</a></h2> <p>Now you write a document. <em>Log out and log in as </em><em><code>ben.keller</code></em><em> (the Document Author).</em></p> <h3 id="2a-create-the-draft">2a. Create the draft<a class="headerlink" href="#2a-create-the-draft" title="Permanent link">¶</a></h3> <ol> <li>Go to <strong>Documents</strong>. Click <strong>New draft</strong> (top right).</li> <li>On the create page, choose:</li> <li><strong>Scope</strong> — <em>MEDTECH-CARDIO — Cardio Monitor</em>.</li> <li><strong>Document type</strong> — <em>SWREQ — SW Requirement</em>.</li> <li><strong>Folder</strong> — leave <em>Unfiled</em> (you can file it later).</li> <li><strong>Title</strong> — type <code>Heart-rate alarm requirement</code>.</li> <li>Click <strong>Create draft</strong>. → You land on the new document, shown as <strong>v1</strong> in state <strong>Draft</strong>.</li> </ol> <p>The human ID is assigned automatically — the project code, then the type's prefix, then the next free number. There is no ID field to fill in. On the demo stack Cardio already carries three SW Requirements, so yours is <code>MEDTECH-CARDIO-SWREQ-004</code>; in an empty project it would be <code>-001</code>.</p> <h3 id="2b-write-in-the-visual-editor">2b. Write, in the visual editor<a class="headerlink" href="#2b-write-in-the-visual-editor" title="Permanent link">¶</a></h3> <ol> <li>Click <strong>Edit draft</strong>. The editor opens in the <strong>visual (WYSIWYG)</strong> mode by default: a toolbar (headings, <strong>Bold</strong>, <em>Italic</em>, lists, <strong>Table</strong>, colour, links, images) over a document surface.</li> <li>Type a heading and a sentence of body text.</li> <li>Type <strong><code>/</code></strong> in an empty line to open the <strong>slash menu</strong> — the insert menu for blocks (table, code block, diagram, formulas, and the trace items below).</li> <li>The mode buttons switch between <strong>Switch to Markdown source</strong> and <strong>Switch to visual editing</strong> if you prefer typing Markdown; leaving source mode re-imports your text. Depth: <a href="../documents-lifecycle/#2-editing-a-draft">Documents & the lifecycle §2</a>.</li> </ol> <h3 id="2c-insert-a-requirement-trace-item">2c. Insert a requirement trace item<a class="headerlink" href="#2c-insert-a-requirement-trace-item" title="Permanent link">¶</a></h3> <p>Because <strong>May define requirements</strong> is on for this type (Part 1c), the editor offers requirement items. The slash menu lists one entry per kind the type may define — here, just <strong>Requirement</strong>.</p> <ol> <li>On an empty line, type <strong><code>/</code></strong> and choose <strong>Requirement</strong>. → The <strong>New requirement</strong> dialog opens.</li> <li>Fill it in:</li> <li><strong>Key</strong> — click <strong>Suggest</strong>. Cardio has a key convention, so it fills in the next free key (<code>REQ-004</code> on the demo stack); the field hint states the rule you live under: <em>"Unique within the scope; defined in exactly one document."</em> Type a key by hand only where no convention exists — and never one an existing document already defines: the save is refused with, e.g., <em>"Requirement key REQ-001 is already defined in MEDTECH-CARDIO-SWREQ-001."</em></li> <li><strong>Kind</strong> — choose <strong>Functional</strong>.</li> <li><strong>Priority</strong> — a short token in your own language, e.g. <code>high</code>.</li> <li><strong>Rationale</strong> and <strong>Acceptance criteria</strong> — optional; fill them if you like.</li> <li>Type the requirement statement in the block body. Click <strong>Save</strong>. → A keyed requirement block appears inline in the document.</li> </ol> <p>Depth on the fixed attribute sets and why the item's lifecycle <em>is</em> the document's: <a href="../trace-items/">Trace items</a>.</p> <h3 id="2d-attach-a-file-and-link-another-document">2d. Attach a file and link another document<a class="headerlink" href="#2d-attach-a-file-and-link-another-document" title="Permanent link">¶</a></h3> <ol> <li>Still in the editor, open the <strong>Details</strong> panel (the <em>tune</em> button in the editor's header). It is the boxed <strong>Document settings — Changes apply immediately</strong> section: everything in it takes effect the moment you make it, without <em>Save</em>. Two things to do here:</li> <li><strong>Addressees — who must acknowledge</strong> — add <strong>Document Author</strong> and <strong>Quality Reviewer</strong>. On a draft created by an author this list is empty (see Part 1b), and Part 4 needs it filled.</li> <li><strong>Attachments</strong> → <strong>Attach a file</strong>, and pick any small file. It appears as a download-only attachment (it is <em>not</em> inlined into the text). Once a document has one, an <strong>Attachments</strong> section appears on the document page too.</li> <li>Back on the writing surface, use <strong>Insert document link</strong> (the link button, or the <strong><code>/</code></strong> menu) to link to another controlled document by its stable ID — search for one in the <strong>Find a document</strong> box and insert it. The link survives the target's later renames and folder moves, and it also records a document-level <strong>reference</strong> you will see on the <em>References</em> card.<blockquote> <p>Typing <strong><code>[[</code></strong> as a shortcut works in the <strong>Markdown source</strong> mode — a completion menu opens; type a few letters of the target's title or ID and pick it. In visual mode, use the link button or the <strong><code>/</code></strong> menu instead.</p> </blockquote> </li> <li><strong>Save</strong> the draft (the <em>Save</em> action). Saving is optimistic-locked: if someone else saved while you were editing, your save is refused with a clear message rather than overwriting them.</li> </ol> <p>✔ <strong>Checkpoint</strong> — The document detail shows <strong>Draft · v1</strong>, a requirement block keyed with the key you took from <strong>Suggest</strong>, one file under <strong>Attachments</strong>, an in-text document link, and the line <em>Addressees: Document Author, Quality Reviewer</em>. Diagrams: <a href="../diagrams/">Diagrams</a>.</p> <hr /> <h2 id="part-3--review--release">Part 3 — Review & release<a class="headerlink" href="#part-3--review--release" title="Permanent link">¶</a></h2> <p>A controlled document moves <strong>Draft → In review → Released</strong>. You will drive a full four-eyes round, then see the direct-release shortcut for records.</p> <h3 id="3a-submit-as-the-author">3a. Submit (as the author)<a class="headerlink" href="#3a-submit-as-the-author" title="Permanent link">¶</a></h3> <ol> <li>Still as <strong><code>ben.keller</code></strong>, open your draft and click <strong>Submit for review</strong>. → The document becomes <strong>In review</strong> and read-only. Submitting freezes the content, the change reason, and the workflow roles for this round.</li> </ol> <p>If a workflow group is unstaffed the button is blocked with the reason (e.g. <em>"A workflow group has no active role holder in this scope…"</em>). Because four-eyes is on, <strong>you cannot approve your own round</strong>; Ben holds no approve-capable role here, so the review console simply offers him no reviewer section at all. Where a submitter <em>does</em> hold one, LQMS says so in its place: <em>"You submitted this version for review — a second person must approve it."</em></p> <h3 id="3b-review-and-approve-as-the-reviewer">3b. Review and approve (as the reviewer)<a class="headerlink" href="#3b-review-and-approve-as-the-reviewer" title="Permanent link">¶</a></h3> <ol> <li><em>Log out and log in as </em><em><code>anna.sommer</code></em><em> (the Quality Reviewer).</em></li> <li>Go to <strong>Inbox</strong> → <strong>My reviews</strong>. Your document is listed because Anna holds a Reviewer role on it. Open it.</li> <li>To comment on a passage, select some text and choose <strong>Add comment</strong>; type a note and <strong>Post</strong> it. (The <strong>Add comment</strong> button on the <em>Review comments</em> card posts an unanchored comment about the version as a whole.) A comment is anchored to that text, cannot be edited, and can be <strong>Resolve</strong>d (or <strong>Reopen</strong>ed) later — its author may delete it only while the version is still a draft and nobody has replied. Depth: <a href="../review-comments/">Review comments</a>.</li> <li>In the <strong>review console</strong> on the document, under <strong>As reviewer</strong>, check your <strong>Acting as role</strong>: with exactly one approve-capable role (anna's case here) it is preselected and shown as plain text — nothing to pick; only if you hold several does a picker appear. Optionally add a <strong>Comment</strong>, and click <strong>Approve</strong>. (<strong>Reject</strong> would send it back to Draft for the author.)</li> </ol> <h3 id="3c-release">3c. Release<a class="headerlink" href="#3c-release" title="Permanent link">¶</a></h3> <ol> <li>Your own comment from step 4 is still open, and Part 1a left <strong>Block release while review comments are unresolved</strong> on — so <strong>Resolve</strong> it first (the <em>Resolve</em> action on the comment). Then, with the required approvals in and nothing left open, the <strong>As releaser</strong> section offers <strong>Release</strong>. Click it. → The document becomes <strong>Released</strong> — the controlled, effective version.</li> </ol> <p>If release is not yet allowed, the action tells you exactly what is missing — e.g. <em>"awaiting 1 approval(s) from Quality Reviewer"</em> or <em>"3 unresolved review comment(s) must be resolved before release."</em> (To correct a round instead of rejecting it, an author uses <strong>Withdraw</strong>, which voids the round's approvals and returns the document to Draft.)</p> <p>✔ <strong>Checkpoint</strong> — The document detail shows <strong>Released</strong>. <strong>Download PDF</strong> is now available; every page of that PDF carries the distribution-control footer band — <em>"</em><em>Uncontrolled copy</em><em> — issued via LQMS to <you> on <date>; validity must be verified against the live system."</em> Depth: <a href="../documents-lifecycle/#3-the-review-round--from-both-sides">Documents & the lifecycle §3–§8</a>.</p> <h3 id="3d-the-counter-example--direct-release-of-a-record">3d. The counter-example — direct release of a record<a class="headerlink" href="#3d-the-counter-example--direct-release-of-a-record" title="Permanent link">¶</a></h3> <p>Records skip the ceremony when you allowed it in Part 1.</p> <ol> <li><em>Log in as </em><em><code>carla.fischer</code></em><strong> (the Quality Manager — she may release records in this project). Click </strong>New draft<strong>, choose scope </strong>Cardio Monitor<strong>, type </strong>Quality Record<strong>, give it a title, and </strong>Create draft**.</li> <li>On the draft you now see a <strong>Release</strong> button <em>beside</em> Submit for review. Click it. → A confirmation dialog titled <strong>Release directly</strong> appears: <em>"This record type allows direct release: releasing now skips the submit → approve steps and makes this a single-person, attributed release. Continue?"</em> Confirm.</li> </ol> <p>✔ <strong>Checkpoint</strong> — The record went straight from <strong>Draft</strong> to <strong>Released</strong> in one attributed step — no reviewer needed. Depth: <a href="../documents-lifecycle/#4a-direct-release-records-only">Documents & the lifecycle §4a</a>.</p> <hr /> <h2 id="part-4--training--acknowledgement">Part 4 — Training & acknowledgement<a class="headerlink" href="#part-4--training--acknowledgement" title="Permanent link">¶</a></h2> <p>Releasing a document that has <strong>addressee roles</strong> raises an <em>Acknowledgement required</em> task for each person holding one of those roles. The type policy you set in Part 1 supplies the default list; the document's own set — the one you filled in by hand in Part 2d — is what actually decides.</p> <ol> <li>The moment your Part-3 SW Requirement released, an acknowledgement task was created for its addressees — Ben and Anna. <em>Log in as </em><em><code>ben.keller</code></em><strong> and open the </strong>Inbox<strong>. → Under </strong>Awaiting your acknowledgement** you see the released document.</li> <li>Open it. On the released version a prominent panel invites you to <strong>Acknowledge (read & understood)</strong>, with the hint <em>"You are addressed by this document — please confirm you have read and understood it."</em> Click it. → The panel changes to <em>"Acknowledged on <date>"</em>.</li> </ol> <blockquote> <p><strong>On the demo stack</strong> there is a ready acknowledgement waiting regardless of your own release: log in as <code>ben.keller</code> and acknowledge the <strong>Design Control Procedure</strong> (in <strong>QMS-OPS</strong>) — Anna acknowledged hers already, Ben's is left outstanding on purpose.</p> </blockquote> <p><strong>The questionnaire variant, in two sentences.</strong> A type can train by <strong>Questionnaire</strong> instead of a simple acknowledgement; the author builds the quiz in the draft editor's <strong>Training</strong> section (pass threshold + questions), and a version cannot be released until it carries one. The addressee then <strong>passes</strong> the questionnaire (a passing attempt records the training; failed attempts are recorded too and retries are unlimited).</p> <p><strong>Where coverage shows.</strong> As an addressee you see your own line — <em>Acknowledged on <date></em> — and the document's addressee roles. The <strong>who has acknowledged and who has not</strong> roll-up belongs to training management: a Quality Manager sees the per-document status and, across the project, the <strong>Training compliance</strong> view in Part 5's workspace. Depth: <a href="../training/">Training & acknowledgements</a>.</p> <p>✔ <strong>Checkpoint</strong> — Your Inbox no longer lists that document under <strong>Awaiting your acknowledgement</strong> (the seeded <em>Design Control Procedure</em> stays there until you do that one too), and the released version shows <em>Acknowledged on <date></em> in place of the button.</p> <hr /> <h2 id="part-5--trace--prove">Part 5 — Trace & prove<a class="headerlink" href="#part-5--trace--prove" title="Permanent link">¶</a></h2> <p>Traceability is how you <em>prove</em> the QMS holds together: requirements covered by evidence, risks controlled, needs validated. You will author one link yourself, then tour the fully-built picture in the <strong>SAMPLE</strong> project.</p> <p>Two lanes run in parallel here, and it helps to name them up front. <strong>Stakeholder requirements</strong> are the <em>specification</em> lane — what the product must do, stated as requirements (any stakeholder is a source: clinicians, service, regulators, business), decomposed into software requirements and <em>verified</em>: "did we build the product right?" That is the <strong>Requirement chains</strong> view. <strong>User needs</strong> are the <em>validation</em> lane — the need in the user's own terms, never decomposed, <em>validated</em> against the finished device in use: "did we build the right product?" That is the <strong>Validation matrix</strong> view. The distinction is verification vs. validation (IEC 62304 vs. ISO 13485 §7.3.6/7.3.7); depth: <a href="../trace-items/#72-stakeholder-requirements-vs-user-needs-verification-vs-validation">Trace items §7.2</a>.</p> <h3 id="5a-author-a-verifies-link-in-your-project">5a. Author a Verifies link (in your project)<a class="headerlink" href="#5a-author-a-verifies-link-in-your-project" title="Permanent link">¶</a></h3> <ol> <li>As <strong><code>ben.keller</code></strong>, create a <strong>New draft</strong> in <strong>Cardio Monitor</strong> of type <strong>SW Test</strong>; give it a title and <strong>Create draft</strong>.</li> <li>On the draft's <strong>document page</strong>, find the <strong>Trace links</strong> card and click <strong>Add link</strong> — note it lives on the document page (right column), NOT inside the edit view: close the editor (<strong>Save</strong>, then back) if you are still in it. The card opens a small form in place:</li> <li><strong>Source item</strong> — leave <strong>(the document)</strong> (a document-level claim).</li> <li><strong>Link type</strong> — leave <strong>Verifies</strong>.</li> <li>Leave <strong>A keyed item</strong> selected and search, under <strong>Target item</strong>, for the requirement you wrote in Part 2c (<code>REQ-004</code> on the demo stack).</li> <li><strong>Target scope</strong> — leave <em>Cardio Monitor</em> (where the target item lives). Click <strong>Add</strong>.</li> </ol> <p>Adding or removing a link is a <strong>structure change</strong>, so it is allowed only while the source has a <strong>Draft</strong> version — the server enforces this (it refuses a link on a released document with <em>409 Conflict</em>, telling you to revise first). Depth: <a href="../trace-links/">Trace links & the suspect cycle</a>.</p> <p>✔ <strong>Checkpoint</strong> — The <strong>Trace links</strong> card lists <strong>(the document) · VERIFIES ·</strong> your requirement's key.</p> <h3 id="5b-read-the-coverage--and-the-new-validation-matrix">5b. Read the coverage — and the new validation matrix<a class="headerlink" href="#5b-read-the-coverage--and-the-new-validation-matrix" title="Permanent link">¶</a></h3> <p>Open <strong>Evidence → Traceability</strong> in the top bar (<em>Evidence</em> is the menu that also holds <em>Dossiers</em> and <em>Authority</em>). This is the workspace hub — <em>"QMS health at a glance — pick a view."</em> Each tile carries a metric and links to a focused page. Sub-pages show <strong>one project at a time</strong>: if the toolbar says <em>All projects</em>, a <strong>Select a project</strong> prompt appears — pick one.</p> <blockquote> <p><strong>On the demo stack:</strong> switch the toolbar's <strong>Project context</strong> to <strong>SAMPLE</strong> for the richest, fully-seeded example. SAMPLE was built precisely to show every verdict at once.</p> </blockquote> <ol> <li>Open the <strong>Requirement coverage</strong> tile. A requirement counts as <strong>covered</strong> when it has at least one inbound <strong>Verifies</strong> <em>or</em> <strong>Satisfies</strong> link; the evidence chips split <strong>planned ×N</strong> / <strong>verified ×N</strong> / <strong>satisfied ×N</strong>. In SAMPLE you should read <strong>2 of 6 requirements covered</strong> with four gaps listed — REQ-001 is <em>verified</em> and the stakeholder requirement STK-001 is <em>satisfied</em> by REQ-001, while REQ-002/003/004 and STK-002 remain uncovered. The <strong>kind</strong> filter separates <em>stakeholder</em> requirements from the <em>functional</em> / <em>safety</em> software ones (a <em>planned</em> verification is a designation; a <em>verified</em> one is a released report). Depth: <a href="../traceability-workspace/#2-requirement-coverage">The traceability workspace §2</a>.</li> <li>Back at the hub, open the <strong>Requirement chains</strong> tile — it walks <em>stakeholder requirement → satisfying software requirements → verification evidence</em> end to end, carrying honest roll-up flags (<em>Not satisfied</em>, <em>Satisfied, unverified</em>, <strong>Planned only</strong>, <em>Suspect on path</em>). This view is driven by requirements of <strong>kind <em>Stakeholder</em></strong>. In SAMPLE you should read <strong>1 of 2 stakeholder requirements satisfied</strong> and <strong>1 fully verified</strong>: expand <strong>STK-001</strong> to see the software requirement <strong>REQ-001</strong> that <em>satisfies</em> it, and REQ-001 in turn verified by the released Verification Report — a complete, genuinely verified chain (no flag). <strong>STK-002</strong> carries <strong>Not satisfied</strong> — no software requirement satisfies it yet (the honest gap). The flat matrix is a <strong>Download matrix (CSV)</strong> on this page — the artifact auditors mean by "traceability matrix".</li> <li>Back at the hub, open the <strong>Validation</strong> tile — the <strong>Validation matrix</strong> (the <em>"right product"</em> axis — <em>user need → validating validation-cases / records</em>). In SAMPLE you should read <strong>2 of 3 user needs validated · 1 genuinely validated · 1 planned only</strong>, and that three-part headline is the honest part: one need is validated by a released Validation Report (<em>verified</em> class), one carries <strong>Planned only</strong> (a validation-case in a plan, not yet executed) and counts toward the 2, and one is <em>Not validated</em> (the honest gap). Below, a <strong>Design realization</strong> section shows a design element satisfying a requirement.</li> <li>Back at the hub, open <strong>GSPR conformity</strong> (regulatory clause → complying requirements, with each complier's verification state). In SAMPLE, note the deliberate hard gap: a not-applicable clause carrying <strong>N/A — no justification</strong> — an unjustified exclusion an auditor would flag.</li> <li>Open <strong>Risk traceability</strong> (<em>hazard → control → requirement / verification → residual risk</em>). In SAMPLE you should see three risks: one full chain, one with <strong>control not implemented</strong> / <strong>control not verified</strong> gaps, and one <strong>Accepted without reduction</strong> (an already-acceptable initial risk that is <em>complete</em>, not a gap). Scores render as recorded tokens (RISK-001 reads <em>Initial: S4 · P2 · P3 — High</em>, <em>Residual: S4 · P1 · P2 — Low</em>) — the tool records, it does not compute. Depth: <a href="../trace-items/#4-risks--the-recorded-score-not-a-computed-one">Trace items §4</a>.</li> </ol> <h3 id="5c-export-the-proof">5c. Export the proof<a class="headerlink" href="#5c-export-the-proof" title="Permanent link">¶</a></h3> <ol> <li>On the hub header, click <strong>Traceability report (PDF)</strong>. → One derived PDF downloads: a front-page gap digest, then the requirement chains, requirement-verification status, risk chains and relation coverage. It is labelled <em>derived — as at export</em> and is <strong>not</strong> a controlled document (two exports on different days may legitimately differ).</li> </ol> <p><strong>The audit pack, in one paragraph.</strong> From the top bar's <strong>Evidence</strong> menu, under the <strong>Audit pack</strong> heading (it appears whenever a single project is in context), you can export the whole scope at once: <strong>Audit pack (single PDF)</strong> — one merged file with a cover, a clickable table of contents and every effective-released document as a bookmarked chapter, whose internal links work in any PDF viewer (this leads the menu) — or <strong>Audit pack (zip)</strong> — one PDF per document plus a SHA-256 hash manifest, carrying the caution <em>"Cross-document links open only in Adobe Acrobat."</em> Depth: <a href="../exports/">PDF exports & the audit pack</a>.</p> <p>✔ <strong>Checkpoint</strong> — You have read requirement coverage, the requirement chains, the validation matrix, GSPR conformity and risk traceability for SAMPLE, and downloaded the traceability report PDF. Depth: <a href="../traceability-workspace/">The traceability workspace</a>.</p> <hr /> <h2 id="part-6--operate-a-recurring-obligation">Part 6 — Operate: a recurring obligation<a class="headerlink" href="#part-6--operate-a-recurring-obligation" title="Permanent link">¶</a></h2> <p>Some QMS duties recur on a schedule and must leave evidence each time (a backup rehearsal, an environment check). LQMS models these as <strong>recurring obligations</strong>: a duty whose <em>evidence</em> is a released record. There is no "done" button — <strong>releasing the record is the proof it ran</strong>.</p> <p><em>Log in as </em><em><code>carla.fischer</code></em>** (defining obligations needs review-policy permission).</p> <ol> <li>Open the <strong>gear</strong> (<strong>Scope configuration</strong>) for <strong>Cardio Monitor</strong>, then the <strong>Obligations</strong> tab. Click <strong>Add obligation</strong>.</li> <li>In the <strong>New obligation</strong> dialog:</li> <li><strong>Name</strong> — <code>Monthly environment check</code>.</li> <li><strong>Completion record type</strong> — pick <strong>Quality Record</strong> (only <em>Record</em>-category types appear; you set this one to <strong>Direct</strong> release in Part 1, which makes completing it frictionless).</li> <li><strong>Schedule</strong> — choose a calendar schedule: <strong>End of month</strong> (or <strong>Monthly on a day…</strong> and set a <strong>Day of month</strong>; pick a late day there and a hint appears noting that shorter months use their last day, so the deadline is never pushed later than the day you chose).</li> <li><strong>Due window (days)</strong> — e.g. <code>7</code> (when it starts warning before it is due).</li> <li> <p><strong>Responsible roles</strong> — add a role whose holders should be reminded (e.g. <em>Quality Manager</em>). Click <strong>Save</strong>.</p> </li> <li> <p>Now <strong>complete</strong> it by producing the evidence. Still as <strong><code>carla.fischer</code></strong> (who may release records here), create a <strong>New draft</strong> of type <strong>Quality Record</strong> in <strong>Cardio Monitor</strong>, title it <code>Environment check — <this month></code>, and use the direct <strong>Release</strong> button (Part 3d) to release it.</p> </li> <li> <p>Open <strong>Evidence → Traceability</strong>, then the <strong>Obligations</strong> tile (the oversight page; switch the toolbar to <strong>Cardio Monitor</strong> if prompted). The summary reads <strong>N OK · N due soon · N overdue</strong>, and your obligation's row shows a freshness chip. Releasing the record set its <strong>Last execution</strong> and advanced <strong>Next due</strong> — the chip is now <strong>OK</strong>. Every released record of the completion type counts, and each one discharges one occurrence: the Quality Record you released in Part 3d counts too, so <strong>Next due</strong> here lands one occurrence further out than you might expect.</p> </li> </ol> <blockquote> <p><strong>On the demo stack</strong> a ready example already exists in <strong>QMS-OPS</strong>: a <em>Monthly infrastructure verification</em> obligation, completed by a directly-released record, already showing <strong>OK</strong> on the Obligations oversight page — switch the project context to <strong>QMS-OPS</strong> to observe it.</p> </blockquote> <p>✔ <strong>Checkpoint</strong> — On the <strong>Obligations</strong> oversight page, your obligation shows <strong>OK</strong>, with the record you just released named as its <strong>Last execution</strong> and a <strong>Next due</strong> date on the schedule. Depth: <a href="../obligations/">Recurring obligations</a>.</p> <hr /> <h2 id="part-7--wrap-up-what-you-now-know">Part 7 — Wrap-up: what you now know<a class="headerlink" href="#part-7--wrap-up-what-you-now-know" title="Permanent link">¶</a></h2> <p>You took a project from registration to a released, acknowledged, traced document — and kept an operational duty green. Here is the map from what you did to the reference chapter that goes deeper:</p> <table> <thead> <tr> <th>You did this</th> <th>Go deeper</th> </tr> </thead> <tbody> <tr> <td>Registered an organization and a project, chose its lane, and staffed yourself into it</td> <td><a href="../topics/provisioning-birth-path/">How a new organization and project are born</a>; <a href="../topics/setup-wizard-lanes/">The setup wizard's lanes</a>; <a href="../project-context/">The project context</a></td> </tr> <tr> <td>Set review, training and type-definition policies; staffed a role</td> <td><a href="../training/#4-scope-configuration-the-gear-icon--the-rules-per-document-type">Training & acknowledgements §4</a></td> </tr> <tr> <td>Created a draft, wrote it, and inserted a keyed requirement</td> <td><a href="../documents-lifecycle/">Documents & the lifecycle</a>; <a href="../trace-items/">Trace items</a>; <a href="../diagrams/">Diagrams</a></td> </tr> <tr> <td>Ran a four-eyes review round; direct-released a record</td> <td><a href="../documents-lifecycle/#3-the-review-round--from-both-sides">Documents & the lifecycle §3–§4a</a>; <a href="../review-comments/">Review comments</a></td> </tr> <tr> <td>Acknowledged a released document as an addressee</td> <td><a href="../training/">Training & acknowledgements</a></td> </tr> <tr> <td>Authored a trace link; read coverage, chains, the validation matrix, GSPR and risk; exported the proof</td> <td><a href="../trace-links/">Trace links & the suspect cycle</a>; <a href="../traceability-workspace/">The traceability workspace</a>; <a href="../exports/">PDF exports & the audit pack</a></td> </tr> <tr> <td>Defined a scheduled obligation and completed it with a record</td> <td><a href="../obligations/">Recurring obligations</a></td> </tr> <tr> <td>Switched personas through the user menu — which also names the build you are running</td> <td><a href="../project-context/#4-which-version-of-lqms-am-i-running">The project context & app version §4</a></td> </tr> </tbody> </table> <p>From here, the reference chapters answer "why" and "every option"; this tutorial only walked the happy path.</p> <hr /> <p><em>This is a hands-on tutorial; the authoritative behaviour and the governing decisions live in the reference chapters linked above and their ADR footers. The personas, projects and seeded content this tutorial follows are described in <a href="https://github.com/nburri/lqms/blob/main/deploy/DEMO.md"><code>deploy/DEMO.md</code></a>. Operators standing up an installation: see <a href="../../operations/deployment/"><code>docs/operations/deployment.md</code></a>.</em></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="../" class="md-footer__link md-footer__link--prev" aria-label="Previous: LQMS User Guide"> <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"> LQMS User Guide </div> </div> </a> <a href="../administration/" class="md-footer__link md-footer__link--next" aria-label="Next: Administering an LQMS Installation"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Administering an LQMS Installation </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>