Architecture

Understand how Gluonic works under the hood.

Overview

Gluonic is built on a three-layer architecture that separates concerns and enables offline-first, reactive data synchronization.

Topics

System Overview - High-level architecture
Data Pipeline - How data flows
Sync Protocol - Bootstrap, delta, realtime
How Reactivity Works - MobX + Proxy magic

Architecture Diagram


┌─────────────────────────────────────────────┐
│           React Components                   │
│  (observer HOC, useModel, useCollection)    │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│            Reactive Models                   │
│  (Proxy, LazyReference, LazyCollection)     │
│  - Identity mapping                          │
│  - Lazy loading                              │
│  - Computed properties                       │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│            Data Store                        │
│  (Store, ObjectPool, Adapters)              │
│  - Observable pool (current state)           │
│  - Transaction queue (pending changes)       │
│  - Storage adapter (confirmed data)          │
└────────────────┬────────────────────────────┘
                 │
┌────────────────▼────────────────────────────┐
│            Sync Protocol                     │
│  (Bootstrap, Delta, WebSocket, Mutations)   │
│  - HTTP for bootstrap/delta                  │
│  - WebSocket for real-time                   │
│  - POST /tx for mutations                    │
└─────────────────────────────────────────────┘

Design Principles

1. Local-First

Data is stored locally first, then synced to server.

2. Single Source of Truth

The ObjectPool is the sole data source for UI.

3. Reactive by Default

MobX makes everything automatically reactive.

4. Optimistic Concurrency

Apply changes immediately, rollback if server rejects.

5. Identity Mapping

Same data ID always returns same object instance.

6. Lazy Everything

Load data only when actually needed.

Next Steps

System Overview - Complete architecture
Data Pipeline - Data flow details
Core Concepts - Fundamental ideas