SuperGraph — Federated Graph Intelligence

SuperGraph is a native P8G module that enables a single Purple8 Hyper Graph instance to coordinate queries across multiple P8G instances and foreign graph systems — transparently, securely, and with full audit trails.

The key insight

SuperGraph does not replace P8G — it extends it. Every peer connection is a Journey. Every approval is a graph event. Every partial result is honest about what it knows and what it couldn't reach.

"SuperGraph is P8G knowing about other P8Gs — and knowing how to talk to everything else."

Why SuperGraph Exists

Large enterprises do not run a single graph. They run many — across divisions, regions, regulatory boundaries, and technology stacks. Without federation:

Cross-domain queries require manual data extraction and reconciliation
Duplicate entities accumulate across systems with no canonical source
Graph size is bounded by a single instance's capacity
Foreign graph systems (Neo4j, Amazon Neptune, Microsoft Graph) are permanently siloed

SuperGraph solves all four — without modifying P8G core, and without forcing the enterprise to adopt a new data model.

Architecture

Only one P8G instance runs SuperGraph — the coordinator. All other instances are peers. Peers do not need SuperGraph installed. They only need to be reachable.

User Query
    ↓
P8G SuperGraph Instance  ← coordinator (only instance with SuperGraph active)
    ├── queries itself natively
    ├── queries P8G Peer A  (another P8G instance)
    ├── queries P8G Peer B  (another P8G instance)
    └── queries Foreign Graph  (Neo4j, Neptune, etc. via adapter)
         ↓
    Unified P8G hypergraph result

If the SuperGraph instance is offline, federation stops. Peers continue operating independently. This is intentional — there is no hidden coordination happening without the designated coordinator.

Discovery Tiers

SuperGraph supports four peer discovery modes. None activate without explicit administrator approval. Each tier is a superset of the previous — you must enable lower tiers before higher ones can be activated.

Tier	Mode	Default	Description
1	Static Registry	✅ Always available	Admin manually declares all peer URLs in config. No automation. Every connection is explicit and auditable.
2	Service Discovery	❌ Opt-in	Instances discovered via DNS/Consul/etcd. Discovery surfaces candidates — it does not connect automatically. Each discovered instance still requires manual approval.
3	Central Coordinator	❌ On-demand only	SuperGraph maintains the authoritative peer registry. Other instances check in to get the approved peer list. Not a persistent service — activates for a federated query, shuts down after. Requires Tier 1 + 2.
4	Gossip Protocol	❌ Explicit unlock required	Instances propagate peer knowledge to each other. Fully decentralised. Every gossip message is signed and logged. Not recommended for regulated industries. Requires Tier 1 + 2.

Regulated industries

Tiers 2, 3, and 4 are disabled by default. For industries subject to GDPR, HIPAA, FedRAMP, or equivalent frameworks, Tier 1 (Static Registry) is the recommended operating mode. Your CISO can confirm that no automatic peer discovery or gossip occurs without explicit configuration.

Peer Approval

Enabling a tier does not connect anything. Every peer relationship requires explicit approval before it is written to the registry.

P8G's role is to emit, wait, receive, and act — not to own the approval workflow. The approval process is yours.

How it works

SuperGraph Journey (closed loop)
    ├── 1. Peer connection requested
    │         ↓
    ├── 2. P8G emits approval event → your workflow system (webhook/callback)
    │         ↓
    ├── 3. Journey pauses — not blocking, other journeys continue
    │         ↓
    ├── 4. Your system handles approvals (however many approvers you need)
    │         ↓
    ├── 5. Decision received via callback
    │         ↓
    └── 6. Journey resumes (approved) or terminates (denied)
         Peer written to registry — or not.

P8G does not dictate how many approvers are required, who they are, or what tool manages the workflow. Wire it to ServiceNow, Jira, email, or a custom system — P8G only cares about the callback decision.

Approval micro-module

python

from purple8_graph.supergraph.approval import ApprovalConfig

