The Design Registry

14 — Files, Documents, Notes, Deliverables & Version Control

Version: 1.0
Prepared: August 2026
Status: Engineering and product source of truth
Depends on: Product Vision; Spec 03 Teammates, Teams, Role Labels & Notifications; Spec 04 Workspace Dashboard & Profiles; Spec 05 Provider Applications; Spec 06 Proposals, Work Orders, Invoicing & Payments; Spec 07 Projects, Calendar, Items, Budgets & Provider Operations; Spec 08 Permissions; Spec 09 Pipeline, Forms & Automation Builder; Spec 10 Matchmaking; Spec 11 Communications; Spec 12 Tasks, Calendar, Resource Scheduling & Project Time Tracking; Spec 13 Client Portal, Approvals & Project Experience

1. Executive Summary

The Design Registry needs one dependable content system for every file, document, note, deliverable, image, markup and piece of completion evidence used across the platform. Today’s product already contains record-level Files and Notes tabs, an enterprise file grid, file uploads, internal notes, attachments, activity events and Project deliverables. This specification turns those existing patterns into a canonical shared service instead of allowing every module or portal to invent its own storage, versioning and collaboration behaviour.

The system must answer five questions about any content object:

1. What is it? — file, document, note, deliverable, comment, annotation, evidence or activity event.
2. Where does it belong? — Workspace, Project, record, phase, room, item, task, Work Order or other governed context.
3. Who can see or change it? — internal, Registry, designer, provider, client or specifically shared audiences.
4. Which version governs? — draft, current, issued, published, superseded, accepted or archived.
5. What happened to it? — upload, edit, publication, download, approval, replacement, redaction and retention history.

The most important architectural rule is that similarly visible objects do not become interchangeable. An Internal Note is private collaboration. A Message is communication sent to participants. A Comment is discussion attached to a record. An Annotation identifies a location on a file or document. A Decision is a formal governed response. An Activity Event is system-generated history. A Deliverable is an expected Project output with completion rules. Each has a distinct lifecycle and security boundary even when the same rich-text editor, mention picker, attachment component or activity renderer is reused.

Projects remain the principal operational centre, but the content service also supports pipeline records, applications, entities, clients, designer studios, providers, Offers, Proposals, Work Orders, invoices, tasks, items, purchase orders, shipments and internal Workspace operations.

2. Product Outcomes

The module succeeds when it:

• gives users one searchable library without detaching content from its business context;
• preserves the existing record-level Files and Notes experiences;
• makes current, issued and superseded document versions unmistakable;
• prevents internal notes from leaking to clients or providers;
• lets designers publish polished deliverables without duplicating files;
• lets providers submit category-specific evidence inside assigned workflows;
• gives clients a curated, versioned library of published content;
• provides defensible audit history for approvals, commercial documents and Project completion;
• reduces duplicate uploads and “final-v7-revised” filename confusion;
• supports AI extraction and summarization without bypassing access controls;
• scales safely on Supabase Storage and Postgres.

2.1 Success measures

• At least 95% of uploaded files used in active Projects have a valid record link, category and audience.
• Zero verified external leakage of Internal Notes.
• Every issued or approved deliverable can be traced to an immutable file/document version.
• At least 80% of required Project deliverables are managed through template-generated deliverable requirements.
• Duplicate-upload warnings reduce unnecessary copies without blocking valid revisions.
• Search results and generated previews respect the same access boundary as the original content.

3. Scope

3.1 In scope

• Existing Files and Notes tabs and grids.
• Global Library experience.
• File upload, preview, metadata, linking and classification.
• Folder/collection views without breaking canonical record relationships.
• File and document version control.
• Project drawings, specifications, design packages and deliverables.
• Internal Notes, mentions, note templates and edit history.
• Comments, annotations and markups.
• Evidence, photos and field uploads.
• Client/provider publication and sharing workflows.
• File requests and controlled external uploads.
• Search, OCR, extraction and AI assistance.
• Permissions, signed access, malware scanning, retention and redaction.
• Notification Builder events.
• Supabase/Postgres/Storage model, APIs, migration and acceptance criteria.

3.2 Out of scope

• General email/SMS/in-app messaging transport, owned by Spec 11.
• Formal Decisions and approval authority, owned by Spec 13 and Spec 08.
• Proposal, contract and invoice business rules, owned by Spec 06.
• Full CAD/BIM authoring.
• A general-purpose collaborative word processor equivalent to Google Docs.
• External storage-provider integrations, addressed later by the Integrations specification.

4. Product Principles

4.1 One content object, many contextual views

A file uploaded to a Project and linked to a Work Order appears in both authorized views through record links. The platform does not create copied binaries for each tab.

4.2 Context is mandatory

Business content must belong to a Workspace and at least one supported record or governed Workspace library. Orphaned files are quarantined into an administrative review queue.

4.3 Audience before convenience

Search, preview, thumbnails, OCR, AI, exports, notifications and activity feeds apply access filtering before rendering or processing user-facing results.

4.4 Version beats filename

Version identity is stored structurally. Filenames are presentation metadata and cannot determine which file governs.

4.5 Issued history is immutable

Issued, accepted, signed, paid, published or completion-governing versions cannot be overwritten. Corrections create a new version or governed redaction.

4.6 Notes are never messages

Internal Notes cannot have external recipients, transport state or delivery provider IDs. Sharing Note content creates a separate reviewed draft.

4.7 Deletion is exceptional

Normal users archive or supersede content. Material operational history is not silently deleted. Privacy/legal redaction uses a governed workflow and preserves audit metadata.

4.8 Build once, reuse everywhere

Uploaders, previews, galleries, grids, metadata drawers, rich text, mentions, comments, version timelines and publication controls are shared components.

5. Canonical Content Types

5.1 File

A stored binary object with name, MIME type, size, checksum, storage key, scan state, owner, metadata, audience and record links. Examples: PDF, image, spreadsheet, archive, CAD export or video.

5.2 Document

A business record whose content may be native structured data, generated output or an uploaded file. Documents have types, versions, status and business meaning. Examples: design package, specification, scope document and handover manual.

5.3 Deliverable

