Core Concepts

Understanding these concepts will help you build better applications with Gluonic.

Gluonic is a sync engine - it handles data synchronization between client and server with offline support, real-time updates, and optimistic UI. What makes it unique is how you access that synchronized data - through a synchronous API that eliminates loading states and complex async patterns.

Sync Engine Concepts

These are the core features of any production sync engine:

Offline-First

Core sync engine feature: Your app works without network connectivity.

How it works:

Data stored in local database (via Drizzle adapter)
All operations work against local database
Changes sync to server in the background when connected
No network = no problem

Optimistic Updates

Core sync engine feature: UI updates immediately before server confirmation.

How it works:

User edits → applied to memory instantly
UI re-renders immediately (optimistic)
Change queued for server sync
Server confirms → persisted to local database
Server rejects → rolled back from memory

Delta Synchronization

Core sync engine feature: Only sync what changed, not the entire dataset.

How it works:

Client tracks lastSyncId (last change seen)
Server returns changes since lastSyncId
Client applies incremental updates
Both sides stay in sync efficiently

Real-Time Sync

Core sync engine feature: Changes propagate instantly via WebSocket.

How it works:

WebSocket connection for push updates
Server broadcasts changes to all connected clients
Client applies changes to local state
UI updates automatically

Unique: Synchronous Data Access

These concepts are what make Gluonic’s developer experience unique:

Synchronous API

Gluonic’s differentiator: Access async data through a synchronous API with two patterns.

Progressive pattern:


const author = issue.author.value?.name  // Handle with optionals

Suspense pattern:


const author = issue.author.suspense.name  // Guaranteed loaded

Both avoid async/await in components - that’s what makes them “synchronous”.

Object Graph

Enables synchronous access: Connected model instances that form a graph structure.

Structure:


Team
  ├── issues → LazyCollection<Issue>
  
Issue
  ├── assignee → LazyReference<User>
  ├── comments → LazyCollection<Comment>

Navigate the graph synchronously - relationships load on-demand.

Lazy Collections

How synchronous works: Collections that load data on-demand while feeling synchronous.

API:


team.issues.map(...)  // Returns [], kicks hydration
team.issues.suspense  // Throws promise for Suspense

Lazy References

How synchronous works: Object references that load on-demand.

API:


issue.author.value  // May be undefined, kicks hydration
issue.author.suspense  // Guaranteed loaded (throws promise)

Hydration

The loading mechanism: Process of loading data into memory from storage or network.

Types:

Automatic: Accessing data triggers hydration
Explicit: await model.hydrate()
Recursive: await model.hydrate(depth)

React Suspense

Guaranteed data pattern: Use Suspense boundaries for clean component code.

API:


<Suspense fallback={<Spinner />}>
  <Component />  {/* Use .suspense accessors inside */}
</Suspense>

Supporting Concepts

These concepts support the sync engine and synchronous API:

ObjectPool

In-memory storage: MobX observable map holding all current data.

Flat storage of WireRows that forms the foundation for the Object Graph.

Deferred Persistence

Optimistic updates: Separate memory (optimistic) from storage (confirmed).

Why optimistic changes live in ObjectPool, not storage, until confirmed by server.

Identity Mapping

Consistency: Same ID always returns the same instance.

Ensures referential equality and efficient React rendering.

Reactive Models

Automatic updates: MobX-powered models that trigger re-renders.

How components automatically update when data changes.

Model Loader

Transparent loading: Tries local storage first, falls back to network.

The abstraction that enables synchronous data access despite async sources.

Batch Loader

Performance: Intelligent request batching and deduplication (coming soon).

Prevents N+1 queries when accessing collections for multiple models.

Next Steps

Now that you understand core concepts:

Dive into Architecture - See how it all fits together
Follow Quick Start - Build your first app
Explore Examples - See it in action

Last updated on October 31, 2025

Introduction Offline-First