Grand Diomande Research · Full HTML Reader
Graph Kernel Architecture Diagram
```mermaid flowchart TB subgraph External [External Services] RAG["RAG++ Service<br/>Context Retrieval"] Orbit["Orbit Server<br/>Session Management"] MCP["MCP Server<br/>AI Tools"] end
Full Public Reader
Graph Kernel Architecture Diagram
Version: 1.0.0
Last Updated: 2026-01-02
---
System Overview
mermaid
flowchart TB
subgraph External [External Services]
RAG["RAG++ Service<br/>Context Retrieval"]
Orbit["Orbit Server<br/>Session Management"]
MCP["MCP Server<br/>AI Tools"]
end
subgraph GraphKernel [Graph Kernel Service]
direction TB
subgraph API [API Layer - Axum]
SliceEP["POST /api/slice<br/>Generate Slice"]
BatchEP["POST /api/slice/batch<br/>Batch Slices"]
VerifyEP["POST /api/verify_token<br/>Verify Admissibility"]
PolicyEP["GET /api/policies<br/>List Policies"]
HealthEP["GET /health/*<br/>Health Probes"]
end
subgraph Core [Core Engine]
Slicer["ContextSlicer<br/>Priority Queue Expansion"]
Policy["PolicyRegistry<br/>Immutable Policy Store"]
Token["AdmissibilityToken<br/>HMAC-SHA256 Authority"]
Snapshot["GraphSnapshotHash<br/>Content Immutability"]
end
subgraph Store [Storage Layer]
PGStore["PostgresGraphStore<br/>Connection Pool"]
InMem["InMemoryGraphStore<br/>Testing Only"]
end
subgraph Observability [Observability]
Metrics["Prometheus Metrics<br/>:9000/metrics"]
Logs["Structured JSON Logs<br/>Cloud Logging"]
Health["Health Probes<br/>/live /ready /startup"]
end
end
subgraph Database [PostgreSQL / Supabase]
MT[(memory_turns<br/>Conversation DAG)]
CV[(conversations)]
Edges[(edges)]
end
subgraph Secrets [Google Secret Manager]
HMAC[["KERNEL_HMAC_SECRET<br/>Token Signing Key"]]
DBURL[["DATABASE_URL<br/>Connection String"]]
end
%% External connections
RAG -->|"POST /api/slice"| SliceEP
Orbit -->|"POST /api/verify_token"| VerifyEP
MCP -->|"GET /api/policies"| PolicyEP
%% Internal flow
SliceEP --> Slicer
BatchEP --> Slicer
VerifyEP --> Token
PolicyEP --> Policy
Slicer --> Policy
Slicer --> PGStore
Slicer --> Token
Slicer --> Snapshot
Token --> HMAC
PGStore --> DBURL
PGStore --> MT
PGStore --> CV
PGStore --> Edges
%% Observability
API --> Metrics
API --> Logs
HealthEP --> Health
Health --> PGStore---
Slice Generation Flow
mermaid
sequenceDiagram
participant Client as RAG++ / Orbit
participant API as Axum API
participant Slicer as ContextSlicer
participant Policy as PolicyRegistry
participant Store as PostgresGraphStore
participant Token as TokenAuthority
participant DB as PostgreSQL
Client->>+API: POST /api/slice {anchor_turn_id}
API->>+Policy: resolve(policy_ref)
Policy-->>-API: SlicePolicyV1
API->>+Slicer: slice(anchor_id, policy)
Slicer->>+Store: get_turn(anchor_id)
Store->>+DB: SELECT * FROM memory_turns WHERE id = ?
DB-->>-Store: TurnSnapshot
Store-->>-Slicer: anchor_turn
loop Priority Queue Expansion
Slicer->>+Store: get_parents(turn_id)
Store->>DB: SELECT parent_turn_id FROM memory_turns
Store-->>-Slicer: parent_ids
Slicer->>+Store: get_children(turn_id)
Store->>DB: SELECT id FROM memory_turns WHERE parent_turn_id = ?
Store-->>-Slicer: child_ids
Slicer->>+Store: get_siblings(turn_id, limit)
Store->>DB: SELECT id FROM memory_turns WHERE parent_turn_id = parent
Store-->>-Slicer: sibling_ids
end
Slicer->>+Store: get_edges(selected_turn_ids)
Store->>DB: SELECT * FROM edges WHERE parent IN (?) OR child IN (?)
Store-->>-Slicer: edges
Slicer->>Slicer: compute_graph_snapshot_hash()
Slicer->>Slicer: compute_slice_fingerprint()
Slicer->>+[sensitive field redacted], slice_data)
Token-->>-Slicer: AdmissibilityToken
Slicer-->>-API: SliceExport
API-->>-Client: {slice, policy_ref}---
Token Verification Flow
mermaid
sequenceDiagram
participant Client as Downstream Service
participant API as Graph Kernel API
participant Token as TokenAuthority
participant Secret as KERNEL_HMAC_SECRET
Client->>+API: POST /api/verify_token
Note over Client,API: {token, slice_id, anchor_id, policy_id, ...}
API->>+[sensitive field redacted], claimed_token, params)
Token->>[sensitive field redacted], canonical_string)
Token->>[sensitive field redacted], expected)
Token-->>-API: valid: bool
alt Token Valid
API-->>Client: {"valid": true}
else Token Invalid
API-->>Client: {"valid": false, "reason": "TOKEN_MISMATCH"}
end
deactivate API---
Data Model
mermaid
erDiagram
memory_turns {
uuid id PK
uuid conversation_id FK
uuid parent_turn_id FK
text session_id
text role
text phase
text content_text
text content_hash
float salience
integer depth
timestamptz created_at
jsonb trajectory_coord
}
conversations {
uuid id PK
uuid project_id FK
text title
timestamptz created_at
}
edges {
uuid id PK
uuid parent_turn_id FK
uuid child_turn_id FK
text edge_type
}
memory_turns ||--o{ memory_turns : "parent_turn_id"
memory_turns }o--|| conversations : "conversation_id"
memory_turns ||--o{ edges : "parent_turn_id"
memory_turns ||--o{ edges : "child_turn_id"---
Priority Queue Expansion
Anchor Turn (distance=0)
│
┌───────────────┼───────────────┐
▼ ▼ ▼
Parent 1 Sibling 1 Child 1
(d=1) (d=0) (d=1)
│ │
┌──────┴──────┐ ┌──────┴──────┐
▼ ▼ ▼ ▼
Parent 2 Sibling 2 Child 2 Child 3
(d=2) (d=1) (d=2) (d=2)
Priority Score = salience × phase_weight × distance_decay^d
Expansion Order:
1. Pop highest priority from frontier
2. Add to selected slice
3. Add unvisited neighbors to frontier
4. Repeat until max_nodes or frontier empty---
Slice Export Structure
┌─────────────────────────────────────────────────────────────────┐
│ SliceExport │
├─────────────────────────────────────────────────────────────────┤
│ anchor_turn_id: UUID │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ turns: Vec<TurnSnapshot> (sorted by TurnId) │ │
│ │ ├─ id, session_id, role, phase │ │
│ │ ├─ salience, depth, word_count │ │
│ │ ├─ commitment, uncertainty, recovery_margin │ │
│ │ ├─ content_hash, created_at │ │
│ │ └─ ... │ │
│ └───────────────────────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ edges: Vec<Edge> (sorted by parent, child) │ │
│ │ └─ parent_id, child_id, edge_type (Reply|Branch|Merge) │ │
│ └───────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ PROVENANCE FIELDS (All Required) │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ slice_id: SliceFingerprint │ │
│ │ └─ Hash of (anchor, turn_ids, edges, policy) │ │
│ ├───────────────────────────────────────────────────────────┤ │
│ │ graph_snapshot_hash: GraphSnapshotHash │ │
│ │ └─ Hash of (content_hashes, edge_count, schema_version) │ │
│ ├───────────────────────────────────────────────────────────┤ │
│ │ admissibility_token: AdmissibilityToken │ │
│ │ └─ HMAC-SHA256(secret, slice_id | anchor | policy | ...)│ │
│ ├───────────────────────────────────────────────────────────┤ │
│ │ policy_id: "slice_policy_v1" │ │
│ │ policy_params_hash: "a1b2c3d4..." │ │
│ │ schema_version: "1.0.0" │ │
│ └───────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘---
Deployment Architecture
mermaid
flowchart TB
subgraph CloudRun [Google Cloud Run]
GK[Graph Kernel Service<br/>gcr.io/PROJECT/graph-kernel:latest<br/>Port 8001]
subgraph Config [Configuration]
Mem[Memory: 1Gi]
CPU[CPU: 1]
Concurrency[Concurrency: 50]
Instances[Instances: 0-10]
end
subgraph Secrets [Mounted Secrets]
HMACSecret[KERNEL_HMAC_SECRET<br/>kernel-hmac-[sensitive field redacted]
DBSecret[DATABASE_URL<br/>database-url:latest]
end
end
subgraph Supabase [Supabase PostgreSQL]
DB[(memory_turns<br/>conversations<br/>edges)]
end
subgraph CloudBuild [Cloud Build]
Build[cloudbuild-service.yaml<br/>Docker Build → Push → Deploy]
end
subgraph Monitoring [Observability]
CloudLogging[Cloud Logging<br/>JSON Structured Logs]
CloudMonitoring[Cloud Monitoring<br/>Alerts & Dashboards]
Prometheus[Prometheus<br/>Custom Metrics]
end
Build --> GK
GK --> DBSecret --> DB
GK --> HMACSecret
GK --> CloudLogging
GK --> CloudMonitoring
GK -.-> Prometheus---
Security Model
┌─────────────────────────────────────────────────────────────────────┐
│ SECURITY BOUNDARY │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Graph Kernel (Trusted) │ │
│ │ │ │
│ │ KERNEL_HMAC_SECRET ──────┐ │ │
│ │ (Google Secret Manager) │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ AdmissibilityToken │ │ │
│ │ │ HMAC-SHA256 Signing │ │ │
│ │ └─────────────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ SliceExport │ │ │
│ │ │ + admissibility_token │ │ │
│ │ └─────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ Downstream Services (Untrusted) │ │
│ │ │ │
│ │ RAG++, Orbit, etc. │ │
│ │ │ │
│ │ ┌─────────────────────────────────────────────────────┐ │ │
│ │ │ MUST verify admissibility_token before: │ │ │
│ │ │ • Using turns from slice │ │ │
│ │ │ • Promoting content to higher lifecycle phases │ │ │
│ │ │ • Storing derived artifacts │ │ │
│ │ └─────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Token verification via POST /api/verify_token │ │
│ │ (constant-time comparison, no secret exposure) │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ INVARIANT: No Phantom Authority │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Without a valid admissibility_token, content is NOT admissible. │
│ Tokens cannot be forged without KERNEL_HMAC_SECRET. │
│ │
└─────────────────────────────────────────────────────────────────────┘---
Health Check Flow
mermaid
sequenceDiagram
participant CloudRun as Cloud Run
participant GK as Graph Kernel
participant DB as PostgreSQL
Note over CloudRun,DB: Startup Probe
CloudRun->>+GK: GET /health/startup
GK->>+DB: SELECT 1
DB-->>-GK: OK
GK-->>-CloudRun: {"startup": true, "database": true}
Note over CloudRun,DB: Readiness Probe (repeated)
loop Every 10s
CloudRun->>+GK: GET /health/ready
GK->>+DB: SELECT 1
DB-->>-GK: OK
GK-->>-CloudRun: {"ready": true, "database": true}
end
Note over CloudRun,DB: Liveness Probe (repeated)
loop Every 30s
CloudRun->>+GK: GET /health/live
GK-->>-CloudRun: {"live": true}
Note over GK: No DB check (fast)
end---
ASCII Diagram (Fallback)
GRAPH KERNEL SERVICE
═══════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────┐
│ API LAYER (Axum) │
│ ┌─────────────┐ ┌───────────────┐ ┌─────────────────────┐ │
│ │ /api/slice │ │ /api/verify │ │ /health/* │ │
│ │ (POST) │ │ (POST) │ │ (GET) │ │
│ └──────┬──────┘ └───────┬───────┘ └──────────┬──────────┘ │
└─────────┼─────────────────┼──────────────────────┼──────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ CORE ENGINE │
│ ┌─────────────────┐ ┌─────────────────┐ ┌────────────────┐ │
│ │ ContextSlicer │ │ PolicyRegistry │ │ TokenAuthority │ │
│ │ - Priority Queue│ │ - Immutable │ │ - HMAC-SHA256 │ │
│ │ - BFS Expansion │ │ - Hash-stable │ │ - Verification │ │
│ └────────┬────────┘ └─────────────────┘ └────────────────┘ │
└───────────┼─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ STORAGE LAYER │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ PostgresGraphStore │ │
│ │ - Connection Pool (min=2, max=10) │ │
│ │ - test_before_acquire(true) │ │
│ │ - idle_timeout(300s), max_lifetime(1800s) │ │
│ └────────────────────────────┬────────────────────────────┘ │
└───────────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ POSTGRESQL (Supabase) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │memory_turns │ │conversations│ │ edges │ │
│ │- id │ │- id │ │- parent_id │ │
│ │- parent_id │ │- project_id │ │- child_id │ │
│ │- content │ │- title │ │- edge_type │ │
│ │- content_hash│ │ │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘---
Related Documents
- [15-GRAPH_KERNEL.md](../15-GRAPH_KERNEL.md) — Full specification
- [rag-architecture.md](rag-architecture.md) — RAG++ integration
- [deployment-topology.md](deployment-topology.md) — Cloud deployment
Promotion Decision
Promote into a technical note or architecture paper with implementation anchors.
Source Anchor
Comp-Core/docs/architecture/diagrams/graph-kernel-architecture.md
Detected Structure
Method · Evaluation · Architecture