An expected output defined by a Project Template, phase, Work Package or Work Order. It has requirements, owner, due date, audience, review state and one or more submitted versions.

5.4 Internal Note

Private Workspace collaboration attached to one or more authorized records. It has no external recipients and can never enter email, SMS or in-app delivery as a Note.

5.5 Comment

Discussion attached to a specific object, version, section or workflow record. A Comment does not itself change approval or status.

5.6 Annotation

A structured location reference on a document, image, drawing or presentation: page, coordinates, region, timestamp or selected text. It contains comment/markup information and remains anchored to a version.

5.7 Markup

Visual annotation data such as pin, arrow, rectangle, freehand line, text callout or measurement. It does not alter the underlying file binary.

5.8 Evidence

Content submitted to prove an operational action or completion condition, such as receiving photos, delivery proof, signed sheet, measurement, installation image or deficiency resolution.

5.9 Message attachment

A File linked to a Message and Conversation. Message participant rules govern access; the File service still owns storage, scanning and preview.

5.10 Activity Event

System-generated append-oriented history. It is not a user-authored Note and cannot be edited to change business history.

5.11 Formal Decision

A versioned approval/rejection record owned by Spec 13. It may reference Files, Documents, Deliverables or Annotations, but Comments and Notes cannot substitute for a Decision response.

6. Information Architecture

6.1 Global Library

Add Library as an authorized navigation destination for Registry, Designer and Provider Workspaces. It contains:

1. Files
2. Deliverables
3. Notes
4. Shared with me
5. Recent
6. File requests
7. Archived

Client navigation continues to use the curated Files surface from Spec 13 rather than the internal Library.

6.2 Record-level tabs

Reuse Files and Notes tabs on:

• Project Opportunities and pipeline records;
• Projects;
• applications;
• client, designer and provider entities;
• Offers and requirements;
• Proposals, Work Orders and invoices;
• Tasks, Decisions and milestones;
• items, purchase orders, shipments, receiving and deficiencies;
• internal Workspace records where enabled.

Each tab queries the canonical content/record-link model.

6.3 Project content navigation

Project Files can be filtered by phase, room/area, type, deliverable, Work Package, provider, status, audience and date. The Project’s Files tab remains a contextual view of the Library.

6.4 Provider experience

Providers see assigned Job/Work Order content, their own private operational content and explicitly shared Project files. Category-specific labels may rename views, but use the shared service.

7. Existing Files Tool Upgrade

7.1 Preserve

Preserve the existing Files tab, Upload Files action, drag-and-drop empty state, enterprise file grid, selection controls, filter, sort, export, column picker and Open action.

7.2 Grid columns

Available columns include:

• title/document name;
• type/category;
• source;
• version/revision;
• status;
• Project/phase/room;
• related record;
• audience;
• uploaded/published by;
• date uploaded/issued;
• file size;
• scan state;
• approval/Decision state;
• retention state;
• actions.

7.3 Views

• Table;
• Gallery for images and presentations;
• Folder/collection;
• Deliverables queue;
• Recent;
• Awaiting review;
• Published;
• Superseded/archived.

Saved views can be private or shared with authorized Workspace roles.

7.4 Bulk actions

Bulk metadata, category, audience, archive, download and link actions require capability and validation. Issued/published versions, formal evidence and mixed-audience sets cannot be destructively changed through ordinary bulk actions.

8. Upload and Ingestion

8.1 Upload sources

• file picker;
• drag-and-drop;
• mobile camera/photo library;
• paste from clipboard where supported;
• Message attachment;
• file request;
• spreadsheet import process;
• generated platform document;
• future approved integration.

8.2 Upload flow

1. Client obtains authorized upload intent.
2. File streams directly to a temporary/quarantine location.
3. Server records expected checksum, size, type and context.
4. Malware/content checks run.
5. Metadata and duplicate checks run.
6. Authorized user confirms title, category, audience and record links when needed.
7. File becomes available after safe-state confirmation.
8. Previews/OCR/extraction run asynchronously.

8.3 Size and type validation

Workspace policy defines allowed types and limits by context. Executables and unsafe archives are blocked by default. MIME type is detected from content, not trusted solely from extension.

8.4 Malware states

Pending, clean, quarantined, rejected and scan_failed. Pending or unsafe files cannot be previewed/downloaded by ordinary users. Administrators see a safe exception record, not the unsafe payload.

8.5 Duplicate detection

Checksum and contextual metadata identify exact duplicates. The uploader can link the existing File, upload as a new version or continue as a distinct file with a reason. Similar filename alone never blocks upload.

8.6 Interrupted upload

Large uploads support resumable transfer where practical. Failed uploads remain drafts with retry/cleanup policy and never appear as completed evidence.

9. File Metadata and Record Linking

9.1 Core metadata

• Workspace;
• title and original filename;
• MIME/media type;
• category/subcategory;
• size and checksum;
• storage object reference;
• owner/uploader;
• source;
• audience/visibility;
• scan state;
• lifecycle state;
• created/updated/issued dates;
• retention class;
• tags;
• record links.

9.2 Contextual metadata

Files may reference Project, phase, site, floor, room/area, item, provider requirement, Work Package, Work Order, task, Decision, Proposal, PO, shipment, receipt, delivery, installation, deficiency or other supported record.

9.3 Typed links

Record links use constrained typed relationships, not unconstrained table-name/string IDs. One link may be primary; others express related context. Link changes are audited and must not widen audience automatically.

9.4 Tags and categories

Tags are Workspace-configurable and alphabetized in pickers. Categories have stable reporting codes and configurable display labels. AI suggestions require user confirmation unless a high-confidence safe rule is configured.

9.5 Folders and collections

Folders are navigational collections, not the sole source of access. Moving a File between folders cannot grant access or detach required record links. A File may appear in multiple collections without binary duplication.

10. File and Document Lifecycle

10.1 Lifecycle states

• draft;
• in_review;
• approved_internal;
• issued;
• published;
• superseded;
• archived;
• quarantined;
• redacted.

Display labels may be customized, but underlying semantics remain stable.

10.2 Drafts

Drafts are visible only to permitted internal audiences. Upload does not equal publication.

10.3 Issue and publication

