Technical Specification: Document Module

This document details the technical architecture, technology stack, and integration patterns for the Document module.

v1.0 — ApprovedPlatform: VENI-AI ShellStack: Bun/Ignis/Hono

---

1. High-Level Architecture

The Document module is built as an SCS (Self-Contained System) with a custom versioning engine and a rich-text processing pipeline.

Component Diagram

---

2. Technology Stack

Backend (API)

• Runtime: Bun
• Framework: Ignis Framework
• Router: Hono
• ORM: Drizzle ORM
• Database: PostgreSQL (with Full-Text Search enabled)

Frontend (UI)

• Library: React 18
• Editor Engine: TipTap (Headless wrapper for Prosemirror)
• Build Tool: Vite
• Styling: Tailwind CSS v4 + ARDOR UI Kit

---

3. Core Implementation Logic

3.1 Content Persistence

Instead of raw HTML, the module stores document content as TipTap JSON. This allows for:

• Reliable version diffing.
• Easier cross-platform rendering.
• Structured data extraction (e.g., auto-generating TOC).

3.2 Version Control Engine

Every PUT /api/documents/:id creates a new record in document_versions.

• Concurrency: Basic optimistic locking using the updatedAt timestamp.
• Rollback: Restoring a version involves cloning an old document_versions record and setting it as the new currentVersionId.

3.3 Full-Text Search

Implemented via PostgreSQL's native tsvector.

• When a document is published, the API generates a weighted searchVector combining the Title (weight A) and the plaintext extracted from the JSON content (weight B).

---

4. Integration Details

4.1 Shell Auth

• Document extracts organizationId and userId from the Platform JWT.
• Authorization is checked against the Shell's RBAC: documents:read, documents:write, documents:publish.

4.2 Cross-Module Usage

• AI Assistant: Indexes published documents in its knowledge base (Vector Store) via a post-publication webhook.

---

Related Links

• Unified SRS Hub
• Database Schema
• API Reference