Architecture Overview

ContextGraph OS is designed as a layered architecture where each layer builds upon the capabilities of the layers below it.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        ContextGraph OS                          │
├─────────────────────────────────────────────────────────────────┤
│  Interface Layer                                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │  REST API   │  │     CLI     │  │  Webhooks   │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
├─────────────────────────────────────────────────────────────────┤
│  SDK Layer                                                      │
│  ┌─────────────────────────────────────────────────┐           │
│  │                      SDK                         │           │
│  │  (Unified API for all ContextGraph operations)  │           │
│  └─────────────────────────────────────────────────┘           │
├─────────────────────────────────────────────────────────────────┤
│  Advanced Capabilities Layer                                    │
│  ┌───────────┐ ┌───────────┐ ┌───────────────┐ ┌───────────┐  │
│  │    Viz    │ │ Reasoning │ │Recommendations│ │ Telemetry │  │
│  └───────────┘ └───────────┘ └───────────────┘ └───────────┘  │
├─────────────────────────────────────────────────────────────────┤
│  Execution Layer                                                │
│  ┌─────────────┐  ┌─────────────┐                              │
│  │  Executor   │  │  Handlers   │                              │
│  └─────────────┘  └─────────────┘                              │
├─────────────────────────────────────────────────────────────────┤
│  Agent Layer                                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │   Agents    │  │ Capabilities│  │ Hierarchies │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
├─────────────────────────────────────────────────────────────────┤
│  Governance Layer                                               │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────────┐│
│  │  Policy   │ │Exceptions │ │   RBAC    │ │   Compliance    ││
│  └───────────┘ └───────────┘ └───────────┘ └─────────────────┘│
│  ┌─────────────────────────────────────────────────┐           │
│  │              Decision Trace Graph               │           │
│  └─────────────────────────────────────────────────┘           │
├─────────────────────────────────────────────────────────────────┤
│  Knowledge Layer                                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │     CKG     │  │ Provenance  │  │  Retrieval  │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
├─────────────────────────────────────────────────────────────────┤
│  Foundation Layer                                               │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
│  │    Core     │  │   Storage   │  │  Ontology   │             │
│  └─────────────┘  └─────────────┘  └─────────────┘             │
└─────────────────────────────────────────────────────────────────┘

Layer Descriptions

Foundation Layer

The base layer providing essential primitives:

PackagePurpose
coreBranded types, Result pattern, time utilities, error types
storageAbstract storage interface with SQLite and in-memory implementations
ontologySchema definitions, versioning, validation, code generation

Knowledge Layer

Manages all knowledge and provenance:

PackagePurpose
ckgContextual Knowledge Graph - entities and claims with temporal context
provenanceImmutable ledger tracking all data origins with hash chain verification
retrievalContext assembly with temporal, scope, and confidence filtering

Governance Layer

Handles policies, decisions, and access control:

PackagePurpose
dtgDecision Trace Graph - tracks decisions through their lifecycle
policyPolicy ledger with deny-takes-precedence evaluation
exceptionsException requests and approvals for policy overrides
rbacRole-based access control with permission inheritance
complianceAudit reports, GDPR features, compliance tracking

Agent Layer

Manages autonomous agents and their capabilities:

PackagePurpose
agentAgent registry, capabilities, and problem-space graphs
executionAction execution framework with policy enforcement

Advanced Capabilities Layer

Specialized features for analysis and insight:

PackagePurpose
vizVisualization in DOT, Mermaid, D3.js, and SVG formats
reasoningSemantic reasoning, inference rules, contradiction detection
recommendationsDecision recommendations based on precedents
telemetryOpenTelemetry-compatible tracing, metrics, logging

Interface Layer

External interfaces for system access:

PackagePurpose
sdkUnified TypeScript SDK for all operations
apiREST API with authentication and rate limiting
cliCommand-line tools and interactive REPL
webhooksEvent notifications via HTTP callbacks

Data Flow

Claim Creation Flow

User/Agent Request
       │
       ▼
   ┌───────┐
   │  SDK  │
   └───┬───┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│   Policy    │────▶│   Enforce   │
│  Evaluation │     │  Decision   │
└─────────────┘     └──────┬──────┘
                           │
       ┌───────────────────┴───────────────────┐
       ▼                                       ▼
┌─────────────┐                         ┌─────────────┐
│     CKG     │                         │ Provenance  │
│ Store Claim │                         │   Record    │
└─────────────┘                         └─────────────┘
       │                                       │
       └───────────────────┬───────────────────┘
                           ▼
                    ┌─────────────┐
                    │   Storage   │
                    └─────────────┘

Decision Lifecycle

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│ PROPOSED │────▶│ APPROVED │────▶│ EXECUTED │────▶│COMPLETED │
└──────────┘     └────┬─────┘     └──────────┘     └──────────┘
      │               │
      │               ▼
      │          ┌──────────┐
      └─────────▶│ REJECTED │
                 └──────────┘

Key Design Patterns

1. Branded Types

All identifiers are branded types for type safety:

type EntityId = string & { readonly __brand: 'EntityId' };
type ClaimId = string & { readonly __brand: 'ClaimId' };
type AgentId = string & { readonly __brand: 'AgentId' };

2. Result Pattern

All operations return Result<T, Error> instead of throwing:

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

3. Temporal Context

All data includes temporal qualifications:

interface TemporalContext {
  validFrom: Timestamp;
  validUntil: Timestamp | null;
  observedAt: Timestamp;
}

4. Provenance Chain

Every data mutation creates a provenance entry with hash linking:

interface ProvenanceEntry {
  id: ProvenanceId;
  hash: string;
  previousHash: string | null;
  type: ProvenanceType;
  data: unknown;
  timestamp: Timestamp;
}

Storage Architecture

Abstract Interface

interface StorageInterface {
  get<T>(key: string): Promise<Result<T | null>>;
  set<T>(key: string, value: T): Promise<Result<void>>;
  delete(key: string): Promise<Result<void>>;
  list<T>(prefix: string): Promise<Result<T[]>>;
  query<T>(query: Query): Promise<Result<T[]>>;
}

Implementations

  • InMemoryStorage: Fast, ephemeral, great for testing
  • SQLiteStorage: Persistent, ACID-compliant, production-ready

Extension Points

Custom Storage

Implement StorageInterface for custom backends:

class RedisStorage implements StorageInterface {
  // Implementation
}

Custom Action Handlers

Register handlers for any action type:

client.registerHandler('custom', 'resource', async (action) => {
  // Handle the action
  return ok(result);
});

Custom Policy Conditions

Extend policy conditions:

{
  field: 'custom.property',
  operator: 'custom_op',
  value: 'expected'
}

Next Steps