Issue freezes a version for operational use. Publication intentionally makes an eligible version visible to a client/provider audience. Issue and publication are separate so an internally issued construction document need not be client-visible.

10.4 Supersession

Publishing/issuing a replacement identifies the predecessor and reason. The prior version becomes superseded but remains auditable and accessible according to policy.

10.5 Archive

Archive removes content from active default views without destroying history. Archived content remains searchable to authorized users and available to governing records.

10.6 Redaction

Redaction is a privileged workflow for privacy, legal or security needs. It records reason, actor, scope, original content retention policy and affected derivatives/previews. Redacted binaries are never returned through old signed links.

11. Version Control

11.1 Version identity

Every version has immutable ID, parent document, sequence, optional revision code, checksum, source, author, created date, change summary and lifecycle state.

11.2 Creating versions

A new version can originate from upload, generated document, approved integration or controlled copy/edit. Users choose New version rather than overwriting an issued binary.

11.3 Revision naming

Workspace templates can define revision patterns such as v1, v2 or A, B, C. The system sequence remains canonical even when display codes differ.

11.4 Current version

“Current” is computed from lifecycle and relationship, not filename or most recent upload. Different audiences may have different current published versions only when explicitly allowed and clearly indicated.

11.5 Version comparison

Supported comparison modes include:

• metadata and change summary for all types;
• text comparison for extracted/structured text;
• page/image overlay for supported PDFs/images;
• spreadsheet structural comparison where feasible;
• manual comparison acknowledgement for unsupported binary types.

Comparisons obey access to both versions.

11.6 Accepted and signed versions

Versions referenced by a formal Decision, signature, Work Order, paid invoice or completion gate are immutable. Replacement requires a new governing record where business rules demand it.

12. Document Types

12.1 Drawings and plans

Fields include drawing number, title, discipline, phase, sheet, revision, issue purpose, scale, site/space, author, reviewer and approval state. Native CAD/BIM may be stored, while browser preview uses safe derivatives.

12.2 Specifications and schedules

Support discipline, section/category, room/item links, issue set, revision and associated drawing/deliverable.

12.3 Design packages and presentations

Structured packages reference ordered sections, files, images, rooms, selections and Decisions. Published packages use immutable versions defined in Spec 13.

12.4 Commercial documents

Proposals, contracts, Work Orders, Change Orders, invoices and receipts remain owned by Spec 06. The content service stores rendered files and attachments and preserves exact version lineage.

12.5 Operational documents

Purchase orders, acknowledgements, packing slips, receiving records, manifests, proof of delivery, install sheets, deficiency reports and warranties link to canonical operational records.

12.6 Generated documents

Generated documents store template version, input snapshot, rendering engine version and output checksum so they can be reproduced or explained.

13. Project Deliverables

13.1 Deliverable requirement

A Deliverable requirement defines:

• title and type;
• Project/phase/space/Work Package;
• owner and collaborators;
• due date/relative schedule rule;
• required files/metadata;
• reviewer/Decision policy;
• client/provider/internal audience;
• completion evidence;
• predecessor/dependency;
• template/source version.

13.2 Project Builder integration

Project Templates include a Deliverable Library and phase deliverable instances. Instantiation is idempotent. Template migration previews added, removed or changed requirements without deleting submissions.

13.3 Deliverable states

Not started, in progress, submitted, changes requested, approved internal, issued, published, accepted, superseded, waived and cancelled.

13.4 Submission

Submitting a deliverable links one or more specific File/Document versions. A submission snapshot preserves what was reviewed. Revisions create new submissions rather than replacing accepted evidence.

13.5 Gate integration

Project phases and milestones can require specific deliverable states. Waiver requires capability, reason and audit. A Comment or Note cannot satisfy a deliverable requirement.

13.6 Work Order deliverables

Provider Work Orders can require shop drawings, quote detail, measurements, samples, progress photos, packing documents, certificates, completion evidence or warranties. Providers see only their authorized requirements and submissions.

14. Notes Module

14.1 Shared Note model

The existing Internal Notes experience becomes a platform-wide Note service. A Note includes author, author Membership, owning Workspace, body, created/edited times, versions, visibility classification, record links, mentions, attachments, categories, pinned state and audit metadata.

14.2 Note types

• general internal note;
• meeting note;
• site visit note;
• call follow-up note;
• research/reference note;
• handoff note;
• risk/exception note;
• configurable Workspace type.

Note type affects prompts/templates and reporting, not the hard internal safety boundary.

14.3 Create Note experience

The existing Add Internal Note modal is preserved and extended with:

• rich text;
• @mentions;
• record tags;
• attachments;
• note type;
• pin/importance;
• optional structured meeting fields;
• AI improve/summarize;
• Save Note.

The author and timestamp are visible before save. The submit label always says Add note or Save note, never Send.

14.4 Edit history

Authorized users may edit Notes, but prior versions remain available in audit. The UI shows edited time and editor. Normal users cannot delete operational Notes; governed redaction handles exceptional removal.

14.5 Mentions

Users may mention permitted teammates, Teams and role audiences. Mentioning cannot grant access. If the recipient cannot open the Note context, the mention is blocked and explained.

14.6 Pinning and importance

Authorized users can pin a limited number of Notes to a record Overview or Notes tab. Pinning is audience-scoped and audited. Importance is not a substitute for task priority or risk state.

14.7 Notes search and views

• Recent;
• My Notes;
• Mentioned;
• Pinned;
• By record;
• By type/tag;
• Edited;
• Archived/redacted metadata where authorized.

14.8 Convert to work

Selected Note text can create a draft Task, calendar event, Decision, issue or Project update. The new record keeps a source link. Conversion never changes the Note into the new object and never creates formal approval automatically.

15. Notes Safety Boundary

15.1 Storage separation

Notes live in dedicated Note tables/records, separate from participant Messages. Attachments inherit Note audience unless separately and intentionally published.

15.2 No delivery attributes

Notes have no recipient rows, external address, email/SMS transport, delivery state, provider message ID or external reply token.

15.3 External denial

Client and unrelated Provider RLS policies deny internal Notes even when those users can access the same Project or Conversation.

15.4 Sharing Note content

