Document Vault

The Document Vault is a structured file library for storing and managing all documents associated with blocks and leaseholder units. It supports 10 document categories, block-level and unit-level scoping, and immutable version history.

Document Categories

Category	Description
lease	Lease agreements — block-level template or unit-level specific
insurance	Insurance schedules and policy documents
certificate	Compliance certificates (links to certificate register)
minutes	Meeting minutes and AGM records
plan	Service charge budgets and maintenance plan documents
fire_risk_assessment	FRA reports per block
ews1	External Wall System (EWS1) forms
correspondence	Letters, emails, and communication records
payment_history	Payment records and demand letters per unit
other	Miscellaneous documents

Scoping

Documents can be scoped to:

• A block — shared document library (e.g. FRA, insurance, minutes)
• A specific unit — individual leaseholder documents (e.g. unit lease, payment history)
• Neither — organisation-level documents

The block or unit must belong to the calling organisation; the API validates this on creation.

Version Control

When a document file is replaced using replaceVersion, the platform:

1. Archives the current version (file URL, size, MIME type, uploader) to document_versions
2. Increments currentVersion on the document record
3. Updates the document with the new file

Previous versions are never deleted. The full version history is always available via listVersions.

The current/active file is always on the documents record itself. The document_versions table contains only archived (previous) versions.

Metadata vs. file updates: Use update to change name, category, tags, or description without touching the file. Use replaceVersion only when uploading a new file.

Tags

Documents support a JSON array of string tags (e.g. ["annual", "2024", "approved"]) for filtering and discovery. Tags are stored as a serialised JSON string in the database.

API Reference

All procedures are on the document tRPC router.

document.list

Paginated list of documents for the organisation.

Access: Org member

Filters:

• blockId — documents scoped to a specific block
• unitId — documents scoped to a specific unit
• category — filter by document category

---

document.getById

Fetch a single document by ID.

Access: Org member

---

document.create

Upload a new document to the vault.

Access: Admin

Input:

{
  name: string;              // max 500 chars
  fileUrl: string;           // must be a valid URL
  fileSizeBytes?: number;    // file size in bytes
  mimeType?: string;         // e.g. "application/pdf"
  category: DocumentCategory;
  blockId?: string;          // must belong to org
  unitId?: string;           // must belong to org
  tags?: string[];           // searchable tags
  description?: string;      // optional notes
}

Created documents start at currentVersion: 1.

---

document.update

Update document metadata. Does not change the stored file.

Access: Admin

Editable fields: name, category, tags, description

To replace the actual file, use document.replaceVersion.

---

document.replaceVersion

Replace the document with a new file. Archives the current version before updating.

Access: Admin

Input:

{
  documentId: string;
  fileUrl: string;           // new file URL
  fileSizeBytes?: number;
  mimeType?: string;
  changeNotes?: string;      // reason for the new version, e.g. "Annual renewal"
}

After this call, currentVersion is incremented and the previous file is accessible via document.listVersions.

---

document.listVersions

Return the full archived version history for a document, ordered newest first.

Access: Org member

Input: { documentId: string }

Returns an array of document_versions records. The current (active) version is not included here — it is on the document record itself.

---

document.delete

Permanently delete a document and all its version history.

Access: Admin

This is a permanent, irreversible action. All archived versions are also removed. Use with caution.