Documents

Document templates and document requests for building renovations. Admins define reusable templates organized by labels and categories; document requests track which documents are needed for a specific project or building.

Source Files

Layer	Path
Schema	backend/src/db/schema.ts
Request Routes	backend/src/routes/document-requests.ts
Template Routes	backend/src/routes/admin/document-templates.ts, template-labels.ts, label-categories.ts, priority-rules.ts, template-files.ts
Request Service	backend/src/services/document-request-service.ts
Template Service	backend/src/services/document-template-service.ts + backend/src/services/document-template/

Database Tables

Table	Purpose
documentRequests	Tracks individual document needs per project (status, assignee, due date)
documentTemplates	Reusable definitions of document types — key, bilingual name/description/notes (LocalizedText jsonb), optional formId (Forms) and flowDefinitionId
flowDefinitions	Standard flow types a template can use (default modal configuration)
documentTemplateLabels	Tags/labels for organizing templates
documentTemplateLabelCategories	Groupings for labels (e.g., “Building Type”, “Funding Body”)
documentTemplateToLabels	Template ↔ label junction (m:n)
documentTemplatePriorityRules	Priority matrix — priority per parameter value, optionally scoped to a workflow template/task
documentTemplateFilesMetadata	Supporting files attached to a template (CAS fileId → Files; replaceable/downloadable/required flags)

Key Concepts

• Templates define what a document is (e.g., “Energy Certificate”, “Floor Plan”). Admins manage templates, labels, categories, priority rules, and template files via the admin panel. Bilingual fields use the LocalizedText jsonb pattern.
• Requests are instances tied to a project: “We need document X for project Y.” Each request tracks status, assignee, and fulfillment.
• Labels & categories provide a two-level taxonomy so templates can be filtered and grouped in the UI.
• Template files go through CAS (Files); per-request overrides live in documentObtainingRequestFiles (see Document Obtaining).

Config data, not mocks: document templates, priority rules/filters, and forms were baselined from staging into local/preview/development via an Atlas migration (PR#1789). They are config data shipped by migration — the mock loader no longer touches them.

Relationships

DocumentTemplate 1──* DocumentRequests
DocumentTemplate *──* DocumentTemplateLabels (via documentTemplateToLabels)
DocumentTemplateLabel *──1 DocumentTemplateLabelCategory
DocumentTemplate 1──* DocumentTemplatePriorityRules
DocumentTemplate 1──* DocumentTemplateFilesMetadata ──1 Files
DocumentTemplate *──1 Form (optional)
DocumentRequest *──1 Project

Workflow

1. Admin creates templates, labels, and priority rules in the admin panel
2. When a project starts, relevant document requests are created (manually or via Document Obtaining / the workflow task factory)
3. Requests are assigned to team members or sent to customers via Portal
4. Customers or staff upload Files to fulfill the request (canonical collection chain, PR#2005)
5. Fulfilled documents go through Document Review

Frontend

Document requests appear on the project detail page and inside the Document Obtaining dashboard. The admin template management lives at frontend/src/pages/admin/ alongside Forms and other configuration pages.

Related Pages

Document Obtaining | Document Review | Files | Portal | Forms | Projects | Buildings | Admin Dashboard | Service Layer Pattern