Share externally creates a separate Message, Project update or document draft with copied content and source reference. A human reviews recipients, audience and text before publication/send. The Note remains private.

15.5 Notification safety

Mention notifications use safe excerpts according to policy. External channels never include full sensitive Note content by default. A notification link reauthorizes the Note read.

15.6 AI safety

AI context includes Notes only for callers with Note access. AI-generated client/provider output must be regenerated from permitted sources or reviewed drafts; it cannot cite/reveal a Note directly to an external audience.

16. Comments, Threads and Resolution

16.1 Comment scope

Comments attach to a record or specific immutable version. They include author, body, audience, mentions, status, parent comment and attachments.

16.2 Threading

One-level replies are the default to preserve readability. Deep nesting is flattened with references. Comments can be open, resolved, reopened or archived.

16.3 Audience

Comments may be internal or participant-facing when the governing record supports it. Audience is selected at thread creation and cannot be casually widened after sensitive replies exist.

16.4 Resolution

Resolving a Comment indicates discussion closure, not approval, Task completion or issue resolution. If action is required, create/link the appropriate record.

16.5 Mentions and notifications

Comment mentions require pre-existing access and create editable Notification Builder events.

17. Annotations and Markups

17.1 Supported anchors

• PDF/document page and coordinates;
• image coordinates/region;
• presentation page/section;
• video/audio timestamp;
• extracted text range;
• drawing sheet/viewport where supported.

17.2 Markup tools

Pin, text callout, rectangle, arrow, freehand, highlight, cloud and measurement where calibration is available. Accessibility requires a textual description for every material markup.

17.3 Version anchoring

Annotations belong to a specific file/document version. New versions may offer a best-effort copy/realignment preview, but users confirm migrated locations. Prior annotations remain on the original version.

17.4 Annotation state

Open, acknowledged, action required, resolved and not applicable. Annotation state does not replace formal deficiency/Decision state.

17.5 Create work

An annotation can create a Task, issue, RFI, Decision or deficiency with a snapshot/link to the location.

18. Evidence, Photos and Galleries

18.1 Evidence submission

Evidence links to the exact task, item, receipt, delivery, installation outcome, deficiency or milestone it supports. Required evidence defines type, count, metadata and reviewer.

18.2 Photos

Photo metadata may include capture time, uploader, device-provided orientation, caption, room/item, condition, audience and optional geolocation when policy/consent allows. The system never assumes device geolocation is authoritative proof.

18.3 Condition evidence

Receiving and storage evidence groups overview, label, packaging and damage images with condition record, quantity and timestamp. Original and annotated derivatives are retained.

18.4 Delivery/install evidence

Proof of delivery, signature, installed-state photos and deficiency evidence remain linked to manifest/item/outcome records. Client-visible galleries are intentionally published.

18.5 Galleries

Galleries provide curated order, cover image, captions, audience and version. A gallery references Files without copying binaries.

18.6 Media derivatives

Thumbnails, optimized images and previews are derivatives of the original. They retain source ID and are regenerated/revoked when access or redaction changes.

19. Publication and Sharing

19.1 Publication workflow

1. Select eligible version(s).
2. Choose client/provider audience and Project context.
3. Preview exactly what recipients will see.
4. Validate hidden metadata/attachments.
5. Optionally link a Decision or message.
6. Publish with note/change summary.
7. Create activity and notification events.

19.2 Published artifact

Publication creates an audience record referencing the canonical version. It does not copy the binary. Revocation ends future access but preserves audit and any governing acceptance history.

19.3 Direct shares

Specifically shared access identifies users/Workspaces, expiry and purpose. Anonymous public links are disabled by default. Password-only links do not replace identity for sensitive Project content.

19.4 Provider sharing

Pre-award providers receive only controlled quote-package content. Awarded providers receive Work Order/Job content. Provider-to-client sharing is prohibited unless the Project relationship permits it.

19.5 Client sharing

Clients see only published artifacts in Spec 13. Internal metadata, hidden costs, notes, annotations and prior drafts remain excluded.

19.6 Watermarks

Policy may apply recipient, Project, date or confidentiality watermarks to generated previews/downloads. Watermarking does not replace authorization.

20. File Requests and External Uploads

20.1 File request

A request defines recipient, context, required file types, instructions, due date, maximum count/size, destination category, audience and expiry.

20.2 Recipient experience

Authenticated users upload inside the portal. Approved unauthenticated request links may allow narrowly scoped upload without granting record read access. Links are single-purpose, expiring and rate-limited.

20.3 Review

Requested uploads enter pending review and scan state. Reviewers accept, reject, request replacement or reclassify. Acceptance does not publish externally unless configured.

20.4 Examples

• client inspiration and existing plans;
• provider insurance/certification;
• vendor acknowledgement;
• photographer gallery;
• storage receiving documents;
• contractor submittal;
• warranty/care document.

21. Search, OCR and Discovery

21.1 Searchable fields

Title, filename, category, tags, Project, phase, room, linked record, author, dates, version, status, permitted extracted text and Note content.

21.2 Security trimming

Results are filtered at query time and index-time by audience/workspace/record relationship. A result cannot reveal hidden title, snippet, thumbnail, count or existence.

21.3 OCR and extraction

Supported images/PDFs can produce searchable text, document type suggestions, dates, amounts, vendor names, item references and sheet numbers. Extracted data stores model/parser version, confidence and source coordinates.

21.4 Saved searches

Users can save private or shared searches, subject to capability. Shared search results remain individually authorized.

21.5 Discovery panels

• Recent;
• Shared with me;
• Awaiting my review;
• Missing metadata;
• Duplicate candidates;
• Expiring/retention action;
• Mentioned Notes/Comments.

22. AI Assistance

22.1 Approved uses

• suggest file category, title, tags and record links;
• summarize permitted documents and Notes;
• extract structured fields from purchase orders, invoices, specifications and forms;
• identify potential duplicate/revision relationships;
• compare versions and draft change summaries;
• draft Notes, meeting summaries and handoff notes;
• find related permitted content;
• generate a draft Task/Decision/update from selected content;
• detect missing deliverable metadata;
• create accessible image descriptions for human review.

22.2 Human review