supergraph = SuperGraph(
    approval=ApprovalConfig(
        webhook_url="https://your-workflow-system.example.com/p8g/peer-approval",
        timeout_hours=72,          # deny automatically if no decision after 72h
        callback_secret="...",     # HMAC-signed callbacks only
    )
)

The approval module is ~200 lines. It emits, waits, receives, and logs. Nothing more.

Partial Results & Disconnection Handling

If a peer becomes unreachable mid-traversal, SuperGraph does not fail the query. It returns everything it gathered, with a clear disclaimer.

python

result = await supergraph.traverse("""
    MATCH (doc:Document)-[:EXTRACTED_CONCEPT]->(concept:Concept)
          -[:USED_IN]->(design:DesignElement)
    RETURN doc, concept, design
""", doc_id="...")

print(result.status)         # "partial"
print(result.data)           # everything retrieved before disconnection
print(result.unreachable)    # which instances were missing

Result envelope

json

{
  "status": "partial",
  "data": { "...full results from reachable instances..." },
  "disclaimer": "Results are incomplete — one or more peers were unreachable.",
  "unreachable": [
    {
      "instance_id": "p8g-legal-eu-west",
      "last_seen": "2026-04-11T09:23:11Z",
      "reason": "connection_timeout",
      "affected_domains": ["Legal", "Compliance"]
    }
  ]
}

The user always knows exactly what is missing and why. Silent gaps do not exist.

Foreign Graph Adapters

SuperGraph can query non-P8G graph systems via thin adapters that speak each system's native protocol and translate results into P8G hypergraph format.

System	Protocol	Status
Neo4j	Bolt / Cypher	Planned
Amazon Neptune	Gremlin / SPARQL	Planned
Microsoft Graph	REST / OData	Planned
TigerGraph	GSQL	Planned
Custom	P8G Adapter Protocol	Available

Foreign graph results are returned as P8G nodes and edges — the query author does not need to know which system the data came from.

Journey Integration

Every SuperGraph operation is a Journey. Peer connections, federated queries, partial results, and approval events are all first-class Journey events — stored as graph edges, fully queryable, fully auditable.

cypher

-- All federated queries in the last 30 days
MATCH (q:SuperGraphQuery)-[:EXECUTED_AGAINST]->(peer:Peer)
WHERE q.executed_at > datetime() - duration('P30D')
RETURN q.query_id, peer.instance_id, q.status, q.result_count
ORDER BY q.executed_at DESC

-- All peers currently in pending approval state
MATCH (p:Peer {approval_status: "pending"})
RETURN p.instance_id, p.requested_at, p.requested_by

-- Audit trail for a specific peer relationship
MATCH (p:Peer {instance_id: $id})-[e:APPROVAL_EVENT]->()
RETURN e.event_type, e.actor, e.timestamp, e.notes
ORDER BY e.timestamp

Licensing

SuperGraph is an Enterprise-tier feature of Purple8 Hyper Graph.

Feature	Beta	Pro	Enterprise
Tier 1 — Static Registry	❌	❌	✅
Tier 2 — Service Discovery	❌	❌	✅
Tier 3 — Central Coordinator	❌	❌	✅
Tier 4 — Gossip Protocol	❌	❌	✅ (explicit unlock)
Foreign graph adapters	❌	❌	✅
Partial result handling	❌	❌	✅
Approval micro-module	❌	❌	✅

Design Principles

P8G core is untouched. SuperGraph only uses P8G's public interfaces.
Nothing connects without approval. Discovery ≠ connection.
One coordinator. Only the SuperGraph instance can initiate federation.
Honest partial results. Missing data is always declared, never silently omitted.
Your approval workflow. P8G emits and waits — it does not own the process.
Every event is a Journey edge. Full audit, full queryability, zero black boxes.

SuperGraph — Federated Graph Intelligence ​

Why SuperGraph Exists ​

Architecture ​

Discovery Tiers ​

Peer Approval ​

How it works ​

Approval micro-module ​

Partial Results & Disconnection Handling ​

Result envelope ​

Foreign Graph Adapters ​

Journey Integration ​

Licensing ​

Design Principles ​

See Also ​