<!-- CANARY: REQ=REQ-ENGINE-005; FEATURE="Engine"; ASPECT=CostBasedOptimizer; STATUS=TESTED; OWNER=engine; UPDATED=2026-01-15 -->
<h2 id="geode-architecture" class="position-relative d-flex align-items-center group">
<span>Geode Architecture</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="geode-architecture"
aria-haspopup="dialog"
aria-label="Share link: Geode Architecture">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h2><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden>
<div class="hsm-dialog" role="document">
<div class="hsm-header">
<h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2>
<button type="button" class="hsm-close" aria-label="Close">
<i class="fa-solid fa-xmark"></i>
</button>
</div>
<div class="hsm-body">
<label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label>
<div class="input-group mb-4 hsm-url-group">
<input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" />
<button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy">
<i class="fa-duotone fa-clipboard" aria-hidden="true"></i>
</button>
</div>
<div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div>
<div class="hsm-share-grid">
<a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-twitter me-2"></i>Twitter
</a>
<a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-linkedin me-2"></i>LinkedIn
</a>
<a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer">
<i class="fa-brands fa-facebook me-2"></i>Facebook
</a>
</div>
</div>
</div>
</div>
<style>
.heading-share-modal {
position: fixed;
inset: 0;
display: flex;
justify-content: center;
align-items: center;
background: rgba(0, 0, 0, 0.6);
z-index: 1050;
padding: 1rem;
backdrop-filter: blur(4px);
-webkit-backdrop-filter: blur(4px);
}
.heading-share-modal[hidden] { display: none !important; }
.hsm-dialog {
max-width: 420px;
width: 100%;
background: var(--bs-body-bg, #fff);
color: var(--bs-body-color, #212529);
border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
border-radius: 1rem;
box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
overflow: hidden;
animation: hsm-fade-in 0.2s ease-out;
}
@keyframes hsm-fade-in {
from { opacity: 0; transform: scale(0.95); }
to { opacity: 1; transform: scale(1); }
}
[data-bs-theme="dark"] .hsm-dialog {
background: #1e293b;
border-color: rgba(255,255,255,0.1);
color: #f8f9fa;
}
.hsm-header {
display: flex;
justify-content: space-between;
align-items: center;
padding: 1rem 1.5rem;
border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1));
background: rgba(0,0,0,0.02);
}
[data-bs-theme="dark"] .hsm-header {
background: rgba(255,255,255,0.02);
border-color: rgba(255,255,255,0.1);
}
.hsm-close {
background: transparent;
border: none;
color: inherit;
opacity: 0.5;
padding: 0.25rem 0.5rem;
border-radius: 0.25rem;
font-size: 1.2rem;
line-height: 1;
transition: opacity 0.2s;
}
.hsm-close:hover {
opacity: 1;
}
.hsm-body {
padding: 1.5rem;
}
.hsm-url-group {
display: flex !important;
align-items: stretch;
}
.hsm-url-group .form-control {
flex: 1;
min-width: 0;
margin: 0;
background: var(--bs-secondary-bg, #f8f9fa);
border-color: var(--bs-border-color, #dee2e6);
border-top-right-radius: 0;
border-bottom-right-radius: 0;
height: 42px;
}
.hsm-url-group .btn {
flex: 0 0 auto;
margin: 0;
margin-left: -1px;
border-top-left-radius: 0;
border-bottom-left-radius: 0;
height: 42px;
display: flex;
align-items: center;
justify-content: center;
padding: 0 1.25rem;
z-index: 2;
}
[data-bs-theme="dark"] .hsm-url-group .form-control {
background: #0f172a;
border-color: #334155;
color: #e2e8f0;
}
.hsm-share-grid {
display: flex;
flex-direction: column;
gap: 0.5rem;
}
.hsm-share-grid .btn {
display: flex;
align-items: center;
justify-content: center;
font-size: 0.9rem;
padding: 0.6rem;
border-color: var(--bs-border-color);
width: 100%;
}
[data-bs-theme="dark"] .hsm-share-grid .btn {
color: #e2e8f0;
border-color: #475569;
}
[data-bs-theme="dark"] .hsm-share-grid .btn:hover {
background: #334155;
border-color: #cbd5e1;
}
</style>
<script>
(function(){
const modal = document.getElementById('headingShareModal');
if(!modal) return;
const input = modal.querySelector('#headingShareInput');
const copyBtn = modal.querySelector('.hsm-copy');
const twitter = modal.querySelector('#share-twitter');
const linkedin = modal.querySelector('#share-linkedin');
const facebook = modal.querySelector('#share-facebook');
const closeBtn = modal.querySelector('.hsm-close');
let lastFocus=null;
let trapBound=false;
function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; }
function isOpen(){ return !modal.hasAttribute('hidden'); }
function hydrate(id){
const url=buildUrl(id);
input.value=url;
const enc=encodeURIComponent(url);
const text=encodeURIComponent(document.title);
if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`;
if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`;
if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`;
}
function openModal(id){
lastFocus=document.activeElement;
hydrate(id);
if(!isOpen()){
modal.removeAttribute('hidden');
}
requestAnimationFrame(()=>{ input.focus(); });
trapFocus();
}
function closeModal(){
if(!isOpen()) return;
modal.setAttribute('hidden','');
if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus();
}
function copyCurrent(){
try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); }
catch(e){ fallback(); }
}
function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} }
function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); }
function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); }
function bindShareButtons(){
document.querySelectorAll('.h-share').forEach(btn=>{
if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; }
});
}
bindShareButtons();
if(document.readyState==='loading'){
document.addEventListener('DOMContentLoaded', bindShareButtons);
} else {
requestAnimationFrame(bindShareButtons);
}
document.addEventListener('click', function(e){
const shareBtn=e.target.closest && e.target.closest('.h-share');
if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); }
}, true);
document.addEventListener('click', e=>{
if(e.target===modal) closeModal();
if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); }
if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); }
});
document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); });
function trapFocus(){
if(trapBound) return;
trapBound=true;
modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } });
}
if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); });
})();
</script><p>Geode is an enterprise-ready graph database built with a modular, high-performance architecture designed for scalability, reliability, and compliance.</p>
<h3 id="system-overview" class="position-relative d-flex align-items-center group">
<span>System Overview</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="system-overview"
aria-haspopup="dialog"
aria-label="Share link: System Overview">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"><span class="line"><span class="cl">┌─────────────────────────────────────────────────────────────┐
</span></span><span class="line"><span class="cl">│ Entry Points │
</span></span><span class="line"><span class="cl">│ ┌────────────┐ ┌─────────────┐ │
</span></span><span class="line"><span class="cl">│ │ Server │ │ CLI │ │
</span></span><span class="line"><span class="cl">│ │ (QUIC+TLS) │ │ (Shell) │ │
</span></span><span class="line"><span class="cl">│ └─────┬──────┘ └──────┬──────┘ │
</span></span><span class="line"><span class="cl">│ │ │ │
</span></span><span class="line"><span class="cl">│ └─────────────┬──────────────────────┘ │
</span></span><span class="line"><span class="cl">│ │ │
</span></span><span class="line"><span class="cl">└──────────────────────┼──────────────────────────────────────┘
</span></span><span class="line"><span class="cl"> │
</span></span><span class="line"><span class="cl"> ┌──────────────┼──────────────┐
</span></span><span class="line"><span class="cl"> │ │ │
</span></span><span class="line"><span class="cl"> ▼ ▼ ▼
</span></span><span class="line"><span class="cl"> ┌─────────┐ ┌──────────┐ ┌─────────┐
</span></span><span class="line"><span class="cl"> │ GQL │ │Execution │ │ Eval │
</span></span><span class="line"><span class="cl"> │ Parser │ │ Engine │◄──┤ Engine │
</span></span><span class="line"><span class="cl"> └────┬────┘ └─────┬────┘ └─────────┘
</span></span><span class="line"><span class="cl"> │ │
</span></span><span class="line"><span class="cl"> └──────────────┴──────────────┘
</span></span><span class="line"><span class="cl"> │
</span></span><span class="line"><span class="cl"> ┌──────────────┼──────────────┐
</span></span><span class="line"><span class="cl"> │ │ │
</span></span><span class="line"><span class="cl"> ▼ ▼ ▼
</span></span><span class="line"><span class="cl"> ┌─────────┐ ┌──────────┐ ┌─────────┐
</span></span><span class="line"><span class="cl"> │ Planner │ │ Storage │ │Security │
</span></span><span class="line"><span class="cl"> │ CBO │ │ Engine │ │(Audit, │
</span></span><span class="line"><span class="cl"> └─────────┘ └─────┬────┘ │ TDE,RLS)│
</span></span><span class="line"><span class="cl"> │ └─────────┘
</span></span><span class="line"><span class="cl"> ▼
</span></span><span class="line"><span class="cl"> ┌──────────┐
</span></span><span class="line"><span class="cl"> │ WAL │
</span></span><span class="line"><span class="cl"> │ Index │
</span></span><span class="line"><span class="cl"> │ Txn │
</span></span><span class="line"><span class="cl"> └──────────┘
</span></span></code></pre></div>
<h3 id="core-components" class="position-relative d-flex align-items-center group">
<span>Core Components</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="core-components"
aria-haspopup="dialog"
aria-label="Share link: Core Components">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="query-processing-pipeline" class="position-relative d-flex align-items-center group">
<span>Query Processing Pipeline</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="query-processing-pipeline"
aria-haspopup="dialog"
aria-label="Share link: Query Processing Pipeline">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>1. GQL Parser</strong> (<code>src/gql/</code>)</p>
<ul>
<li><strong>ISO/IEC 39075:2024 Compliance</strong>: see conformance profile</li>
<li>Lexer with complete token support</li>
<li>Recursive descent parser</li>
<li>AST generation</li>
<li><strong>Performance</strong>: Optimized parsing pipeline</li>
</ul>
<p><strong>2. Query Planner</strong> (<code>src/planner/</code>)</p>
<ul>
<li>Cost-based optimization (CBO)</li>
<li>Statistics-driven index selection</li>
<li>Join order optimization</li>
<li>Adaptive query planning</li>
<li><strong>IndexOptimizer</strong>: Automatic index selection with logarithmic cost scaling</li>
</ul>
<p><strong>3. Execution Engine</strong> (<code>src/execution/</code>)</p>
<ul>
<li>Pattern matching with backtracking</li>
<li>Path evaluation (variable-length paths)</li>
<li>Aggregation and grouping</li>
<li>Set operations (UNION, INTERSECT, EXCEPT)</li>
<li><strong>Performance</strong>: Optimized for graph traversal patterns</li>
</ul>
<p><strong>4. Expression Evaluator</strong> (<code>src/eval.zig</code>)</p>
<ul>
<li>Type promotion and coercion</li>
<li>Built-in function dispatch</li>
<li>NULL propagation semantics</li>
<li><strong>SIMD Optimization</strong>: Vectorized operations for supported workloads</li>
</ul>
<h4 id="storage-engine" class="position-relative d-flex align-items-center group">
<span>Storage Engine</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="storage-engine"
aria-haspopup="dialog"
aria-label="Share link: Storage Engine">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Page Manager</strong> (<code>src/storage/</code>)</p>
<ul>
<li>Memory-mapped I/O with page-level caching</li>
<li>8KB page size (configurable)</li>
<li>LRU cache with eviction</li>
<li>Lock-free read paths where possible</li>
</ul>
<p><strong>Write-Ahead Log (WAL)</strong> (<code>src/wal/</code>)</p>
<ul>
<li>Durability guarantees</li>
<li>Point-in-time recovery</li>
<li>Segment-based storage</li>
<li>Automatic checkpoint management</li>
</ul>
<p><strong>Transaction Management</strong> (<code>src/txn/</code>)</p>
<ul>
<li>MVCC (Multi-Version Concurrency Control)</li>
<li>Serializable Snapshot Isolation (SSI)</li>
<li>Phantom read prevention</li>
<li>6 isolation levels: Read Uncommitted, Read Committed, Repeatable Read, Snapshot, Serializable, Linearizable</li>
</ul>
<h4 id="index-system" class="position-relative d-flex align-items-center group">
<span>Index System</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="index-system"
aria-haspopup="dialog"
aria-label="Share link: Index System">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Six Index Types</strong> (<code>src/index/</code>):</p>
<ol>
<li>
<p><strong>B-tree</strong> - Range queries, sorting</p>
<ul>
<li>O(log N) operations</li>
<li>Bulk loading optimization</li>
</ul>
</li>
<li>
<p><strong>Hash</strong> - Exact match lookups</p>
<ul>
<li>O(1) average case</li>
<li>Collision handling via chaining</li>
</ul>
</li>
<li>
<p><strong>HNSW</strong> (Vector index)</p>
<ul>
<li>Approximate K-NN search</li>
<li>O(log N) search complexity</li>
<li>6 distance metrics: L2, cosine, dot product, Manhattan, Hamming, Jaccard</li>
</ul>
</li>
<li>
<p><strong>R-tree</strong> (Spatial index)</p>
<ul>
<li>Geographic queries</li>
<li>Bounding box search</li>
<li>Radius search with Haversine distance</li>
</ul>
</li>
<li>
<p><strong>Full-text</strong> (BM25)</p>
<ul>
<li>Tokenization and ranking</li>
<li>Stop word removal</li>
<li>Stemming support</li>
</ul>
</li>
<li>
<p><strong>Patricia Trie</strong> (CIDR index)</p>
<ul>
<li>IP prefix matching</li>
<li>Longest Prefix Match (LPM)</li>
<li>O(prefix_bits) lookup</li>
</ul>
</li>
</ol>
<h4 id="security-layer" class="position-relative d-flex align-items-center group">
<span>Security Layer</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="security-layer"
aria-haspopup="dialog"
aria-label="Share link: Security Layer">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Authentication & Authorization</strong> (<code>src/security/</code>)</p>
<ul>
<li>RBAC (Role-Based Access Control)</li>
<li>ABAC (Attribute-Based Access Control)</li>
<li>Enhanced RLS (Row-Level Security) with policy evaluation</li>
<li>MFA support</li>
<li>Session management</li>
</ul>
<p><strong>Data Protection</strong>:</p>
<ul>
<li>TDE (Transparent Data Encryption): AES-256-GCM encryption</li>
<li>Field-Level Encryption (FLE) with searchable encryption</li>
<li>KMS integration (HashiCorp Vault)</li>
<li>Audit logging with compliance tracking</li>
</ul>
<p><strong>Constraints</strong> (<code>src/schema/catalog.zig</code>):</p>
<ul>
<li>UNIQUE constraints</li>
<li>NOT NULL constraints</li>
<li>NODE KEY constraints (combined uniqueness + existence)</li>
<li>Catalog persistence across restarts</li>
</ul>
<h4 id="distributed-architecture" class="position-relative d-flex align-items-center group">
<span>Distributed Architecture</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-architecture"
aria-haspopup="dialog"
aria-label="Share link: Distributed Architecture">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>Federation</strong> (<code>src/distributed/</code>)</p>
<ul>
<li>Multi-shard support (up to 32 shards)</li>
<li>Cross-shard query coordination</li>
<li>Load balancing with health checks</li>
<li>Fault tolerance with automatic failover</li>
</ul>
<p><strong>Raft Consensus</strong> (<code>src/distributed/raft_consensus.zig</code>)</p>
<ul>
<li>Leader election</li>
<li>Log replication</li>
<li>Membership changes</li>
<li>Snapshot management</li>
</ul>
<h4 id="network-layer" class="position-relative d-flex align-items-center group">
<span>Network Layer</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="network-layer"
aria-haspopup="dialog"
aria-label="Share link: Network Layer">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>QUIC Transport</strong> (<code>src/transport/</code>)</p>
<ul>
<li>Modern protocol with multiplexing</li>
<li>TLS 1.3 mandatory</li>
<li>Connection migration support</li>
<li>Low latency transport</li>
</ul>
<p><strong>Protocol</strong> (<code>src/protocol.zig</code>)</p>
<ul>
<li>Protobuf wire protocol</li>
<li>Message types: <code>HelloRequest</code>, <code>ExecuteRequest</code>, <code>PullRequest</code>, <code>BeginRequest</code>, <code>CommitRequest</code>, <code>RollbackRequest</code>, <code>PingRequest</code></li>
<li>Response type: <code>ExecutionResponse</code> (payloads: <code>SchemaDefinition</code>, <code>DataPage</code>, <code>Error</code>, <code>ExplainPayload</code>, <code>ProfilePayload</code>)</li>
<li>Multi-tenancy support with tenant_id in HELLO message</li>
</ul>
<h4 id="advanced-features" class="position-relative d-flex align-items-center group">
<span>Advanced Features</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="advanced-features"
aria-haspopup="dialog"
aria-label="Share link: Advanced Features">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><p><strong>ML Graph Embeddings</strong> (<code>src/ml/</code>)</p>
<ul>
<li>Node2Vec algorithm</li>
<li>GraphSAGE implementation</li>
<li>DeepWalk support</li>
<li>Integration with HNSW indexes</li>
</ul>
<p><strong>Real-time Analytics</strong> (<code>src/analytics/</code>)</p>
<ul>
<li>Streaming pattern detection</li>
<li>Anomaly detection with ML</li>
<li>CDC (Change Data Capture) integration</li>
<li>Backpressure handling</li>
</ul>
<p><strong>Materialized Views</strong> (<code>src/query/</code>)</p>
<ul>
<li>Three refresh strategies: immediate, deferred, on-demand</li>
<li>Query rewriting for automatic use</li>
<li>Dependency tracking</li>
<li>Incremental refresh support</li>
</ul>
<h3 id="file-organization" class="position-relative d-flex align-items-center group">
<span>File Organization</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="file-organization"
aria-haspopup="dialog"
aria-label="Share link: File Organization">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="codebase-statistics" class="position-relative d-flex align-items-center group">
<span>Codebase Statistics</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="codebase-statistics"
aria-haspopup="dialog"
aria-label="Share link: Codebase Statistics">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>Total LOC</strong>: 173,048 lines of Zig code</li>
<li><strong>Source Files</strong>: 436 files</li>
<li><strong>Test Files</strong>: 843 test files</li>
<li><strong>Test/Source Ratio</strong>: 1.9:1</li>
<li><strong>Modules</strong>: 50 top-level directories</li>
</ul>
<h4 id="module-structure" class="position-relative d-flex align-items-center group">
<span>Module Structure</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="module-structure"
aria-haspopup="dialog"
aria-label="Share link: Module Structure">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"><span class="line"><span class="cl">src/
</span></span><span class="line"><span class="cl">├── server/ # Server implementation
</span></span><span class="line"><span class="cl">├── cli/ # CLI implementation
</span></span><span class="line"><span class="cl">├── gql/ # GQL parser
</span></span><span class="line"><span class="cl">├── execution/ # Query execution
</span></span><span class="line"><span class="cl">├── eval.zig # Expression evaluation
</span></span><span class="line"><span class="cl">├── planner/ # Query planning
</span></span><span class="line"><span class="cl">├── storage/ # Storage engine
</span></span><span class="line"><span class="cl">├── security/ # Security features
</span></span><span class="line"><span class="cl">├── distributed/ # Federation & Raft
</span></span><span class="line"><span class="cl">├── index/ # Index implementations
</span></span><span class="line"><span class="cl">├── ml/ # Machine learning
</span></span><span class="line"><span class="cl">├── analytics/ # Real-time analytics
</span></span><span class="line"><span class="cl">├── types/ # Advanced data types
</span></span><span class="line"><span class="cl">└── ... # 40+ more modules
</span></span></code></pre></div>
<h3 id="architecture-characteristics" class="position-relative d-flex align-items-center group">
<span>Architecture Characteristics</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="architecture-characteristics"
aria-haspopup="dialog"
aria-label="Share link: Architecture Characteristics">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="query-processing" class="position-relative d-flex align-items-center group">
<span>Query Processing</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="query-processing"
aria-haspopup="dialog"
aria-label="Share link: Query Processing">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>Point lookups</strong>: Optimized via hash indexes</li>
<li><strong>Path traversal</strong>: Efficient multi-hop pattern matching</li>
<li><strong>Vector search</strong>: SIMD-accelerated distance calculations</li>
<li><strong>Indexed lookups</strong>: Optimized via B-tree and hash indexes</li>
</ul>
<h4 id="scalability" class="position-relative d-flex align-items-center group">
<span>Scalability</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="scalability"
aria-haspopup="dialog"
aria-label="Share link: Scalability">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>Concurrent connections</strong>: Connection pooling supported</li>
<li><strong>Shards</strong>: Up to 32 shards with distributed coordination</li>
</ul>
<h3 id="quality-metrics" class="position-relative d-flex align-items-center group">
<span>Quality Metrics</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="quality-metrics"
aria-haspopup="dialog"
aria-label="Share link: Quality Metrics">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="test-coverage" class="position-relative d-flex align-items-center group">
<span>Test Coverage</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="test-coverage"
aria-haspopup="dialog"
aria-label="Share link: Test Coverage">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>Integration tests</strong>: 97.4% pass rate (1,644/1,688 tests)</li>
<li><strong>Unit tests</strong>: 100% pass rate (393/393 tests)</li>
<li><strong>GQL conformance profile</strong>: see conformance profile</li>
<li><strong>CANARY markers</strong>: 1,735 markers tracking 2,190+ requirements</li>
</ul>
<h4 id="status-breakdown" class="position-relative d-flex align-items-center group">
<span>Status Breakdown</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="status-breakdown"
aria-haspopup="dialog"
aria-label="Share link: Status Breakdown">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li><strong>TESTED</strong>: 81.4% - Full test coverage</li>
<li><strong>BENCHED</strong>: 6.0% - Performance benchmarks</li>
<li><strong>EXEMPT</strong>: 7.7% - Documentation/metadata</li>
<li><strong>IMPL</strong>: 5.7% - Implementation without tests</li>
</ul>
<h3 id="design-principles" class="position-relative d-flex align-items-center group">
<span>Design Principles</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="design-principles"
aria-haspopup="dialog"
aria-label="Share link: Design Principles">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="modularity" class="position-relative d-flex align-items-center group">
<span>Modularity</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="modularity"
aria-haspopup="dialog"
aria-label="Share link: Modularity">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li>Clear module boundaries</li>
<li>Dependency injection for testability</li>
<li>Interface-based design</li>
<li>Zero circular dependencies (resolved)</li>
</ul>
<h4 id="performance" class="position-relative d-flex align-items-center group">
<span>Performance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="performance"
aria-haspopup="dialog"
aria-label="Share link: Performance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li>SIMD vectorization where applicable</li>
<li>Memory-mapped I/O for storage</li>
<li>Lock-free algorithms for hot paths</li>
<li>Adaptive query optimization</li>
</ul>
<h4 id="reliability" class="position-relative d-flex align-items-center group">
<span>Reliability</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="reliability"
aria-haspopup="dialog"
aria-label="Share link: Reliability">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li>ACID transaction guarantees</li>
<li>WAL for durability</li>
<li>Crash recovery</li>
<li>Comprehensive error handling</li>
</ul>
<h4 id="security" class="position-relative d-flex align-items-center group">
<span>Security</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="security"
aria-haspopup="dialog"
aria-label="Share link: Security">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li>Security-first design</li>
<li>Encryption at rest and in transit</li>
<li>Fine-grained access control</li>
<li>Comprehensive audit logging</li>
</ul>
<h4 id="compliance" class="position-relative d-flex align-items-center group">
<span>Compliance</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="compliance"
aria-haspopup="dialog"
aria-label="Share link: Compliance">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><ul>
<li>ISO/IEC 39075:2024 (GQL standard)</li>
<li>GDPR compliance features</li>
<li>SOX/HIPAA/PCI-DSS support</li>
<li>Evidence-based development with CANARY markers</li>
</ul>
<h3 id="deployment-architecture" class="position-relative d-flex align-items-center group">
<span>Deployment Architecture</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="deployment-architecture"
aria-haspopup="dialog"
aria-label="Share link: Deployment Architecture">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3>
<h4 id="standalone-mode" class="position-relative d-flex align-items-center group">
<span>Standalone Mode</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="standalone-mode"
aria-haspopup="dialog"
aria-label="Share link: Standalone Mode">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"><span class="line"><span class="cl">┌─────────────────┐
</span></span><span class="line"><span class="cl">│ Geode Server │
</span></span><span class="line"><span class="cl">│ (QUIC:3141) │
</span></span><span class="line"><span class="cl">│ │
</span></span><span class="line"><span class="cl">│ ┌───────────┐ │
</span></span><span class="line"><span class="cl">│ │ Storage │ │
</span></span><span class="line"><span class="cl">│ │ WAL │ │
</span></span><span class="line"><span class="cl">│ │ Indexes │ │
</span></span><span class="line"><span class="cl">│ └───────────┘ │
</span></span><span class="line"><span class="cl">└─────────────────┘
</span></span></code></pre></div>
<h4 id="distributed-mode" class="position-relative d-flex align-items-center group">
<span>Distributed Mode</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="distributed-mode"
aria-haspopup="dialog"
aria-label="Share link: Distributed Mode">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"><span class="line"><span class="cl">┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
</span></span><span class="line"><span class="cl">│ Geode Shard 1 │ │ Geode Shard 2 │ │ Geode Shard 3 │
</span></span><span class="line"><span class="cl">│ (QUIC:3141) │ │ (QUIC:3142) │ │ (QUIC:3143) │
</span></span><span class="line"><span class="cl">│ │ │ │ │ │
</span></span><span class="line"><span class="cl">│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
</span></span><span class="line"><span class="cl">│ │ Storage │ │ │ │ Storage │ │ │ │ Storage │ │
</span></span><span class="line"><span class="cl">│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
</span></span><span class="line"><span class="cl">└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
</span></span><span class="line"><span class="cl"> │ │ │
</span></span><span class="line"><span class="cl"> └────────────────────┼─────────────────────┘
</span></span><span class="line"><span class="cl"> │
</span></span><span class="line"><span class="cl"> ┌────────▼────────┐
</span></span><span class="line"><span class="cl"> │ Coordinator │
</span></span><span class="line"><span class="cl"> │ (Federation) │
</span></span><span class="line"><span class="cl"> └─────────────────┘
</span></span></code></pre></div>
<h3 id="next-steps" class="position-relative d-flex align-items-center group">
<span>Next Steps</span>
<button type="button"
class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1"
data-share-target="next-steps"
aria-haspopup="dialog"
aria-label="Share link: Next Steps">
<i class="fa-sharp-duotone fa-solid fa-share-nodes" aria-hidden="true" style="font-size: 0.8em;"></i>
<span class="visually-hidden">Share link</span>
</button>
</h3><ul>
<li><a
href="/docs/architecture/storage-engine/"
>Storage Engine Details</a>
- Deep dive into storage</li>
<li><a
href="/docs/architecture/query-optimization/"
>Query Optimization</a>
- CBO and index selection</li>
<li><a
href="/docs/architecture/distributed-systems/"
>Distributed Systems</a>
- Federation and Raft</li>
<li><a
href="/docs/architecture/security-architecture/"
>Security Architecture</a>
- Security features</li>
</ul>
Architecture
Geode system architecture, storage engine design, and distributed systems overview
9 pages
Pages
Distributed Architecture Deep Dive
Comprehensive guide to Geode's distributed query coordination, federation, sharding, load balancing, and fault tolerance for enterprise-scale graph databases.
13 min read
Performance and Scalability
Understand Geode's performance architecture (storage, planner, indexes) and how distributed query coordination scales across shards over QUIC+TLS
5 min read
Storage Engine Architecture
Deep dive into Geode's storage engine including memory-mapped I/O, page management, MVCC transactions, and data persistence
5 min read
Query Optimization
Geode's cost-based query optimizer including index selection, join ordering, predicate pushdown, and adaptive query execution
5 min read
Distributed Systems Architecture
Geode's distributed systems including Raft consensus, federation, sharding strategies, and fault tolerance mechanisms
5 min read
Query Execution Architecture
Deep dive into Geode's query execution pipeline including parser, planner, optimizer, and executor with distributed query coordination
14 min read
Security Architecture
Geode's security architecture including authentication, authorization, encryption, audit logging, and compliance features
5 min read
CLI Architecture and Unified Binary Design
Learn about Geode's unified binary architecture that eliminates subprocess spawning for improved performance, simplified deployment, and streamlined CLI operations.
11 min read
Wire Protocol Specification
Complete Geode wire protocol specification with QUIC/gRPC transport, Protobuf messages, streaming, federation, and client-server communication details.
2 min read