AI suggestions remain drafts when they affect audience, document status, record links, financial data, formal Decisions or evidence completeness. AI cannot issue, publish, approve, redact or delete content.

22.3 Context boundary

Retrieval occurs after permissions and field masking. Embeddings/indexes preserve tenant/audience partitions. AI output cannot expose the existence of hidden content.

22.4 Provenance

Accepted extraction stores source file/version, page/coordinates, model/parser version, confidence, reviewer and time.

23. Notifications Builder

Every new notification is an editable template event.

23.1 Files/documents

• upload completed, failed or quarantined;
• file shared/published/revoked;
• new version uploaded;
• document issued/superseded;
• download/export ready;
• file request created, reminder, submitted, accepted, rejected or expired;
• missing metadata/retention action assigned.

23.2 Deliverables

• requirement assigned/due/overdue;
• deliverable submitted;
• changes requested;
• approved, issued, published, accepted, waived or superseded.

23.3 Notes/comments/annotations

• Note mentioned;
• Note pinned or materially edited when following;
• Comment/annotation mentioned, replied, resolved or reopened;
• linked Task/Decision/issue created.

Templates use safe excerpts and secure links. Notes are excluded from external channels unless policy and recipient access permit a minimal internal notification. Digests reduce noise.

24. Permissions and Audience

Use Spec 08’s capability/field/access model.

24.1 Capability families

• files.view/upload/edit_metadata/download/export/archive/redact/manage_versions;
• documents.create/edit/issue/publish/supersede;
• deliverables.view/create/submit/review/approve/waive/manage_templates;
• notes.view/create/edit/pin/mention/export/redact;
• comments.view/create/reply/resolve/manage_audience;
• annotations.view/create/edit/resolve;
• file_requests.create/manage/respond;
• library.manage_categories/manage_retention.

24.2 Audience classes

• private to author where enabled;
• Workspace internal;
• Registry internal;
• Project designer team;
• assigned provider;
• client;
• specifically shared users/Workspaces.

24.3 Combined authorization

A user must have content capability, access to at least one governing record link and permission for the audience class. Possessing a signed URL alone is insufficient after expiry/revocation.

24.4 Field masking

Users may see a document without protected cost, contact or provider metadata. Generated preview/download variants must honor masking where source formats support it; otherwise access to the original is denied and a safe rendered artifact is used.

25. Retention, Legal Hold and Deletion

25.1 Retention classes

Workspace default, Project, commercial/legal, financial, personnel, provider compliance, transient upload, communication attachment and custom governed class.

25.2 Retention clock

Retention may start from upload, supersession, Project completion, contract termination, final payment or another configured event.

25.3 Legal hold

Hold prevents destructive deletion/redaction where legally required and records scope/authority. Ordinary users do not see confidential hold detail.

25.4 Archive versus delete

Archive is normal lifecycle. Hard deletion is limited to uncommitted transient uploads, required privacy deletion or approved administrative cleanup with dependency check.

25.5 Dependency check

Content referenced by Decisions, signatures, invoices, payments, custody, evidence, audit or issued deliverables cannot be hard-deleted through ordinary tools.

25.6 Storage cleanup

Unreferenced failed uploads and obsolete derivatives are cleaned by scheduled, auditable jobs after a safety window. Original governing versions remain protected.

26. Data Model

files
file_objects
file_derivatives
file_metadata
file_categories
file_tags
file_tag_links
file_record_links
file_collections
file_collection_members
file_access_grants
file_scan_results
file_extractions

documents
document_types
document_versions
document_version_links
document_publications

deliverable_templates
deliverable_template_versions
deliverable_requirements
deliverable_submissions
deliverable_submission_files
deliverable_reviews

notes
note_versions
note_record_links
note_mentions
note_attachments

comments
comment_threads
comment_mentions
annotations
annotation_markups

evidence_requirements
evidence_submissions
evidence_files
galleries
gallery_items

file_requests
file_request_submissions
retention_policies
legal_holds
content_redactions

26.1 Constraints

• Every content record belongs to one owning Workspace.
• Every active File has a safe object/scan state and at least one governed context.
• Checksums identify binaries but do not determine business identity.
• Issued/published/accepted versions are immutable.
• Notes cannot have Message recipients or transport fields.
• Annotations reference immutable version coordinates.
• Publication references an exact version and audience.
• Deliverable completion references exact submission versions.
• Derivatives cannot outlive/reveal a revoked or redacted source.

27. Supabase and Storage Architecture

27.1 Postgres

Postgres stores content metadata, typed record links, versions, audience, publication, notes, comments, annotations, deliverable requirements, retention and audit references.

27.2 Supabase Storage

Private buckets store originals, quarantine objects, previews/derivatives and temporary uploads with separated policies. Object paths use opaque IDs rather than sensitive names.

27.3 Upload authorization

Server-authorized upload intents define Workspace, context, expected size/type, expiry and idempotency key. Finalization verifies object ownership/checksum and scan state.

27.4 Signed access

Downloads/previews use short-lived signed URLs or authorized streaming. Authorization is checked immediately before link creation. Revocation prevents new links and can invalidate cached derivative access according to CDN policy.

27.5 Background jobs

A durable queue handles scans, thumbnails, OCR, extraction, version comparison, watermarking and cleanup. Jobs are idempotent and dead-lettered after bounded retries.

27.6 Realtime

Private authorized channels can signal upload completion, comments, Notes mentions and deliverable state. Realtime payloads contain safe metadata; canonical reads return full state.

27.7 Service isolation

Browser clients never receive service-role credentials. Scan/extraction workers use least-privilege access to specific object/job scope and do not log sensitive content.

28. API Design

28.1 Files and versions

POST /v1/files/upload-intents
POST /v1/files/:fileId/finalize
GET  /v1/files
GET  /v1/files/:fileId
PATCH /v1/files/:fileId/metadata
POST /v1/files/:fileId/record-links
POST /v1/files/:fileId/versions
GET  /v1/files/:fileId/download
POST /v1/files/:fileId/archive
POST /v1/files/:fileId/redaction-requests

28.2 Documents/deliverables

