PSA/ee/docs/plans/2026-02-27-documents-system-improvements/PRD.md

PRD: Documents System Improvements

• Slug: 2026-02-27-documents-system-improvements
• Date: 2026-02-27
• Status: Draft

Summary

A 5-phase overhaul of the Alga PSA documents system to add entity-scoped folders, admin-configurable folder templates, client portal visibility controls, shareable document URLs, and a knowledge base foundation. The system is designed so that each phase builds on the previous ones, with the entire document infrastructure serving as the foundation for a full MSP knowledge base.

Problem

The current documents system has several gaps that limit its value for MSPs:

1. Flat folders per tenant — Folders are global to the tenant. A client, project, or ticket cannot have its own private folder tree. This means all users see one giant folder structure that mixes documents from every entity.
2. No visibility control for clients — There is no is_client_visible flag. MSPs cannot control which documents clients see on the portal. The client portal only shows documents embedded in individual tickets and project tasks — no central Documents page.
3. No folder templates — Every folder is manually created. There is no way for an admin to define a standard structure (e.g., "Contracts / Invoices / Meeting Notes") that auto-applies to new clients.
4. No auto-filing — Uploading a ticket attachment doesn't place it in any folder. Documents accumulate without organization.
5. No shareable links — There is no way to generate a URL that allows external access to a document (public or authenticated).
6. No knowledge base — Documents exist as files and rich-text notes, but there is no article concept, publishing workflow, review cycle, or audience targeting. MSPs must use separate tools (IT Glue, Hudu) for KB, losing the integrated advantage.

Goals

1. Entity-scoped folders — Each client, project, ticket, and contract gets its own folder tree, isolated from others.
2. Visibility toggle — MSP users can mark documents/folders as client-visible with a single click. Clients never see internal-only documents.
3. Folder templates — Admins define folder structures per entity type. Templates are applied lazily on first document access.
4. Auto-filing — Uploads are automatically placed in the correct folder based on entity type and context.
5. Client portal Documents hub — A dedicated Documents page in the client portal aggregating all client-visible documents with folder browsing, search, and filtering.
6. Share URLs — MSP users can generate public, portal-authenticated, or password-protected share links for any document.
7. Knowledge base foundation — KB articles built as a document subtype with audience targeting, publishing workflow, review cycles, and category/tag taxonomy. Both internal and client-facing KB supported.

Non-Goals

• AI-powered article generation or smart suggestions (future work, Phase 5 lays the foundation)
• Real-time collaborative editing of KB articles (existing Hocuspocus/Yjs infrastructure handles this for documents already)
• Document import from IT Glue / Hudu / Confluence (separate migration initiative)
• Credential / password vault (separate feature)
• Document retention policies / auto-archival
• E-signature integration
• Full-text search engine (e.g., Elasticsearch) — uses PostgreSQL text search for now

Users and Primary Flows

Personas

Persona	Description
MSP Admin	Configures folder templates, manages visibility settings, creates KB articles
MSP Technician	Uploads documents to entities, uses KB articles for troubleshooting, generates share links
Client Contact (Portal)	Views shared documents, browses external KB articles, downloads files via share links
External Recipient	Accesses documents via public share URLs without any account

Primary Flows

Flow 1: MSP Admin configures folder template

1. Admin navigates to Settings → Document Templates
2. Creates template "MSP Client Default" for entity type "client"
3. Defines folder tree: /Contracts, /Contracts/SLAs, /Invoices, /Meeting Notes, /Technical Documentation
4. Sets /Contracts and /Invoices as client-visible
5. Marks template as default for "client"

Flow 2: Technician opens client Documents tab (lazy folder init)

1. Technician navigates to Client → Documents tab
2. System checks document_entity_folder_init — no record found
3. System applies default "client" template → creates entity-scoped folders
4. Folder tree renders with pre-created structure
5. Technician uploads a contract → auto-filed to /Contracts

Flow 3: MSP user toggles document visibility

1. In Documents list, user sees eye icon next to each document
2. Clicks to toggle is_client_visible → eye icon changes state
3. Document is now visible in client portal Documents hub
4. Bulk select + toggle also supported

