Skip to content
LQMS
How a new organization and project are born
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"> <a href="../../tutorial/" class="md-nav__link"> <span class="md-ellipsis"> Tutorial — from zero to a released document </span> </a> </li> <li class="md-nav__item"> <a href="../../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="../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="../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="../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="../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="../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="../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="../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="../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="../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 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"> How a new organization and project are born </span> <span class="md-nav__icon md-icon"></span> </label> <a href="./" class="md-nav__link md-nav__link--active"> <span class="md-ellipsis"> How a new organization and project are born </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="#0-two-processes-and-why-they-are-not-one-form" class="md-nav__link"> <span class="md-ellipsis"> 0. Two processes, and why they are not one form </span> </a> </li> <li class="md-nav__item"> <a href="#1-the-act-sequence" class="md-nav__link"> <span class="md-ellipsis"> 1. The act sequence </span> </a> </li> <li class="md-nav__item"> <a href="#1a-founding-an-organization" class="md-nav__link"> <span class="md-ellipsis"> 1a. Founding an organization </span> </a> </li> <li class="md-nav__item"> <a href="#2-step-1-in-detail--the-form" class="md-nav__link"> <span class="md-ellipsis"> 2. Step 1 in detail — the form </span> </a> </li> <li class="md-nav__item"> <a href="#3-staffing-comes-before-policies--and-this-order-is-not-optional" class="md-nav__link"> <span class="md-ellipsis"> 3. Staffing comes before policies — and this order is not optional </span> </a> <nav class="md-nav" aria-label="3. Staffing comes before policies — and this order is not optional"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-bridge-staff-yourself-now" class="md-nav__link"> <span class="md-ellipsis"> The bridge: "Staff yourself now" </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-without-the-installation-permission-the-hand-off" class="md-nav__link"> <span class="md-ellipsis"> 4. Without the installation permission: the hand-off </span> </a> </li> <li class="md-nav__item"> <a href="#4b-when-the-missing-piece-is-the-catalog--and-you-are-the-one-who-governs-it" class="md-nav__link"> <span class="md-ellipsis"> 4b. When the missing piece is the CATALOG — and you are the one who governs it </span> </a> </li> <li class="md-nav__item"> <a href="#5-everything-is-attributed" class="md-nav__link"> <span class="md-ellipsis"> 5. Everything is attributed </span> </a> </li> <li class="md-nav__item"> <a href="#6-dissolving-an-organization-founded-by-mistake" class="md-nav__link"> <span class="md-ellipsis"> 6. Dissolving an organization founded by mistake </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="../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="../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="../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="../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="#0-two-processes-and-why-they-are-not-one-form" class="md-nav__link"> <span class="md-ellipsis"> 0. Two processes, and why they are not one form </span> </a> </li> <li class="md-nav__item"> <a href="#1-the-act-sequence" class="md-nav__link"> <span class="md-ellipsis"> 1. The act sequence </span> </a> </li> <li class="md-nav__item"> <a href="#1a-founding-an-organization" class="md-nav__link"> <span class="md-ellipsis"> 1a. Founding an organization </span> </a> </li> <li class="md-nav__item"> <a href="#2-step-1-in-detail--the-form" class="md-nav__link"> <span class="md-ellipsis"> 2. Step 1 in detail — the form </span> </a> </li> <li class="md-nav__item"> <a href="#3-staffing-comes-before-policies--and-this-order-is-not-optional" class="md-nav__link"> <span class="md-ellipsis"> 3. Staffing comes before policies — and this order is not optional </span> </a> <nav class="md-nav" aria-label="3. Staffing comes before policies — and this order is not optional"> <ul class="md-nav__list"> <li class="md-nav__item"> <a href="#the-bridge-staff-yourself-now" class="md-nav__link"> <span class="md-ellipsis"> The bridge: "Staff yourself now" </span> </a> </li> </ul> </nav> </li> <li class="md-nav__item"> <a href="#4-without-the-installation-permission-the-hand-off" class="md-nav__link"> <span class="md-ellipsis"> 4. Without the installation permission: the hand-off </span> </a> </li> <li class="md-nav__item"> <a href="#4b-when-the-missing-piece-is-the-catalog--and-you-are-the-one-who-governs-it" class="md-nav__link"> <span class="md-ellipsis"> 4b. When the missing piece is the CATALOG — and you are the one who governs it </span> </a> </li> <li class="md-nav__item"> <a href="#5-everything-is-attributed" class="md-nav__link"> <span class="md-ellipsis"> 5. Everything is attributed </span> </a> </li> <li class="md-nav__item"> <a href="#6-dissolving-an-organization-founded-by-mistake" class="md-nav__link"> <span class="md-ellipsis"> 6. Dissolving an organization founded by mistake </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/topics/provisioning-birth-path.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="how-a-new-organization-and-project-are-born">How a new organization and project are born<a class="headerlink" href="#how-a-new-organization-and-project-are-born" title="Permanent link">¶</a></h1> <p><em>Audience: whoever stands up a new customer or a new project — a quality manager or an installation administrator.</em></p> <p>A project in LQMS is a <strong>scope</strong>: a strictly separated space holding one project's documents, records, roles and configuration. A scope belongs to an <strong>organization</strong> — the customer or operating company that is the hard separation boundary. Both are created <strong>in the tool</strong> — but they are created by two different acts, and that separation is the first thing to understand about this page.</p> <p><em>(The API, the database and the decision records call an organization a </em><em>mandator</em><em>. Same thing, internal name — you meet it only if you read those.)</em></p> <h2 id="0-two-processes-and-why-they-are-not-one-form">0. Two processes, and why they are not one form<a class="headerlink" href="#0-two-processes-and-why-they-are-not-one-form" title="Permanent link">¶</a></h2> <p><strong>Founding an organization</strong> and <strong>setting up a project</strong> are different business processes. One says <em>a new customer exists</em>; the other says <em>we are starting a piece of work for a customer that already exists</em>. They are usually done by different people, on different days, for different reasons — and one of them creates a boundary that can never be moved afterwards.</p> <p>Until August 2026 the tool merged them: the new-project form's organization picker carried an inline <em>"— new organization —"</em> entry, so founding a whole tenant was one dropdown slip away from routine work. Now the two acts are two entries in the <strong>Administration</strong> menu, and you choose which one you are doing before you are on either surface:</p> <ul> <li><strong>Project setup</strong> — setting a project up inside an organization that already exists. The routine act.</li> <li><strong>Found an organization</strong> — its own workflow, on its own page, visible only to whoever holds the founding right. The operator's act.</li> </ul> <p>The project process <strong>can no longer create an organization at all</strong>, and the founding act is nowhere inside it — not even as an offer. If you need an organization, you found it first from its own menu entry, and the founding workflow then offers to continue straight into its first project.</p> <h2 id="1-the-act-sequence">1. The act sequence<a class="headerlink" href="#1-the-act-sequence" title="Permanent link">¶</a></h2> <p>This is the order the acts happen in, and most of it is forced: each step depends on the one above it. The first line is a <strong>separate act on a separate page</strong>; everything under it is one run of the wizard.</p> <ol> <li><strong>Organization</strong> — founded in its own workflow (§1a), or already there and simply named as the project's boundary (§2).</li> <li><strong>Project (scope)</strong> — its code, its name, its derive-source capability.</li> <li><strong>Roles activated</strong> in the project (from the installation catalog) — a policy may only name roles the project has activated, and a person may only be assigned a role the project has activated.</li> <li><strong>Staffing</strong> — people assigned to those roles, <strong>you included</strong> (<a href="../staffing-and-assignments/">staffing & assignments</a>); §3 explains why this one cannot wait.</li> <li><strong>Document types activated</strong> in the project (from the installation catalog), each before its own configuration.</li> <li><strong>Review policies</strong>, may-define rights and acknowledgement policies, per type.</li> <li><strong>Folders</strong>.</li> <li><strong>Special elements declared</strong>, where the lane wants them (<a href="../key-rules/">special elements</a>) — last, and deliberately not tolerant of an "already there": a project that already mints items of that kind has its name and prefix <strong>frozen</strong>, and that must be read, not silently skipped. Declaring a kind also declares what it depends on: risks bring risk controls, a validation case brings the user need and the requirement behind it, in the same audited act.</li> <li>The setup check reads <strong>complete</strong>.</li> </ol> <h2 id="1a-founding-an-organization">1a. Founding an organization<a class="headerlink" href="#1a-founding-an-organization" title="Permanent link">¶</a></h2> <p><strong>Administration → Found an organization.</strong> The menu entry appears for whoever holds the founding right and for nobody else. Where the absence would otherwise be a dead end — the project form of an installation that carries no organization at all — the process is named there instead, with the right that carries it and the roles that hold it, rather than leaving a reader to conclude the tool cannot do it.</p> <p>The page states what the act creates <em>before</em> the name field, because all three of these outlive the click:</p> <ul> <li><strong>its own space</strong> — every project, document and record of this organization stays inside it, and nothing crosses to another organization;</li> <li><strong>its own membership</strong> — people are invited into this organization and hold their functions inside it, independently of every other one;</li> <li><strong>its own audit trail</strong> — what happens there is recorded there, permanently.</li> </ul> <p><img alt="Founding an organization: what the act creates, stated before the field" src="scene:found-organization-1-name" /></p> <p>Then one field: the organization's name. A name that already exists is <strong>refused, never adopted</strong> — the server names the existing organization and tells you to pick it instead. Two customers silently collapsing into one tenant is exactly the failure separation exists to prevent. The founding itself is recorded in the installation's audit trail, with your name and the organization's.</p> <p><strong>It does not end on a success message.</strong> A freshly founded organization has no project and nobody in it, so the workflow offers both of its first beats:</p> <ul> <li><strong>Set up its first project</strong> — hands over to the project wizard with this organization already carried and <em>stated</em> (see §2);</li> <li><strong>Invite its first member</strong> — the ordinary membership invitation on <strong>Admin → People</strong>; the person answers it themselves, and until they accept they see nothing of the organization.</li> </ul> <p><img alt="A founded organization and its two first beats" src="scene:found-organization-2-beats" /></p> <p>Underneath, quietly, the <strong>undo</strong>: while an organization is still completely empty it can be dissolved (§6). Once it holds anything at all — a project, a member, even a single audit entry — it stays.</p> <p><img alt="The new-project form" src="scene:setup-wizard-birth-1-project" /></p> <h2 id="2-step-1-in-detail--the-form">2. Step 1 in detail — the form<a class="headerlink" href="#2-step-1-in-detail--the-form" title="Permanent link">¶</a></h2> <ul> <li><strong>Organization (customer)</strong> — the boundary this project will belong to. It is asked for <strong>only when there is a real choice</strong>, and stated in every case:</li> <li><strong>more than one</strong> organization → a picker, with <strong>no default</strong> at all: nothing is preselected and the step will not advance until you choose. The tenant boundary is the one fact this system exists to keep straight, so it is never set by form initialization;</li> <li><strong>exactly one</strong> → no question. The binding is stated as a prominent fact before anything is committed — <em>"This project will belong to: Acme Corp"</em> — because a question with one possible answer is not a safeguard, and an unstated binding is not either;</li> <li><strong>none yet</strong> → the form says so and points at the founding workflow (or at the person who holds it). A project cannot exist without an organization, and this form cannot make one.</li> <li>Arriving here from the founding workflow, the newborn organization is the stated boundary, and — where others exist — it can still be exchanged for another one. Exchanging <strong>clears</strong> the binding rather than swapping in the next candidate: from that moment it is a choice again.</li> <li><strong>Project code</strong> — <em>"Unique and immutable; it prefixes every document id in this project."</em> A code already in use is refused by name.</li> <li><strong>Project name</strong> — free text.</li> </ul> <p>Neither project CAPABILITY is asked here, and for two different reasons. Whether the project holds its own records is derived by the server from the project type — the form says so: <em>"A project keeps its own records — the server sets that from the project type, so it is not asked here."</em> Whether it <strong>may be a derive source</strong> is a governed setting on an existing project, changed under <strong>Administration → Scopes</strong> by a holder of MANAGE_SCOPES at the installation level and recorded in the trail. It left the birth form in July 2026: a brand-new project is never a derive source (base procedures are derived <em>into</em> a project from the operating organization's own project rather than out of it), so asking at birth only offered a wrong answer, while the real decision belongs to a project that already exists.</p> <p>Nothing is written on this step. The project becomes the <strong>first item of the commit plan</strong> on <em>Apply & verify</em>, so you can still go back and change everything — and that plan item names its organization in words (<em>"under organization Acme Corp"</em>), because the binding is the one thing here that can never be corrected afterwards.</p> <p>Two things this surface deliberately does <strong>not</strong> do: it never deletes or deactivates anything (removing a type activation would strand existing documents), and it cannot create the installation's single base scope — the bootstrap owns that.</p> <h2 id="3-staffing-comes-before-policies--and-this-order-is-not-optional">3. Staffing comes before policies — and this order is not optional<a class="headerlink" href="#3-staffing-comes-before-policies--and-this-order-is-not-optional" title="Permanent link">¶</a></h2> <p>This is the one sequencing constraint worth understanding, even though the wizard now handles it for you.</p> <p>Creating and configuring the <em>installation-level</em> facts (organization, project, activations, element declarations) is gated on a permission held <strong>installation-wide</strong>. Configuring a <em>project's</em> review policies is gated <strong>inside that project</strong> — and a project that was born ten seconds ago has nobody in it, including you. So the first policy write into a newborn project is refused until somebody is staffed there.</p> <p>The consequence, verified end to end (2026-07-27, driven as <code>carla.fischer</code>): she created the organization and the project, activated SOP and REC, activated Document Author, Quality Reviewer and Quality Manager, and declared the lane's special elements — all accepted — and then her <strong>first review-policy write into the new project was refused</strong>, because she held no configuration permission <em>there</em> yet. Staffing herself unblocked it; the setup check then named the one role still empty (<em>Quality Reviewer has no active holder</em>), she staffed <code>anna.sommer</code>, added a folder, and the check read <strong>complete, no findings</strong>.</p> <h3 id="the-bridge-staff-yourself-now">The bridge: "Staff yourself now"<a class="headerlink" href="#the-bridge-staff-yourself-now" title="Permanent link">¶</a></h3> <p>You do not have to hit that wall. The configuration step carries a <strong>Staff yourself now</strong> section in its Roles block: a checkbox per role the run is activating, ticked for the roles you will actually work in. 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. Assign yourself the roles you will actually work in and the project's own configuration steps — review policies, folders, acknowledgement policies — are performed in this same run instead of being handed off."</em></p> <p><strong>This is the normal path for a birth run.</strong> Ticking the boxes adds a <em>Staff yourself — <roles></em> act to the commit plan, immediately after the role activations that make those roles assignable and <strong>before</strong> everything that needs a permission they carry. The wizard then re-reads what you may now do and re-derives the rest of the plan from it — which is what lets the policies, may-define rights, folders and acknowledgement policies the staffing just unlocked run in <strong>this</strong> pass, on one <em>Apply</em>. Nothing is written earlier than the last step, as always.</p> <p>The section only appears where you can actually staff yourself — your user administration must reach into the new project (held installation-wide, or on the organization the project belongs to). Where a per-project step is blocked for exactly this reason, the wizard says so and points at the checkbox rather than making you work it out: <em>"You are not staffed in this new project yet — that is the cause. Tick 'Staff yourself now' in the Roles section above and this step is planned and performed in the same run."</em></p> <p><strong>Without that reach</strong>, the fallback is the sequence above: create the project, then staff yourself — or have someone staff you — on <strong>Admin → Users</strong>, then come back. The wizard names this case too: <em>"You are not staffed in this new project yet — that is the cause. Staff yourself (Admin › Users) once the project exists, then this step unlocks."</em> Nothing you entered is lost; the wizard writes nothing until <em>Apply</em>.</p> <h2 id="4-without-the-installation-permission-the-hand-off">4. Without the installation permission: the hand-off<a class="headerlink" href="#4-without-the-installation-permission-the-hand-off" title="Permanent link">¶</a></h2> <p>A caller who does not hold it sees the same wizard with the same steps — the provisioning panels of a run already under way simply keep their <strong>"Hand this to an administrator"</strong> rendering, naming exactly what is missing and who does it. Never a silent skip, never a disabled button with no explanation: the hand-off <em>is</em> the unauthorized rendering.</p> <p>Read that sentence precisely: a hand-off is what a panel renders <strong>for the caller who does not hold the act</strong>. Where the act <em>is</em> yours, the same panel is the act — see §4b for the catalog case, which is the one a fresh installation meets first.</p> <p><strong>The one exception is the doorway.</strong> Step 1 is where you pick the project you came to set up, and for a caller who cannot create one, the "Set up a new project" entry is simply absent — with no band in its place. A hand-off belongs to somebody stopped <em>inside</em> a run at a step they cannot perform; on the way in it would greet a reader with a permission they may never need, in front of work that is entirely open to them. The projects you reach are listed and configurable exactly as before. Where a new project really has to exist, that is an installation administrator's act: ask, and come back once it does.</p> <p>Each of the remaining panels says which permission is the cause, by name, and what happens next: - <strong>Founding an organization</strong> — a right of its own since the two processes split (MANAGE_MANDATORS). It is not a panel inside the wizard: the menu entry is simply absent for whoever does not hold it. The two rights can be held separately on purpose — an administrator may let a role set projects up inside existing organizations while withholding the power to create new ones. Where that is how the installation is configured, the project process works in full and the founding entry is not offered. The one place the <em>process</em> is still named to such a caller is the project form of an installation that carries no organization yet, because there it would otherwise be a dead end. - <strong>Type activation</strong> — <em>"…Activating them needs installation-shaping rights (MANAGE_SCOPES), which you do not hold — an administrator activates them, then re-run this wizard to configure them."</em> - <strong>Special elements</strong> — <em>"Activating these special elements — and saying which document types may define them — needs installation-shaping rights (MANAGE_SCOPES), which you do not hold. An administrator activates them; the wizard reports a missing one as a setup gap in the last step."</em> The lane's proposal is still shown, row by row with its prefix, so you can read the convention you cannot set — and the <strong>defining types</strong> control beside it stays live where you hold catalog activation in the project, because that is a different authority.</p> <p>Note what those sentences do and do not say. The cause is always <em>"you do not hold this permission"</em> — never <em>"this feature does not exist"</em>. And rather than leaving you to find the right person, the panel lists the roles that carry the permission in this installation: <em>"Roles carrying MANAGE_SCOPES in this installation: …"</em>. That is who to ask.</p> <h2 id="4b-when-the-missing-piece-is-the-catalog--and-you-are-the-one-who-governs-it">4b. When the missing piece is the CATALOG — and you are the one who governs it<a class="headerlink" href="#4b-when-the-missing-piece-is-the-catalog--and-you-are-the-one-who-governs-it" title="Permanent link">¶</a></h2> <p>Activating a type or a role in a project presupposes that the <strong>installation's catalog</strong> carries it at all. On a fresh installation it carries almost nothing, so the lane's types and its three role slots are all missing at once — and creating catalog entries is a different permission from provisioning (catalog administration, the surface behind <strong>Admin → Document types</strong> and <strong>Admin → Roles</strong>).</p> <p>The panel therefore follows the reader:</p> <ul> <li><strong>You do not hold catalog administration</strong> — it stays a hand-off, and it distinguishes the two cases rather than lumping them: an <strong>empty</strong> catalog (<em>"This installation's document-type catalog is empty — it carries no document type at all yet"</em>) is a different fact from a partial mismatch (<em>"This installation's document-type catalog has no type for 1 of this lane's prefixes."</em>). The missing entries are listed compactly underneath, and a long list collapses behind <em>"Show the 8 types"</em> — a lane meeting a fresh installation is not a wall of prefixes.</li> <li><strong>You do hold it</strong> — the panel becomes the act. <em>"Create the 8 missing document type(s) now"</em> creates them, and the roles panel offers the same for the slots (<em>"This installation's role catalog has no role named: … You hold the catalog administration that creates them."</em>). The wizard then carries straight on: each created type appears as a configurable panel marked <em>will be activated</em>, each created role fills its slot and joins the activation list. No second trip, no re-run.</li> </ul> <p>Two things the offer states before you press it, because both outlive this wizard run:</p> <ul> <li>it is <strong>catalog administration</strong>, not a project act — <em>"each type is created once for the WHOLE installation and recorded in the audit trail, exactly as on Admin › Document types"</em>. Name, prefix and category come from the lane; one type's periodic-review interval is a separate catalog default and stays a hand-off (see the band below it, headlined <em>"Catalog administration — yours to do"</em> for you);</li> <li>a created <strong>role carries the house permission set</strong> for its part in the work, and the note lists it token by token — <em>"Created in the installation's role catalog, each with the house permission set for its part in the work:"</em>, then one line per role. Those sets are the same ones the demo stack's roles hold, so a wizard-created project and a seeded one behave alike. Note the deliberate asymmetry inside them: <strong>Document Author does not carry <code>ORGANIZE_DOCUMENTS</code></strong> — filing is a document-control act, so the Quality Reviewer and the Quality Manager carry it and the Author does not. That is what decides whether the folder skeleton below can be created in this run, and the staffing bridge names the carriers when it cannot. The permission sets are installation-wide and stay editable on <strong>Admin → Roles</strong>; where a mapping call is refused after the role was created, the note says that role received <em>no permissions</em> rather than repeating a set the installation never got.</li> </ul> <p>This is also the path a <strong>brand-new installation's administrator</strong> walks: they hold their permissions through their assignment at the global scope and may read no project's content at all, so the project picker on step 1 is honestly empty and <em>"I need a new project"</em> is the way in — while every step that follows works, because the wizard asks the same question the server does (ADR-0106).</p> <h2 id="5-everything-is-attributed">5. Everything is attributed<a class="headerlink" href="#5-everything-is-attributed" title="Permanent link">¶</a></h2> <p>Every act writes an audit event — organization created, project created, type activated, role activated, element kind declared (one event per kind, and a prerequisite pulled in with it names what pulled it) — recording the actor <strong>by name</strong>, with before/after values. The project's own trail then carries its staffing, policy and folder acts. A refusal writes nothing: a denied attempt is not an act.</p> <p>One entry deserves reading twice: role activation records <code>staffing: unchanged</code> in the event body. <strong>Activating a role makes it bindable and assignable in the project; it staffs nobody.</strong> The setup check will keep reporting the role as unstaffed until a person is actually assigned.</p> <h2 id="6-dissolving-an-organization-founded-by-mistake">6. Dissolving an organization founded by mistake<a class="headerlink" href="#6-dissolving-an-organization-founded-by-mistake" title="Permanent link">¶</a></h2> <p>There is exactly one destructive act on this whole surface, and it exists for one situation: an organization that was founded and should not have been. It lives on <strong>Administration → Scopes</strong>, at the organization's own heading in the directory.</p> <p><strong>It is offered only while the organization is provably empty</strong> — no project, no member, no configuration, no content, and no audit entry of its own. The check is not a list somebody keeps current: the server derives it from the database's own structure and counts on the true state, not on what the person asking can see. Where anything at all is in the way, the refusal <strong>names it in words</strong> — the projects by name, everything else as a counted noun (<em>"…it still has 1 membership record"</em>) — and the organization stays.</p> <p>That rule has a sharp edge and it is deliberate: the organization's own audit trail counts as content. <strong>An organization that has ever recorded anything stays permanent</strong>, because dissolving it would destroy a trail. A freshly founded one can go only because its own birth entries are recorded at the installation level and survive it — which is what makes the honest pair possible: <em>organization created … organization dissolved</em>, both in the installation's trail, naming the same organization, neither pretending it never happened.</p> <p>The directory also <strong>states the dead end</strong> while it lasts: an organization with no project and nobody in it is marked as such at its heading, with the three ways out — found its first project, invite its first member, or dissolve it if it was a mistake. A founded-and-forgotten organization is never left sitting invisible.</p> <p><img alt="An empty organization: the dead-end note and the dissolve affordance" src="scene:admin-scopes-dissolve" /></p> <p><em>(The tutorial's <a href="../../tutorial/#part-0--register-a-new-project">Part 0 — "Register a new project"</a> walks this path hands-on, once, on the demo stack: the new-project form, the lane, "Staff yourself now", </em><em>Apply & verify</em><em> and the setup check. This topic is the reference behind it — the act sequence, the refusals, and what happens when you hold fewer rights.)</em></p> <hr /> <p><em>Governing decisions: ADR-0097 (the governed provisioning surface — every act audited), ADR-0109 (founding an organization is its own process, with its own right, its own workflow and its narrow undo), ADR-0002 (the scope hierarchy and the capability flags), ADR-0010 (the operating organization's own internal record), ADR-0004 (global catalogs with per-scope activation — why activation and staffing are different acts), ADR-0096 (the policy model the newborn project is configured into), ADR-0112 (the element-kind catalog a project declares from) and ADR-0095 (the freeze that governs those declarations at birth), ADR-0106 (the reflection every permission question on this surface is asked over — why a fresh installation's administrator sees the wizard work).</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="../memberships/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Belonging to an organization: invitations, acceptance, and what they change"> <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"> Belonging to an organization: invitations, acceptance, and what they change </div> </div> </a> <a href="../review-policies/" class="md-footer__link md-footer__link--next" aria-label="Next: What a review policy controls, and what an empty grant means"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> What a review policy controls, and what an empty grant means </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>