How Purple8 Scales

This page answers the central architectural question directly: can Purple8 Hyper Graph hold up at the scale of real-world healthcare networks, manufacturing plants, financial institutions, and government agencies?

Short answer: yes — it scales to large enterprise production workloads on a single machine and scales out horizontally with sharding and Raft HA. Below are the measured production benchmarks, how BrickCoreStorage (Purple8 Cortex) bounds memory regardless of corpus size, and where horizontal cluster boundaries sit.

---

What a single node handles today

Purple8 Hyper Graph runs on BrickCoreStorage (Purple8 Cortex) with BrickWAL and CortexAutoConfig:

Workload / Benchmark	Measured Result
Vector query P99 @ 100K nodes (in-process)	0.33 ms
Batch ingest throughput	40,551 docs/s (40K/s)
VectorDBBench 1M × 768d	916 QPS, 0.946 recall@10
HTTP P95 (1024d with auth, WAL, AES-256-GCM encryption, RBAC all on)	23 ms
16-vCPU / 32 GB RAM enterprise benchmark (FLY_PERF16X_BENCH_20261025)	41,284 nodes/s burst ingest; 1,096 QPS concurrent hybrid search (P99 = 30.85 ms at 32 workers); 100% accuracy across all graph algorithms, GraphRAG, Journey SLA/HITL, SOC detector, and Quantum QUBO solvers
Largest single-node corpus (MS MARCO)	8.84M docs on a 24 GB machine — ~9 GB peak RSS, -3,626 MB returned to OS after ingest, ~5.4 GB query steady state
30-minute sustained soak test	1.18M requests, 500 concurrent users, 0% error rate

For context: a mid-size hospital network generates roughly 5–10 million patient-journey events per year. A national insurer handles 2–4 million claims per year. A large manufacturer runs 500K–2M production orders per year. A single Purple8 node absorbs all of these with significant headroom.

---

Hardware-Bounded Memory: BrickCoreStorage & CortexAutoConfig

Unlike traditional embedded or in-memory engines whose resident memory (RSS) grows linearly with total corpus size $N$, BrickCoreStorage (Purple8 Cortex) enforces a hardware-bounded working set:

1. CortexAutoConfig (auto_config=True): At startup, Purple8 probes available system RAM and solves for (M, ef_construction, segment_size, batch_size) so peak process RSS stays within alpha × available_ram (default alpha=0.75).
2. Brick seal-and-evict cycle:
   • The lock-free Rust DashMap buffer accumulates one batch (batch_size nodes).
   • BrickWAL.append_batch() seals the batch with a single os.write() and fdatasync().
   • Completed buffer entries are evicted and pages are returned to the OS, dropping RSS back to baseline before the next batch begins.
3. Proven at 8.84M documents: Ingesting the full 8.84M MS MARCO corpus on a 24 GB machine peaked at ~9 GB RSS across all 90 seal cycles without touching swap, released 3,626 MB back to the OS upon completion, and served queries in a ~5.4 GB steady-state footprint.
4. Disk High-Watermark Protection: Write admission (P8G_WRITE_ADMISSION_DISK_MAX_PCT=95.0) guards storage volumes from disk exhaustion under heavy sustained ingestion.

---

Start on a single machine

The default GraphEngine runs in-process. No Docker required, no separate server to manage. Install, import, query.

from purple8_graph import GraphEngine

engine = GraphEngine("./data")

engine.add_node("Document", {
    "title": "Q4 Report",
    "body": "Revenue grew 34% year-on-year...",
})

results = engine.query("""
    CALL db.vector.search('Document', $vec, 5)
    YIELD node, score
    RETURN node.title, score
""", vec=my_embedding)

This is production-ready for most enterprise workloads. Many teams run Purple8 this way for months or years before they need to scale out. The embedded storage handles hundreds of millions of nodes and billions of edges on a single NVMe drive.

---

Scale to a multi-shard cluster

When your dataset grows beyond a single machine — or you need higher write throughput — promote to ShardedGraphEngine. The API is identical.

from purple8_graph.sharding import ShardedGraphEngine, HashPartitioner

engine = ShardedGraphEngine(
    shard_configs=[
        {"path": "./data/shard-0"},
        {"path": "./data/shard-1"},
        {"path": "./data/shard-2"},
    ],
    partitioner=HashPartitioner(),
)