Flow 4: Client views Documents hub in portal

1. Client contact logs into portal
2. Navigates to "Documents" tab in top nav
3. Sees folder tree of only client-visible folders
4. Browses by folder, searches by name, filters by source (tickets/projects/contracts)
5. Views/downloads documents

Flow 5: MSP user generates share link

1. Right-clicks document → "Share"
2. Dialog opens with share type selector (Public / Portal Auth / Password Protected)
3. Sets optional expiry and max downloads
4. Clicks "Generate" → URL with copy button appears
5. Shares URL with recipient

Flow 6: MSP user creates KB article

1. Navigates to Knowledge Base section
2. Clicks "New Article" → selects template (e.g., "Troubleshooting Guide")
3. Editor opens with template structure pre-filled
4. Sets audience to "client", category to "FAQs"
5. Writes content using BlockNote editor
6. Submits for review → reviewer approves → article published
7. Published article automatically appears in client portal KB section

UX / UI Notes

Phase 1 — Entity Mode Folder Tree

• Documents component in entity mode gains a collapsible folder sidebar (same as global folder mode, but scoped to entity)
• Eye icon (visibility toggle) appears on each document row/card and each folder in the tree
• Eye icon only rendered for MSP users, not in client portal context

Phase 3 — Client Portal Documents Hub

• New top-level nav item "Documents" between "Projects" and "Appointments"
• Left sidebar: folder tree (read-only, no create/delete)
• Main area: document grid/list with cards showing name, type icon, date, source entity badge
• Filter bar: search, source type dropdown (Tickets / Projects / Contracts / All), date range

Phase 4 — Share Link Dialog

• Modal dialog launched from document context menu
• Three share type cards with radio selection
• Password input, date picker, number input for max downloads
• Generated URL shown in copyable input field
• List of existing share links below with status, copy, and revoke actions

Phase 4 — Public Share Landing Page

• Minimal standalone page (not wrapped in MSP or portal layout)
• Shows: document name, file type icon, file size, expiry countdown
• Password input if password-protected
• Large "Download" button
• Tenant branding (logo) if available

Phase 5 — KB Article Editor

• Same BlockNote editor as regular documents
• Metadata sidebar panel: audience selector, article type, category picker, review cycle, related articles
• Status bar at top: Draft / In Review / Published / Archived with transition buttons

Requirements

Functional Requirements

Phase 1: Entity-Scoped Folders + Visibility

ID	Requirement
FR-1.1	document_folders gains entity_id and entity_type columns. When set, folder is scoped to that entity. When NULL, folder is global (current behavior).
FR-1.2	Same folder_path can exist for different entities (unique constraint includes entity scope).
FR-1.3	documents and document_folders gain is_client_visible boolean column, default false.
FR-1.4	getFolderTree() accepts optional entityId/entityType params and returns only matching folders.
FR-1.5	getDocumentsByFolder() respects entity scope.
FR-1.6	createFolder() accepts entityId, entityType, isClientVisible.
FR-1.7	toggleDocumentVisibility(documentIds, isClientVisible) bulk-toggles visibility.
FR-1.8	toggleFolderVisibility(folderId, isClientVisible, cascade?) toggles folder and optionally cascades to contained documents.
FR-1.9	Documents component in entity mode shows folder tree sidebar.
FR-1.10	Visibility toggle (eye icon) shown on documents and folders in MSP context only.
FR-1.11	document_folders has RLS tenant isolation policies.
FR-1.12	ensureEntityFolders(entityId, entityType) stub returns empty tree (Phase 2 fills in logic).

Phase 2: Folder Templates + Auto-Filing

ID	Requirement
FR-2.1	document_folder_templates table stores template name, entity type, and default flag per tenant.
FR-2.2	document_folder_template_items table stores the folder tree structure for each template.
FR-2.3	document_entity_folder_init table tracks which entities have had folders initialized.
FR-2.4	At most one template per entity type per tenant can be marked as default (partial unique index).
FR-2.5	Admin can CRUD folder templates via Settings → Document Templates.
FR-2.6	ensureEntityFolders() checks init tracker, applies default template if uninitialized, records init.
FR-2.7	Template application is idempotent — skips folders that already exist.
FR-2.8	uploadDocument() auto-files: if entity has a matching folder, sets folder_path. Best-effort — never fails the upload.
FR-2.9	Template editor supports drag-and-drop reorder, add/remove folders, client-visibility toggles per folder.
FR-2.10	Documents component in entity mode calls ensureEntityFolders() on mount.