GET  /v1/documents/:documentId/versions
POST /v1/documents/:documentId/issue
POST /v1/documents/:documentId/publish
POST /v1/document-versions/:versionId/supersede
GET  /v1/deliverables
POST /v1/deliverables/:deliverableId/submissions
POST /v1/deliverable-submissions/:submissionId/review

28.3 Notes/comments/annotations

GET  /v1/notes
POST /v1/notes
PATCH /v1/notes/:noteId
POST /v1/notes/:noteId/pin
POST /v1/notes/:noteId/convert
POST /v1/comment-threads
POST /v1/comment-threads/:threadId/comments
POST /v1/comment-threads/:threadId/resolve
POST /v1/annotations
PATCH /v1/annotations/:annotationId

28.4 Requests/search

POST /v1/file-requests
POST /v1/file-requests/:token/submissions
POST /v1/file-request-submissions/:id/review
GET  /v1/library/search
GET  /v1/library/recent
GET  /v1/library/shared-with-me

List endpoints use cursor pagination, stable sorting and permission-filtered fields. Mutations require idempotency and concurrency/version tokens where relevant. Error responses never reveal hidden content existence.

29. Domain Events

Publish versioned events including:

• file.upload_started, file.upload_completed, file.scan_failed, file.quarantined;
• file.metadata_changed, file.linked, file.archived, file.redacted;
• document.version_created, document.issued, document.published, document.superseded;
• deliverable.assigned, deliverable.submitted, deliverable.changes_requested, deliverable.approved, deliverable.waived;
• note.created, note.edited, note.mentioned, note.pinned, note.redacted;
• comment.created, comment.replied, comment.resolved, comment.reopened;
• annotation.created, annotation.resolved;
• file_request.sent, file_request.submitted, file_request.reviewed;
• content.published, content.access_revoked.

Events include actor, Workspace, content/version, governing context, audience-safe summary, correlation ID and source. Consumers reauthorize actions.

30. Activity and Audit

30.1 User activity

Audience-filtered Activity shows material uploads, issue/publication, version, deliverable, Note/Comment and evidence events. High-volume derivative or scan jobs do not clutter ordinary activity.

30.2 Audit

Audit records upload/finalize, metadata/audience changes, record links, views/downloads where policy requires, publication/revocation, versioning, issue/supersession, Note edits, mention, conversion, annotation, deliverable review, export, archive, redaction, retention and impersonation.

30.3 Content history

File/document detail has a human-readable History tab distinct from security audit. It links to versions, Decisions, publications and related work.

31. Mobile and Offline

• Mobile supports camera upload, captions, room/item selection and evidence submission.
• Upload progress survives supported navigation and retries.
• Field users can queue safe Note drafts and evidence uploads offline.
• Final scan, publication, issue, Decision and deliverable completion require server confirmation.
• Image compression preserves original when governing evidence requires it.
• Large files default to preview rather than forced download.
• Annotations have touch-friendly controls and text alternatives.

32. Accessibility and Design System

• Meet WCAG 2.2 AA.
• File grid has keyboard-accessible list alternative.
• Preview controls, page navigation and annotation tools are labelled.
• Every material annotation/markup supports text description.
• Images support alt text/caption workflows.
• Status never relies on colour alone.
• Drag-and-drop has file picker equivalent.
• Upload progress and errors are announced.
• Focus returns correctly after viewer/dialog actions.
• Notes rich text preserves semantic structure.
• The module uses the existing black-and-white design, rounded controls, standardized dropdowns, date pickers, grids and modals.

33. Non-Functional Requirements

• Standard Library queries return first useful results within 1.5 seconds at p95.
• Large grids use pagination/virtualization.
• Upload finalization and version creation are idempotent.
• Scan failure never marks a file clean.
• Signed URLs are short-lived and generated only after current authorization.
• Derivative/OCR jobs are retryable and observable.
• Original checksums are stable and verified.
• Search/index updates honor access revocation promptly.
• Notes external-leak target is zero.
• A Project supports at least 100,000 metadata records through indexed queries without loading them all client-side.

34. Reporting and Analytics

• storage by Workspace/Project/type;
• upload/scan success and processing time;
• missing metadata/orphan rate;
• duplicate/reuse rate;
• version and supersession volume;
• deliverables on time, changes requested and approval cycle;
• Notes created/mentioned/converted to work;
• comments/annotations open and aging;
• publication/download engagement;
• file request completion;
• search success/no-result rate;
• retention/redaction queue;
• provider evidence completeness.

Analytics never expose content body or hidden filenames to unauthorized users.

35. Failure and Edge Cases

• Duplicate upload to two records: link one canonical File where audience permits.
• Same binary with different business meaning: allow separate File records referencing deduplicated object only under safe ownership.
• New version uploaded to wrong document: detach/relink before issue; audit correction.
• File becomes unsafe after improved scan: quarantine, revoke access and create incident.
• Publication accidentally targets wrong audience: revoke, invalidate access and audit; do not erase evidence of access.
• User mentioned without context access: block mention.
• Client/provider linked to Project asks for Internal Note: RLS denies existence/content.
• Annotation coordinates fail on new version: retain old anchor and request remapping.
• Signed URL copied after access removal: expiry/revocation prevents renewed access.
• Decision references superseded version: accepted version remains immutable and accessible according to policy.
• External upload exceeds limit or link expires: preserve safe retry instructions without granting broader access.
• Storage object exists without finalized metadata: cleanup/reconciliation queue.

36. Migration Plan

36.1 Inventory

• existing record Files tabs and upload records;
• Message attachments;
• Project drawings/deliverables;
• Notes and Note edit history;
• evidence/photos;
• existing storage objects and paths;
• external links and duplicated binaries;
• current visibility assumptions.

36.2 Normalize

• compute checksums;
• detect MIME/type safely;
• map categories/statuses;
• create typed record links;
• assign owning Workspace;
• classify audience conservatively;
• identify issued/accepted/signed references;
• flag uncertain/orphaned content for review.

36.3 Notes migration

• move Internal Notes to dedicated Note records;
• preserve author/time/edit history/attachments;
• ensure no external recipient/delivery fields exist;
• verify Client/Provider RLS denial;
• preserve activity/source links.

36.4 File migration