# Same Cypher — the engine federates across shards automatically
results = engine.query("""
    MATCH (i:JourneyInstance {entity_id: $id})-[t:ADVANCED_TO]->()
    RETURN t.from_stage, t.to_stage, t.actor, t.timestamp
    ORDER BY t.timestamp
""", id="P-44821")

Queries are automatically federated: Purple8 issues them in parallel across all shards and merges the results. Write throughput scales linearly with shard count — a 3-shard cluster delivers roughly 3× the journey transition throughput of a single node (~36,000/sec). You don't rewrite a single line of application code.

---

Add fault tolerance with Raft

For production systems that cannot afford data loss or downtime, wrap shards in Raft consensus groups. Each shard gets 3 or 5 replicas. The cluster survives the loss of any minority of nodes. Leader election completes within 300 ms.

from purple8_graph.raft import RaftShardedEngine
from purple8_graph.sharding import HashPartitioner

engine = RaftShardedEngine(
    shard_groups=[
        {
            "replicas": [
                {"host": "node-0a.internal", "port": 9010, "path": "/data/s0"},
                {"host": "node-0b.internal", "port": 9010, "path": "/data/s0"},
                {"host": "node-0c.internal", "port": 9010, "path": "/data/s0"},
            ]
        },
        {
            "replicas": [
                {"host": "node-1a.internal", "port": 9010, "path": "/data/s1"},
                {"host": "node-1b.internal", "port": 9010, "path": "/data/s1"},
                {"host": "node-1c.internal", "port": 9010, "path": "/data/s1"},
            ]
        },
    ],
    partitioner=HashPartitioner(),
    election_timeout_ms=300,
)

Writes require a quorum commit (majority of replicas acknowledge before returning success). Reads from the leader are always consistent. Use read_consistency="eventual" for high-volume read paths that can tolerate replica lag.

---

Spread across data centres

Assign replicas to different availability zones or regions using the zone tag. The Raft leader-election algorithm is zone-aware — it avoids electing a leader in a zone that already holds a majority of replicas, so a full AZ outage doesn't take down your cluster.

engine = RaftShardedEngine(
    shard_groups=[
        {
            "replicas": [
                {"host": "us-east-1a.db.internal", "port": 9010, "path": "/data/s0", "zone": "us-east-1a"},
                {"host": "us-east-1b.db.internal", "port": 9010, "path": "/data/s0", "zone": "us-east-1b"},
                {"host": "eu-west-1a.db.internal", "port": 9010, "path": "/data/s0", "zone": "eu-west-1a"},
            ]
        },
    ],
    partitioner=HashPartitioner(),
    election_timeout_ms=500,   # slightly higher for cross-region latency
)

---

Scaling path at a glance

Stage	Licensing Tier	Configuration	Nodes	Ingest / Search Throughput	Fault tolerant?
Development & Prototyping	Developer (Self-Hosted Free) (up to 50K nodes, 1 MCP agent)	GraphEngine (BrickCoreStorage)	1	40,551 docs/s batch · 0.33 ms P99 query	BrickWAL durability
Single-node Enterprise	Enterprise / Custom (Self-Hosted) (unlimited nodes & MCP agents)	GraphEngine + CortexAutoConfig	1	41,284 nodes/s burst · 1,096 QPS hybrid search	BrickWAL durability
Read scale & HA failover	Enterprise / Custom (Self-Hosted)	Primary + WAL-streaming Replicas	2+	Linear read scaling across replicas	Yes — automated failover
Horizontal scale-out	Enterprise / Custom (Self-Hosted)	ShardedGraphEngine (3+ shards)	3+	Multi-shard parallel write & scatter-gather	Per-shard BrickWAL
Multi-region / Raft HA	Enterprise / Custom (Self-Hosted)	RaftShardedEngine (3×3 + zones)	9+	Quorum-replicated multi-shard throughput	Yes — AZ & minority failure tolerance

---

What stays identical at every stage

This is the point that matters most for long-lived production systems:

• Cypher queries — not a single line changes between laptop and 9-node cluster
• Python SDK — engine.query(...), engine.add_node(...), journey_engine.advance(...)
• REST and GraphQL endpoints — same paths, same auth, same payloads
• KMS encryption — config carries through to every shard and replica
• Journey Engine — SLA monitoring, HITL queues, CDC events, AI advisor — all continue firing across the cluster unchanged
• MCP server — Claude and Cursor query the cluster the same way they query a single node

