Architecture

How Veculo works under the hood — from the Accumulo storage engine to per-tenant isolation and cloud-native infrastructure.

System overview

Veculo is a managed service built on top of Apache Accumulo, a distributed sorted key-value store originally developed at the NSA and donated to the Apache Software Foundation. Accumulo provides the storage engine, cell-level security, and tablet-based data distribution that underpin Veculo's graph and vector capabilities.

Each Veculo cluster is a dedicated deployment running on Google Cloud Platform (GCP). The architecture consists of several layers:

Apache Accumulo foundation

Accumulo is a BigTable-inspired sorted key-value store with several properties that make it uniquely suited for Veculo's requirements:

• Cell-level security — Every key-value pair carries a visibility expression, evaluated at scan time. This is the foundation of Veculo's ABAC system. See Security & ABAC.
• Tablet-based distribution — Data is split into tablets (contiguous key ranges) and distributed across tablet servers. Tablets split and merge automatically as data grows.
• LSM-tree storage — Writes go to an in-memory map (sorted buffer), then flush to immutable RFiles on disk. Background compactions merge and optimize these files.
• Server-side iterators — Custom logic can run inside the tablet server during scans, enabling graph traversal and vector similarity computation close to the data.
• Multi-level caching — Block cache and index cache minimize disk reads for hot data.

Data model mapping

Veculo maps graph concepts to Accumulo's key-value model. Each vertex and edge becomes a set of key-value pairs in Accumulo:

This encoding allows Accumulo's locality groups to separate properties, edges, and vectors — scans that only need properties skip vector data entirely.

GCS storage layer

Veculo uses Google Cloud Storage (GCS) as the persistent storage layer for all Accumulo data files (RFiles). This replaces the traditional HDFS layer that Accumulo deployments typically use.

Advantages of GCS over HDFS:

• Infinite scale — No need to manage DataNodes or worry about disk capacity. GCS scales transparently.
• Durability — GCS provides 99.999999999% (11 nines) annual durability. Data is automatically replicated across multiple availability zones.
• Cost efficiency — Pay only for storage used. No need to over-provision disk for growth.
• Separation of compute and storage — Tablet servers can be added or removed without moving data. Scaling compute is independent of storage capacity.

To minimize latency, Veculo tablet servers use a local block cache and read-ahead buffering. Hot data is served from memory; cold data is fetched from GCS on demand. Typical read latency for cached data is sub-millisecond; uncached reads add 5-15ms depending on object size.

ZooKeeper coordination

Each Veculo cluster runs a 3-node Apache ZooKeeper ensemble for:

• Tablet assignments — Tracking which tablet server hosts which tablets
• Manager election — Ensuring exactly one active manager coordinates the cluster
• Configuration — Storing table schemas, iterator configurations, and compaction policies
• Liveness detection — Detecting failed tablet servers and reassigning their tablets

ZooKeeper is fully managed — you never interact with it directly. Veculo monitors ensemble health and replaces failed nodes automatically.

Per-tenant isolation model

Every Veculo cluster is a fully isolated deployment. There is no shared infrastructure between tenants:

This isolation provides:

• Security boundary — A compromise of one tenant cannot affect another. There are no shared processes, memory spaces, or storage paths.
• Performance isolation — One tenant's heavy workload cannot impact another tenant's latency. There is no noisy-neighbor problem.
• Independent scaling — Each tenant scales independently based on their own workload.
• Independent upgrades — Tenants can be upgraded independently, enabling canary deployments and rollbacks.

Data durability and consistency

Veculo provides strong durability guarantees:

• Write-ahead log (WAL) — Every write is first appended to a write-ahead log stored in GCS before being acknowledged. If a tablet server crashes, the WAL is replayed to recover uncommitted data.
• Consistent reads — Accumulo provides read-your-writes consistency. After a write is acknowledged, all subsequent reads will see the new data.
• Atomic mutations — A single vertex or edge write is atomic. Either all key-value pairs for the mutation are written, or none are.
• No data loss on server failure — When a tablet server fails, its tablets are reassigned to surviving servers. The WAL ensures no acknowledged writes are lost.

Vector index architecture

Vector embeddings are stored in Accumulo alongside the graph data but indexed separately for approximate nearest-neighbor (ANN) search. The vector index runs as a sidecar process on each tablet server:

• When a vertex with an embedding is written, the embedding is indexed in the local vector index shard
• Vector search queries are broadcast to all shards, which each return their local top-k results
• Results are merged and re-ranked at the API layer to produce the global top-k
• The index is rebuilt from Accumulo data on server restart, ensuring consistency

This architecture ensures that vector search respects cell-level security — the index only returns vertex IDs, and the actual vertex data is read through Accumulo's standard scan path with visibility filtering.