• preserve original binaries and checksums;
• generate safe opaque object paths;
• scan before broader availability;
• create version families only with reliable evidence;
• do not infer current/issued version solely from filename.

36.5 Validation

• compare counts and sample content by record;
• verify Message attachments still open;
• confirm formal records resolve exact versions;
• test audience isolation, search and signed access;
• reconcile orphan/duplicate queues.

36.6 Rollout

Use compatibility adapters and feature flags. Begin with read compatibility, migrate upload/write paths, then enable version/deliverable workflows. Retain rollback/read-only access until reconciliation passes.

37. Implementation Phases

Phase 1 — Canonical Files foundation

• File/object metadata and record links.
• Upload intents, scanning, previews and signed access.
• Existing Files grid compatibility.
• Audience/RLS baseline.

Phase 2 — Notes and comments

• Shared Notes service and existing modal migration.
• Mentions, edit history, pins and conversion.
• Comments and resolution.
• Hard external safety tests.

Phase 3 — Documents and versions

• Document families and version timeline.
• Issue, supersession and comparison.
• Drawing/specification metadata.
• Commercial/generated document lineage.

Phase 4 — Deliverables

• Deliverable Library and Project Template integration.
• Submission/review/gates.
• Provider Work Order requirements.
• Client publication links.

Phase 5 — Annotations and evidence

• PDF/image annotations and markups.
• Field evidence, galleries and media derivatives.
• Task/issue/Decision conversion.

Phase 6 — Library and discovery

• Global Library.
• Search, OCR, extraction and saved views.
• File requests and external uploads.

Phase 7 — Intelligence and governance

• AI classification/comparison/summaries.
• Advanced retention, legal hold, watermarking and analytics.
• External storage integrations later.

Every phase includes RLS, audit, accessibility, mobile, performance, migration and rollback tests.

38. User Stories

38.1 Designer

• I can find the current issued drawing without relying on filename conventions.
• I can add an internal Note to any Project record and safely mention a teammate.
• I can publish a design package to the client without exposing drafts or internal comments.
• I can convert a Note or annotation into accountable work.

38.2 Provider

• I can see the exact files required for my awarded Job and submit deliverables/evidence.
• I can keep my own authorized internal operational Notes without exposing them to the client.

38.3 Client

• I can see a curated library of published, clearly versioned files.
• I can comment on a presentation without accidentally approving it.

38.4 Registry operator

• I can investigate file access/publication history while respecting Workspace boundaries.

38.5 Project template administrator

• I can define required deliverables, metadata, audience and completion rules by phase/provider category.

39. Acceptance Criteria

39.1 Existing tool continuity

• Existing Files and Notes tabs continue to show their records.
• Existing file links open or safely redirect.
• Existing Note authors, timestamps, attachments and edits are preserved.
• Existing enterprise grid controls remain available.

39.2 Upload and security

• Uploads are authorized, finalized and scanned before ordinary access.
• MIME/type and size policies are enforced server-side.
• Quarantined files cannot be previewed/downloaded.
• Exact duplicates offer link/new-version/distinct options.
• Signed access fails after expiry or access removal.

39.3 Notes

• Notes live separately from Messages and have no external delivery fields.
• Client/Provider users cannot read internal Notes through API, search, realtime, notification, export or AI.
• Note edits preserve prior versions.
• Mention cannot grant access.
• Sharing Note content creates a reviewed separate draft.

39.4 Versioning

• Issued/published/accepted versions cannot be overwritten.
• New versions preserve parent, author, checksum and change summary.
• Current/superseded state is structural, not filename-based.
• Formal Decisions/commercial records resolve the exact governing version.

39.5 Deliverables

• Project Templates instantiate Deliverable requirements once.
• Submission references exact File/Document versions.
• Changes requested create a new submission path without erasing history.
• Gates validate required Deliverable states.
• Provider access is limited to assigned requirements and scope.

39.6 Comments/annotations/evidence

• Comments do not change approval state.
• Annotations remain anchored to a version and have accessible text.
• Evidence links to the exact operational record it proves.
• Client galleries require explicit publication.

39.7 Publication

• Publication preview shows audience and visible metadata.
• Published artifacts reference canonical versions without binary copies.
• Revocation ends future access while preserving audit.
• Client/provider views exclude internal metadata and Notes.

39.8 Search and AI

• Search returns only permitted results/snippets/thumbnails.
• Revoked access is removed from discovery promptly.
• AI context and output respect the same audience boundary.
• AI cannot issue, publish, approve, redact or delete content.

39.9 Retention and reliability

• Governing content cannot be hard-deleted through normal tools.
• Legal hold blocks prohibited deletion.
• Background jobs are idempotent, observable and recoverable.
• Derivatives follow source revocation/redaction.

40. Test Matrix

40.1 Audience isolation

• Designer Internal Note on client Project;
• provider private Note on assigned Work Order;
• client published file with hidden provider metadata;
• record link to two contexts with different audiences;
• access removed during open preview;
• search/AI request for hidden title/content.

40.2 Versioning

• simultaneous new-version upload;
• issued version replacement attempt;
• superseded version linked to accepted Decision;
• invalid revision code;
• annotation migration between changed pages;
• generated document reproduced from snapshot.

40.3 Upload/processing

• large resumable upload;
• content-type mismatch;
• malware/quarantine;
• scan timeout/retry;
• duplicate binary;
• orphan temporary object cleanup;
• derivative failure with original still safe.

40.4 Notes/comments

• edit and version history;
• unauthorized mention;
• Note-to-Message reviewed copy;
• client attempts direct Note route;
• comment resolved without changing Decision;
• Note redaction under legal hold.

40.5 Deliverables/evidence

• template instantiation retry;
• provider changes requested/resubmission;
• gate with missing evidence;
• waiver with/without permission;
• offline field evidence retry;
• published client gallery from approved evidence.

41. Definition of Done

• Canonical content types and boundaries are implemented.
• Existing Files/Notes data reconciles with no loss of history.
• RLS and signed access tests pass for every Workspace type.
• Notes cannot enter external delivery paths.
• Upload scanning/quarantine and recovery runbooks are operational.
• Version/issue/publication workflows preserve immutable history.
• Project Builder can define and instantiate Deliverables.
• Client/provider publication uses canonical versions.
• Search, previews, OCR, AI and exports are security-trimmed.
• Retention/redaction/legal-hold policies are tested.
• Mobile and accessibility QA pass.
• Notification templates exist for all required events.
• Observability, feature flags and rollback are ready.