Phase 3: Client Portal Documents Hub

ID	Requirement
FR-3.1	New "Documents" page in client portal at /client-portal/documents.
FR-3.2	"Documents" link added to client portal top navigation.
FR-3.3	getClientDocuments() returns paginated docs where is_client_visible = true AND associated with authenticated user's client.
FR-3.4	Aggregates documents across: direct client associations, client's tickets, client's project tasks, client's contracts.
FR-3.5	getClientDocumentFolders() returns folder tree for client-visible folders only.
FR-3.6	Client portal documents page shows folder tree (read-only), document grid/list, search, and filters.
FR-3.7	Client A can NEVER see client B's documents (enforced at query level via client_id filter).
FR-3.8	downloadClientDocument() verifies both is_client_visible and client ownership before serving.
FR-3.9	File view API route extended to check is_client_visible for client users.
FR-3.10	Existing inline ticket document display continues working unchanged (does not require is_client_visible).

Phase 4: Document Share URLs

ID	Requirement
FR-4.1	document_share_links table stores share token, type, password hash, expiry, max downloads, revocation status.
FR-4.2	document_share_access_log table records every access with IP, user agent, timestamp.
FR-4.3	createShareLink() generates 256-bit cryptographically random token.
FR-4.4	Three share types: public (no auth), portal_authenticated (portal login required), password_protected.
FR-4.5	Share links support optional expiry date and max download count.
FR-4.6	Public share route (/api/share/[token]) works without session.
FR-4.7	Password-protected links require password verification before download.
FR-4.8	Portal-authenticated links require active client portal session and verify client access.
FR-4.9	Share info route (/api/share/[token]/info) returns document metadata without downloading.
FR-4.10	Public landing page at /share/[token] shows document info and download button.
FR-4.11	ShareLinkDialog component allows creating/listing/revoking share links from document context menu.
FR-4.12	Access is logged and download count incremented on each access.
FR-4.13	MSP users can revoke any share link at any time.

Phase 5: Knowledge Base Foundation

ID	Requirement
FR-5.1	kb_articles table extends documents — every article has a parent document (inherits content, versions, associations).
FR-5.2	Article types: sop, runbook, troubleshooting, faq, how_to, reference, policy.
FR-5.3	Audience targeting: internal, client, public.
FR-5.4	Publishing workflow: draft → in_review → published → archived.
FR-5.5	Publishing an article with audience = 'client' auto-sets parent document's is_client_visible = true.
FR-5.6	Archiving clears is_client_visible on parent document.
FR-5.7	Review cycle: configurable review_cycle_days, next_review_due, staleness indicators.
FR-5.8	Review assignment: submit for review to specific users, reviewers approve or request changes.
FR-5.9	kb_article_relations for related/prerequisite/supersedes linking.
FR-5.10	kb_article_templates for pre-built article structures (BlockNote JSON).
FR-5.11	MSP KB section: article list with filters, article editor with metadata sidebar, publishing controls, review dashboard.
FR-5.12	Client portal KB section: published client-audience articles with category browsing, search, "was this helpful?" feedback.
FR-5.13	Articles can be tagged via existing tag system (tagged_type = 'knowledge_base_article').
FR-5.14	createArticleFromTicket() pre-populates article from ticket data (foundation for AI enhancement).
FR-5.15	View count and helpfulness tracking (helpful_count, not_helpful_count).
FR-5.16	URL-friendly slug per article, unique per tenant.

Non-functional Requirements

