Architecture Overview

​

Core Components

​

System Architecture

​

Data Flow

​

Write Operations

1. Application Layer: Call db.put(data)
2. Security Check: If Security Manager is enabled, verify user has write permission
3. Timestamp Generation: Hybrid Logical Clock assigns a causal timestamp
4. Local Write: Data is written to in-memory graph with timestamp
5. Operation Logging: Write operation is appended to the OpLog
6. Persistence: OPFS Worker saves the graph state to disk (debounced)
7. Network Broadcast: If RTC enabled, operation is signed and broadcast to peers
8. Peer Reception: Remote peers verify signature, check permissions, and apply via CRDT conflict resolution

// Example write with full data flow
const db = await gdb('mydb', { 
  rtc: true,
  sm: { superAdmins: ['0x...'] }
});

// This triggers the entire flow described above
const id = await db.put({ 
  title: 'Hello World',
  timestamp: Date.now()
});

​

Read Operations

1. Query Parsing: Parse query parameters and filters
2. In-Memory Lookup: Retrieve data directly from the in-memory graph
3. Index Utilization: Use radix tree indexes if available for fast filtering
4. Graph Traversal: For $edge queries, recursively traverse relationships
5. Permission Filtering: If ACLs enabled, filter nodes based on user permissions
6. Return Results: Stream results to the callback or return promise

// Fast in-memory reads
const { result } = await db.get('node-id');

// Reactive subscriptions
const { unsubscribe } = await db.map(({ id, value }) => {
  console.log('Node updated:', id, value);
}, {
  query: { status: 'active' },
  order: 'desc',
  field: 'timestamp'
});

​

Synchronization Flow

​

Key Design Principles

​

1. Local-First Architecture

• All reads from in-memory graph (microsecond latency)
• Writes are synchronous to memory, asynchronous to disk
• Network sync happens in the background
• Works fully offline with automatic sync on reconnection

​

2. Eventual Consistency

• All peers converge to the same state eventually
• Conflicts are resolved deterministically using Last-Write-Wins
• No central coordinator needed
• Network partitions are handled gracefully

​

3. Zero-Trust Security

• Cryptographic signatures prove authenticity
• Role-based permissions enforce authorization
• No operation is trusted by default
• Security rules are embedded in the graph itself

​

4. Modular Extension

• Optional modules (SM, ACLs, Geo, NLQ) load on demand
• Dynamic imports reduce initial bundle size
• Custom modules can extend functionality
• Clean API boundaries between layers

​

Performance Characteristics

​

Scalability

​

Data Scale

• Nodes: Tested with 100K+ nodes per database
• Graph depth: Efficient traversal up to 10+ hops with $edge
• Operations/sec: 50,000+ sustained writes without UI blocking

​

Network Scale

• Traditional Mesh: Recommended for < 100 peers
• Cellular Mesh: Scales to 10,000+ peers with O(N) connection complexity
• Cross-tab sync: Unlimited tabs via BroadcastChannel

​

Related Pages