No migration scripts. No re-indexing. No schema changes. Add nodes to your cluster config and you're done.

---

Where the real limits are — honestly

Purple8 is production-grade for large enterprise workloads. It is not (yet) a hyperscaler. Here is where the real boundaries sit:

Cross-shard graph traversal

When a multi-hop query crosses shard boundaries — node A is on shard 0, its neighbour is on shard 1 — the FederatedQueryEngine resolves this with a second scatter-gather pass. The latency cost is real: a 3-hop query that crosses shards twice may take 15–25 ms instead of 2–5 ms.

Mitigation: Use LabelPartitioner to co-locate related node types on the same shard. For healthcare, Patient, JourneyInstance, and all their journey edges live on the same shard — cross-shard hops are rare in practice.

partitioner=LabelPartitioner({
    "Patient":         0,
    "JourneyInstance": 0,
    "ClinicalEvent":   0,
    "Document":        1,
    "Staff":           1,
    "Organisation":    2,
})

Deep traversals on very large graphs & Built-in DoS Protection

Unbounded multi-hop queries (-[*]-> with no depth limit) on graphs with hundreds of millions of nodes and high average degrees can easily behave like a Denial of Service (DoS) attack, causing explosive memory usage and CPU saturation as the query fan-out explodes.

Mitigation & Hard Limits: Purple8 now natively protects clusters against graph-expansion DoS attacks. By default, MAX_TRAVERSE_DEPTH = 10 acts as a hard ceiling on all queries and internal operations. Any query attempting a BFS traversal past 10 hops returns the truncated valid 10-hop graph bounds instead of freezing the cluster.

If you specifically require deeper analytics, always bound traversals cautiously with LIMIT. You can also adjust P8G_MAX_TRAVERSE_DEPTH cautiously via environment configurations, but the 10-hop cap natively isolates tenant queries and guarantees system resilience.

Global aggregations at massive scale

COUNT(*) or SUM() across a billion edges is a full-table scan. On a multi-shard cluster this is parallelised, but it still takes seconds, not milliseconds, at extreme scale.

Mitigation: Materialise frequently-needed aggregations as graph nodes using CDC. When an SLA_BREACHED edge is written, a background handler increments a counter node rather than re-scanning the full edge set at query time.

Single-cluster upper bound

The current architecture scales to roughly 50 shards before federation overhead outweighs parallelism gains. In practice, 50 shards with 5 Raft replicas each — 250 nodes — handles several billion nodes and trillions of edges. Very few organisations on earth have workloads that exceed this today.

---

Self-Hosted Licensing Tiers

Purple8 Hyper Graph ships with two self-hosted licensing tiers:

Tier	Capacity & Quotas	Capabilities
Developer (Self-Hosted Free)	Up to 50K nodes, 1 MCP agent	Full BrickCoreStorage (Cortex) engine, graph algorithms, HNSW vector search, Hybrid RAG, Journey Engine, and all 125 MCP tools across 16 namespaces
Enterprise / Custom (Self-Hosted)	Unlimited nodes, unlimited MCP agents	Full multi-tenancy, KMS envelope encryption (Vault/AWS/GCP/Azure), WAL-streaming HA & automated failover, ShardedGraphEngine / RaftShardedEngine, SuperGraph federation, SOC autonomous containment, and compliance controls

---

The architectural comparison

Most databases that claim to handle this class of workload require you to:

1. Run a separate vector database
2. Run a separate graph database
3. Build ETL pipelines between them
4. Run a separate workflow orchestration layer (Temporal, Airflow)
5. Build a separate audit log
6. Manage the operational complexity of 4+ distributed systems

The scaling challenge for those architectures is not just data volume — it is the compounding operational overhead of keeping multiple distributed systems in sync, monitored, and healthy. Purple8 replaces all of them with one system that you scale once, operate once, and monitor in one place.

---

Further reading

• Sharding & Clustering reference — partitioning strategies, Raft config, Docker Compose cluster setup, consistency model
• Benchmarks — measured numbers: QPS, P99 latency, memory footprint, ingestion throughput
• System Requirements — hardware sizing guidance per tier