ID	Requirement
NFR-1	All new tables use composite keys with tenant and RLS tenant isolation policies.
NFR-2	All new tables include inline distributeIfCitus() calls within the same migration file (not separate Citus migrations). Pattern: define helper at top of migration, call after each createTable. See server/migrations/20260219000001_create_sla_policies.cjs for reference.
NFR-3	No database triggers (Citus constraint).
NFR-4	Share token validation must not use tenant-scoped connection (uses admin connection).
NFR-5	Client portal queries must always filter by authenticated user's client_id — no exceptions.
NFR-6	Existing document flows (upload, download, entity mode, folder mode) must not regress.

Data / API / Integrations

New Database Tables (by phase)

Phase 1: Columns added to document_folders (entity_id, entity_type) and documents/document_folders (is_client_visible).

Phase 2: document_folder_templates, document_folder_template_items, document_entity_folder_init

Phase 4: document_share_links, document_share_access_log

Phase 5: kb_articles, kb_article_relations, kb_article_templates, kb_article_reviewers

New API Routes

Route	Phase	Auth	Description
GET /api/share/[token]	4	None/Conditional	Download shared document
GET /api/share/[token]/info	4	None	Get share metadata
GET /share/[token] (page)	4	None	Public share landing page

New Server Action Files

File	Phase	Description
packages/documents/src/actions/folderTemplateActions.ts	2	Template CRUD, apply template
packages/documents/src/actions/shareActions.ts	4	Share link CRUD, token validation
packages/documents/src/actions/kbActions.ts	5	Article CRUD, publishing, review
packages/client-portal/src/actions/client-portal-actions/client-documents.ts	3	Client portal document queries

Security / Permissions

• Tenant isolation: All tables use RLS. All queries include tenant filter.
• Client isolation: Client portal queries derive client_id from authenticated user → contact → client chain. Never trust client-provided IDs.
• Share URL security: Tokens are 256-bit cryptographically random. Public routes use admin connection for lookup, then set tenant context. Password-protected links use bcrypt hashing.
• Visibility enforcement: is_client_visible = false by default. MSP explicitly controls what clients see.
• RBAC: Existing document:read/create/update permissions enforced for client portal users. MSP users require corresponding entity permissions.

Rollout / Migration

Phase Order and Dependencies

Phase 1 (Entity-Scoped Folders + Visibility)
  ├──→ Phase 2 (Folder Templates + Auto-Filing)
  ├──→ Phase 3 (Client Portal Documents Hub)
  ├──→ Phase 4 (Share URLs) — can parallel with P2/P3
  └──→ Phase 5 (Knowledge Base) — needs P1 + P3

Migration Safety

• Phase 1 migrations add nullable columns and a new default-false boolean — no data transformation needed.
• Unique constraint change on document_folders must handle existing NULL entity_id rows correctly (uses COALESCE).
• is_client_visible defaults to false — all existing documents remain invisible to clients until explicitly toggled. This is intentionally conservative.

Open Questions

1. Should the client portal Documents page be behind a feature flag initially?
2. Should folder templates be seeded with defaults (e.g., "MSP Client Default") or start empty?
3. For KB articles, should audience = 'public' articles be accessible without any login at all?

Acceptance Criteria (Definition of Done)

Phase 1

• Entity-scoped folders can be created for clients, projects, tickets, contracts
• Two different clients can have folders with the same path
• is_client_visible toggle works on documents and folders
• Existing global folders still work (regression test)
• Documents component in entity mode shows folder tree sidebar

Phase 2

• Admin can create/edit/delete folder templates
• Default template is applied lazily on first entity document access
• Template application is idempotent
• Document uploads auto-file into matching entity folders
• Admin UI for template management is functional

Phase 3

• Client portal has "Documents" nav item and page
• Only is_client_visible = true documents appear
• Client A cannot see client B's documents
• Folder tree, search, and source filters work
• Download works with proper permission checks

Phase 4

• Public share link works in incognito (no auth)
• Portal-authenticated link requires login
• Password-protected link requires password
• Expiry and max download limits enforced
• Revocation immediately invalidates the link
• Access logging records every download

Phase 5

• KB article created as document subtype (dual identity)
• Publishing with audience='client' makes article visible in portal
• Archiving removes portal visibility
• Review cycle and staleness indicators work
• Article templates populate editor with structure
• Tags and categories are functional
• Client portal KB section shows published client articles with feedback