Skip to main content

Architecture

Chronicle’s architecture is designed for real-time collaboration, temporal navigation, and auditability.

System Overview

                        ┌──────────────────────────────────────┐
                        │           Chronicle App              │
                        │         (Next.js Frontend)           │
                        └─────────────────┬────────────────────┘

                                    WebSocket

                        ┌─────────────────▼────────────────────┐
                        │         Chronicle Relay              │
                        │       (Rust/Axum Service)            │
                        │                                      │
                        │  • WebSocket management              │
                        │  • Operation broadcast               │
                        │  • Presence tracking                 │
                        │  • Session management                │
                        └─────────────────┬────────────────────┘

              ┌───────────────────────────┼───────────────────────────┐
              │                           │                           │
    ┌─────────▼─────────┐       ┌─────────▼─────────┐       ┌─────────▼─────────┐
    │     fork-node     │       │     vest-node     │       │     tnp-node      │
    │                   │       │                   │       │                   │
    │  CRDT Operations  │       │   Audit Trail     │       │ Temporal Queries  │
    │  • LSEQ algorithm │       │   • Proofs        │       │  • Point-in-time  │
    │  • Merge logic    │       │   • Verification  │       │  • History ranges │
    │  • Conflict-free  │       │   • Immutable     │       │  • Diff views     │
    └───────────────────┘       └───────────────────┘       └───────────────────┘

Core Components

Editor Package (@chronicle-hq/editor)

The editor package provides:
  • EditorState - Immutable document state
  • EditorView - DOM rendering and events
  • Transaction - State change representation
  • Selection - Cursor/selection management
  • Schema - Document structure definition

Plugins

  • TimelinePlugin - Temporal navigation UI
  • HistoryPlugin - Local undo/redo

Adapters

  • TimechainAdapter - CRDT operations via fork-node
  • PresenceAdapter - Real-time presence via relay

Relay Service

The relay handles:
  1. WebSocket Connections - Client connection management
  2. Operation Relay - Broadcasting CRDT operations
  3. Presence - Cursor and user status
  4. Session Management - Connection lifecycle

Protocol Integration

fork-node (CRDT)

Provides LSEQ-based CRDT operations:
  • Insert, delete, format operations
  • Automatic conflict resolution
  • Deterministic merge

vest-node (Audit)

Provides verifiable audit trail:
  • Cryptographic proofs for each operation
  • Immutable history
  • Verification endpoints

tnp-node (Temporal)

Provides temporal navigation:
  • Point-in-time document reconstruction
  • History range queries
  • Diff generation

Data Flow

Edit Operation

1. User types in editor
2. Editor creates Transaction
3. Transaction converted to CRDTOperation
4. Operation sent to Relay via WebSocket
5. Relay broadcasts to other clients
6. Relay forwards to fork-node for CRDT merge
7. vest-node records proof
8. Other clients receive and apply operation

Timeline Navigation

1. User drags timeline slider
2. TimelinePlugin captures timestamp
3. Request sent to tnp-node
4. tnp-node reconstructs document state
5. Editor displays historical view
6. User can return to present

Security

  • aegis-node handles all authorization
  • Document permissions: view, comment, edit, admin
  • All operations include user identity
  • Audit trail provides accountability

Scalability

  • Relay instances are stateless (can scale horizontally)
  • CRDT operations are order-independent
  • Protocol nodes handle persistence