42. Final Product Direction

The Design Registry’s content system should eliminate the gap between where work happens and where its evidence, decisions and history are stored. A drawing should not become disconnected when it is emailed, published to a client, sent to a millworker or used to satisfy a phase gate. A photograph should remain connected to the item, delivery or deficiency it proves. A Note should help the internal team collaborate without ever becoming an accidental client message.

The platform becomes trustworthy when every user can understand which content is current, who can see it, what it relates to and what happened next. Files provide the binary. Documents provide business meaning. Versions preserve truth over time. Deliverables define expected outcomes. Notes support private collaboration. Comments and annotations create precise discussion. Decisions create formal authority. Activity preserves history. By keeping these distinctions and reusing one secure content foundation everywhere, The Design Registry can offer a cleaner experience than spreadsheets, inboxes and shared drives while remaining safe enough to operate an entire Project network.

43. Live-product correction contract — Activity and History

The current record-tab pattern can render the same events in both Activity and History. The future architecture must enforce distinct contracts:

• Activity is a permission-scoped, participant-readable operational projection containing external touchpoints, tasks, notes, files, decisions, approvals and other meaningful work events.
• History is the immutable audit projection for material data changes, security-sensitive actions, administrative access, permission changes and command outcomes.
• An event may contribute to both projections only through separate audience-safe representations; the two tabs must never be identical aliases.
• Every Activity event stores stable event type, actor, occurred time, recorded time, visibility, canonical record links and a safe display snapshot.
• Internal Notes and restricted Files must never leak through event titles, counts, search results or exports.
• Overview timelines use the same authorized Activity source and link to the full event rather than maintaining a second editable history.
• Customer touchpoint must be replaced by External touchpoint unless the participant is specifically a Client.

<!-- CURRENT-PRODUCT-GAP-COVERAGE:START -->

Current-product review gap closure register

Generated: August 4, 2026
Owning future specification: 14
Mapped current-product profiles: 4
Recorded review gaps: 17

This register is part of the release contract. It maps the current-product reverse review into required future behavior. A gap is not closed because a screen exists; closure requires the corrected canonical data, permissions, states, migration, audit and test evidence described below.

Register rules

1. Every profile in the Current Product Library must resolve to one owning future specification.
2. Current limitations are evidence, not optional ideas. If a limitation is intentionally retained, the specification must record the decision, risk, owner and review date.
3. Shared-component defects are corrected through Spec 16 and then consumed here; feature teams may not create local replacement controls.
4. Permission, contact, financial and visibility defects also require Spec 08 enforcement, even when the functional feature is owned by another specification.
5. Legacy Proper Gallery, Lead, Partner and implementation-facing labels are migration inputs only and must not return through new UI, APIs, exports or notifications.
6. Verification must use realistic fixtures for Admin, Designer, Provider and Client audiences where applicable.

G01 — Record Activity

Current-product profile: record-activity
Observed route: /admin/leads/:id?tab=activity
Evidence confidence: Verified

Review gaps

• The live record has no events, so filtering accuracy was not tested.
• No pagination, export or event-detail drawer was observed.
• Relationship between Activity and the separate History tab is unresolved.
• Raw technical events have appeared elsewhere on the dashboard, suggesting presentation normalization is incomplete.

Required future closure

• Define a canonical event taxonomy shared by Activity, Notifications and reporting.
• Replace Customer Touchpoint with External Touchpoint plus the identified participant type.
• Separate participant-facing Activity from immutable security and audit history.
• Normalize event copy and link each event to its source.
• Support permissions and retention by event visibility class.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G02 — Record Notes

Current-product profile: record-notes
Observed route: /admin/leads/:id?tab=notes
Evidence confidence: Verified

Review gaps

• Revision history and edited markers were not observed.
• Attachment limits, scanning and preview behavior are unverified.
• Mention autocomplete and notification delivery were not tested.
• There is no observed pinning, categorization or decision-note type.
• Client-visible notes require a separate, explicit model.

Required future closure

• Reuse Notes across records and Projects with explicit visibility classes.
• Add immutable revisions and source-linked Activity events.
• Provide note categories, pins and decision records without weakening simple capture.
• Keep AI suggestions reviewable and fact-preserving.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G03 — Record Files

Current-product profile: record-files
Observed route: /admin/leads/:id?tab=files
Evidence confidence: Verified

Review gaps

• Upload progress, retry and failure behavior are unverified.
• Versioning, folders, tags, preview and approval status are not visible.
• Retention and deletion rules are not documented in the current UI.
• External cloud-file links and Project inheritance are unverified.

Required future closure

• Create one file service reused by records, Projects, tasks, messages, POs and provider operations.
• Add versioning, classification, previews and source linkage.
• Support client/provider visibility without copying the file.
• Preserve audit evidence for replacement, archive and access.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

G04 — Record History

Current-product profile: record-history
Observed route: /admin/leads/:id?tab=history
Evidence confidence: Known limitation

Review gaps

• Dedicated History content is missing.
• Activity/History boundaries and the View complete history label are inconsistent.
• No before/after, actor, correlation, export or retention behavior is evidenced.
• Coming soon provides no alternate audit access for authorized operators.

Required future closure

• Define the Activity versus Audit History contract in Spec 14.
• Create normalized human-readable event copy backed by immutable data.
• Add critical-change filters, correlation and authorized export.
• Replace the disabled placeholder only when dedicated empty, populated, restricted and failure states exist.

Closure evidence required

• The corrected behavior is demonstrated in the relevant loading, empty, populated, error, permission and responsive states.
• Server-side rules, data migration and audit behavior are verified where this feature changes canonical records.
• Automated tests cover the identified defect or missing journey so it cannot silently regress.
• Product, Engineering and the operating owner accept any deliberately deferred item with an owner and target phase.

<!-- CURRENT-PRODUCT-GAP-COVERAGE:END -->