Versioning System Architecture

System design, data flow, and architectural decisions

System Overview

The Universal Versioning System is a relational database-backed solution for tracking all changes to entities throughout their lifecycle. It uses PostgreSQL triggers, session variables, and type-safe relational tables to provide automatic, transparent versioning.

Design Philosophy

Core Principles

Automatic & Transparent - Versioning happens automatically via triggers
Pure Relational - No JSONB storage, all fields are typed columns
Audit-First - Every change is attributed to a user and optionally a submission
Type-Safe - Foreign keys and constraints enforce data integrity
Performance-Conscious - Proper indexing and cleanup mechanisms

Why Not JSONB?

The previous system stored versions as JSONB blobs. We migrated to relational for:

Issue with JSONB	Relational Solution
Not queryable without JSONB operators	Standard SQL WHERE clauses
No type safety	Column-level types and constraints
Poor performance on large datasets	Indexed columns
Can't use foreign keys	Full referential integrity
Complex RLS policies	Standard column-level RLS

High-Level Architecture

graph TB
    subgraph "Frontend Layer"
        UI[React Components]
        HOOKS[React Hooks]
    end
    
    subgraph "Backend Layer"
        EDGE[Edge Functions]
        DB[(PostgreSQL)]
        TRIGGERS[Database Triggers]
    end
    
    UI --> HOOKS
    HOOKS --> DB
    EDGE --> SESSION[Set Session Variables]
    SESSION --> DB
    DB --> TRIGGERS
    TRIGGERS --> VERSIONS[Version Tables]
    
    style VERSIONS fill:#4CAF50
    style TRIGGERS fill:#2196F3
    style SESSION fill:#FF9800

1.8 KiB Raw Blame History