Ecosystem Architecture & Dependency Graph

This chapter maps the full Samyama ecosystem: repositories, modules, features, and knowledge graph projects — with dependency graphs showing how everything connects.

1. Repository Map

Verified against live inventory (53 repos in the samyama-ai GitHub org; Gitea Samyama.ai org) and the working checkouts in graph_ws. Last reconciled 2026-08-19.

Hosting topology

Three hosts, and several repos live on more than one:

• GitHub samyama-ai — public OSS engine + public KG repos (53 repos).
• Gitea git.samyama.ai/Samyama.ai — all private repos, plus mirrors of the public ones.
• GitHub VaidhyaMegha — the web/product front ends.

samyama-graph is triple-hosted (GitHub origin, Gitea, GitLab). Most KG repos are dual-hosted: Gitea (gitea remote) + GitHub (origin, public).

graph LR
    subgraph Engine ["Engine"]
        SG["samyama-graph<br/>(OSS · GitHub+Gitea+GitLab)"]
        SGE["samyama-graph-enterprise<br/>(private · Gitea)"]
    end

    subgraph Support ["Docs · Research · Benchmarks (private · Gitea)"]
        SC["samyama-cloud<br/>(book, wiki, deploy)"]
        SR["samyama-research<br/>(papers)"]
        CB["samyama-graph-<br/>competitor-benchmarks<br/>(LDBC + federation results)"]
        SS["samyama-graph-solutions"]
    end

    subgraph KGs ["~25 KG repos (Gitea + GitHub public)"]
        BIO["Biomedical: pubmed-kg,<br/>clinicaltrials-kg, pathways-kg,<br/>druginteractions-kg, surveillance-kg,<br/>health-determinants-kg,<br/>health-systems-kg,<br/>breast-cancer-pathway-kg,<br/>mental_health-kg"]
        SEC["Security / IT-ops: mitre-attack-kg,<br/>nvd-cve-kg, d3fend-kg, itbench-kg,<br/>lea-cybercrime, devops-kg"]
        DOM["Industrial / finance / other: assetops-kg,<br/>bank-model-risk-kg, powergrid-kg,<br/>telecom-kg, edge-ai-kg,<br/>legal-judgments-graph-kg,<br/>wildfire-evac-kg, regulatory-affairs-kg"]
        DEMO["Demo / sport / media: cricket-kg,<br/>imdb-kg, football-kg, edtech-kg"]
    end

    subgraph Web ["Front ends (GitHub · VaidhyaMegha)"]
        SI["samyama-insight<br/>(React + book at /book)"]
        SGW["samyama-graph-web"]
    end

    subgraph AIApps ["AI apps"]
        CHAT["samyama-chat<br/>(FastAPI GraphRAG chat UI)"]
        GRR["graphrag-rs<br/>(LLM-powered KG builder<br/>+ MCP server)"]
    end

    SG -->|"local path remote 'sg' → sync"| SGE
    SG -->|"Python SDK"| BIO
    SG -->|"Python SDK"| SEC
    SG -->|"Python SDK"| DOM
    SG -->|"Python SDK"| DEMO
    SG -->|"TS SDK"| SI
    SG --> SGW
    SG -->|"embedded (cargo path+version dep)"| GRR
    SG -->|"HTTP :8080"| CHAT
    BIO -->|".sgsnap → federation"| CB
    SG -->|"benchmarked by"| CB
    SGE -->|"deploy scripts"| SC
    SC -->|"mdBook build → public/book-static/"| SI
    SR -.->|"published PDFs"| SI
    CB -.->|"results feed papers"| SR

    style SG fill:#4a9eff,stroke:#333,color:#fff
    style SGE fill:#ff6b6b,stroke:#333,color:#fff
    style SI fill:#51cf66,stroke:#333,color:#fff
    style SGW fill:#51cf66,stroke:#333,color:#fff
    style SC fill:#ffd43b,stroke:#333
    style SR fill:#ffd43b,stroke:#333
    style CB fill:#ff922b,stroke:#333,color:#fff
    style SS fill:#ffd43b,stroke:#333
    style BIO fill:#b197fc,stroke:#333,color:#fff
    style SEC fill:#b197fc,stroke:#333,color:#fff
    style DOM fill:#b197fc,stroke:#333,color:#fff
    style DEMO fill:#b197fc,stroke:#333,color:#fff
    style CHAT fill:#ffa8a8,stroke:#333
    style GRR fill:#ffa8a8,stroke:#333

Core repositories

Knowledge-graph repositories (~25)

Each loads its domain data through the Python SDK and exports a .sgsnap snapshot to s3://samyama-data/snapshots/. The biomedical set is what the 15-KG federation composes.

External upstreams tracked as forks/remotes: IBM/AssetOpsBench, itbench-hub/ITBench.

AMR data was folded into surveillance-kg (see AMRProfile label) — the previously-listed amr-kg no longer exists as a separate repo.

The samyama-ai GitHub org also holds ~25 research-artifact repos (one per paper — ce-metric-eval, token-cost-ledger, lsm-bloom-allocation, filtered-ann-regret, …) which are reproduction packages rather than ecosystem components, so they are not shown above.

Ecosystem in Action

Graph Simulation — Cricket KG (36K nodes, 1.4M edges) with live activity particles

Click for full demo (1:56) — Dashboard, Cypher Queries, and Graph Simulation

2. samyama-graph Module Architecture

The OSS engine is organized into 17 modules under src/, 4 workspace crates, and 3 SDK packages (2 directories — sdk/python ships both samyama and samyama_mcp).

Full src/ listing: agent, algo, embed, graph, http, index, nlq, optimization, persistence, protocol, query, raft, rdf, sharding, snapshot, sparql, vector. The diagram shows the principal ones; algo, embed, http, index, optimization, rdf, sparql and snapshot are omitted from the graph for readability.

graph TB
    subgraph "SDK Layer"
        PYSDK["sdk/python<br/>samyama (PyO3)"]
        MCP["sdk/python<br/>samyama_mcp"]
        TSSDK["sdk/typescript<br/>samyama-sdk"]
    end

    subgraph "Crates"
        SDK["crates/samyama-sdk<br/>EmbeddedClient + RemoteClient"]
        ALGO["crates/samyama-graph-algorithms<br/>PageRank, WCC, SCC, BFS, etc."]
        OPT["crates/samyama-optimization<br/>Rao-family + classical metaheuristics"]
        GPUC["crates/samyama-gpu<br/>wgpu + CUDA (opt-in)"]
    end

    subgraph CLI
        CLIRS["cli/<br/>query, status, shell"]
    end

    subgraph "Core Engine (src/)"
        QUERY["query/<br/>parser (Pest) + planner + executor"]
        GRAPH["graph/<br/>store, node, edge, property, catalog"]
        PROTO["protocol/<br/>RESP server + HTTP API"]
        PERSIST["persistence/<br/>RocksDB, WAL, tenant"]
        RAFT["raft/<br/>openraft consensus"]
        NLQ["nlq/<br/>text-to-Cypher (multi-provider)"]
        AGENT["agent/<br/>GAK runtime + tools"]
        VECTOR["vector/<br/>HNSW index"]
        SHARD["sharding/<br/>tenant-level routing"]
    end

    %% SDK dependencies
    PYSDK --> SDK
    MCP --> PYSDK
    TSSDK -->|"HTTP fetch"| PROTO
    CLIRS --> SDK

    %% Crate dependencies
    SDK --> QUERY
    SDK --> GRAPH
    SDK --> PERSIST
    SDK --> ALGO
    SDK --> OPT
    SDK --> NLQ
    SDK --> AGENT
    SDK --> VECTOR

    %% Core module dependencies
    QUERY --> GRAPH
    PROTO --> QUERY
    PROTO --> GRAPH
    PERSIST --> GRAPH
    RAFT --> PERSIST
    NLQ --> QUERY
    AGENT --> NLQ
    VECTOR --> GRAPH
    SHARD --> PERSIST
    ALGO --> GRAPH
    GPUC -->|"--features gpu/cuda"| ALGO

    style QUERY fill:#4a9eff,stroke:#333,color:#fff
    style GRAPH fill:#51cf66,stroke:#333,color:#fff
    style PROTO fill:#ffd43b,stroke:#333
    style SDK fill:#ff6b6b,stroke:#333,color:#fff
    style MCP fill:#b197fc,stroke:#333,color:#fff
    style PYSDK fill:#b197fc,stroke:#333,color:#fff

Module Responsibilities

3. Enterprise Feature Layering (OSS → SGE)

graph TB
    subgraph OSS ["samyama-graph (OSS — Apache 2.0)"]
        QE["Query Engine<br/>openCypher TCK<br/>97.3% of evaluated,<br/>96.5% coverage"]
        PS["Persistence<br/>RocksDB + WAL"]
        VS["Vector Search<br/>HNSW"]
        GA["Graph Algorithms<br/>PageRank, WCC, BFS..."]
        NQ["NLQ<br/>text-to-Cypher"]
        HV["HTTP Visualizer"]
        RF["Raft Consensus<br/>(basic)"]
        MO["Metaheuristic<br/>Optimization"]
        RDF["RDF / SPARQL"]
        GPUO["GPU Acceleration<br/>(wgpu + CUDA, opt-in)"]
        AG["Agent / GAK Runtime"]
        SNAP["Snapshot Export/Import<br/>(.sgsnap)"]
        SR["Sharding<br/>(basic tenant router)"]
    end

    subgraph SGE ["samyama-graph-enterprise (Proprietary)"]
        MT["Multi-Tenancy<br/>Admin API (CRUD + quotas)"]
        MON["Prometheus /metrics<br/>+ OTLP"]
        HC["Health Checks"]
        BK["Backup & Restore<br/>(PITR)"]
        AU["Audit Trail"]
        SQ["Slow Query Log"]
        ADM["ADMIN.* Commands"]
        ERF["Enhanced Raft<br/>(HTTP transport)"]
        LIC["JET Licensing<br/>(Ed25519 signed)"]
        CBO["Cost-Based Optimizer<br/>+ Graph-Native Planning"]
        COL["Columnar Property Store<br/>Label Interning · Index Manager"]
        LDR["Enterprise Ingestion<br/>(chembl, uniprot, opentargets,<br/>umls, disgenet, sider, go/goa,<br/>obo, clinvar/dbsnp, crosslink)"]
    end

    subgraph DEV ["In-flight on dev branch (unreleased)"]
        SVS["Sharded Versioned<br/>Storage (MVCC)"]
        XSC["Cross-Shard Read<br/>Coordinator"]
        PHA["Production HA<br/>(Raft F-series +<br/>snapshot install)"]
    end

    SGE -->|"inherits all of"| OSS
    DEV -.->|"targets"| SGE

    GPUO -->|"accelerates"| GA
    GPUO -->|"accelerates"| VS
    MON -->|"observes"| QE
    BK -->|"snapshots"| PS
    AU -->|"logs"| QE
    LIC -->|"gates"| SGE
    CBO -->|"replaces"| QE
    COL -->|"backs"| PS
    XSC -->|"reads via"| SVS
    PHA -->|"replicates"| SVS

    style OSS fill:#e8f5e9,stroke:#2e7d32
    style SGE fill:#fce4ec,stroke:#c62828
    style DEV fill:#fff8e1,stroke:#f57f17,stroke-dasharray: 5 5

Verified 2026-08-19. Authoritative feature-matrix source is Enterprise Edition Overview → Feature Matrix. Shifts since last reconciliation:

• GPU acceleration ported to OSS (crates/samyama-gpu, samyama-graph#291): opt-in via --features gpu (wgpu/WGSL) or --features cuda (via cudarc/NVRTC). Enterprise still ships tuned defaults and CUDA prebuilds.
• Multi-Tenancy moved to SGE side: OSS provides per-tenant isolation primitives in src/persistence/tenant.rs, but the tenant CRUD Admin API + quotas + audit surface is SGE-only.
• Added on OSS side: agent/ (GAK runtime), snapshot/ (.sgsnap), sharding/ (basic tenant router).
• Added on SGE side: Cost-Based Optimizer + Graph-Native Planning (ADR-015/017), Columnar Property Store / Label Interning / Index Manager (ADR-021/028/029), Enterprise Ingestion (10 biomedical loaders), OTLP metrics alongside Prometheus.
• Dashed “In-flight on dev” cluster: Sharded Versioned Storage + Cross-Shard Read Coordinator (MVCC, Phase 5.2, PRs #394–#406) and Production HA (Raft F-series + snapshot install, ADR-034 on the dev-ha branch). Not yet in a shipped release; called out so the diagram doesn’t advertise unreleased features on the SGE side.

4. Knowledge Graph Projects

All KG projects share the same stack: Python SDK → samyama-mcp-serve → custom config.

The diagram shows three representative projects; there are ~25 KG repositories (see §1). The largest is pubmed-kg — 66.2M nodes / 1.04B edges — which anchors the 15-KG biomedical federation (264.2M nodes / 1.35B edges).

graph TB
    subgraph Engine ["Samyama Engine"]
        SG["samyama-graph<br/>(Rust)"]
        PYSDK["samyama<br/>(Python SDK / PyO3)"]
        MCPSERVE["samyama_mcp<br/>(MCP serve)"]
    end

    subgraph KGs ["Knowledge Graph Projects"]
        subgraph CKG ["cricket-kg"]
            CETL["etl/loader.py<br/>(Cricsheet JSON)"]
            CMCP["mcp_server/<br/>config.yaml (12 custom)"]
            CTEST["tests/<br/>25 MCP tests"]
        end

        subgraph CTKG ["clinicaltrials-kg"]
            CTETL["etl/loader.py<br/>(API or AACT flat files)"]
            CTMCP["mcp_server/<br/>16 tools (hand-written)"]
            CTAACT["etl/aact_loader.py<br/>(500K+ studies)"]
        end

        subgraph AOKG ["assetops-kg"]
            AOETL["etl/loader.py"]
            AOMCP["mcp_server/<br/>9 tools"]
        end
    end

    SG --> PYSDK
    PYSDK --> MCPSERVE
    MCPSERVE --> CMCP
    MCPSERVE -.->|"SK-14: migrate"| CTMCP
    MCPSERVE -.->|"SK-15: migrate"| AOMCP
    PYSDK --> CETL
    PYSDK --> CTETL
    PYSDK --> CTAACT
    PYSDK --> AOETL

    style SG fill:#4a9eff,stroke:#333,color:#fff
    style MCPSERVE fill:#b197fc,stroke:#333,color:#fff
    style CKG fill:#d0f0c0,stroke:#2e7d32
    style CTKG fill:#ffe0b2,stroke:#e65100
    style AOKG fill:#e1bee7,stroke:#6a1b9a

KG Schema Summary

Grouped by domain. ✅ shipped = loader + MCP server exercised end-to-end; 🟡 partial = data loads but tools/coverage still thin; ⚪ stub = README exists, ingest not yet wired.

Biomedical (federation inputs)

Security / IT-ops

Industrial / finance / regulatory

Legal / public safety

Demo / sport / media

5. Feature Dependency Graph (Backlog)

The complete feature dependency chain across all backlog items. Green = done · blue = in progress · orange = reverted / regressed · white = planned. Statuses reconciled 2026-08-19; authoritative source is samyama-cloud/BACKLOG.md.

graph TB
    subgraph "Query Engine (Done ✅)"
        QE01["QE-01<br/>Parameterized $param"]
        QE02["QE-02<br/>PROFILE stats"]
        QE03["QE-03<br/>shortestPath()"]
        QE07["QE-07<br/>CALL procedures"]
    end

    subgraph "Cypher Completeness (Done ✅)"
        CY01["CY-01<br/>collect(DISTINCT)"]
        CY02["CY-02<br/>datetime args"]
        CY04["CY-04<br/>Named paths"]
        CY05["CY-05<br/>Path functions"]
    end

    subgraph "Planner / Optimizer (Done ✅)"
        QP01["QP-01 Predicate pushdown"]
        QP02["QP-02 Cost-based"]
        QP05["QP-05 Plan cache"]
        QP11["QP-11 Graph-native enum"]
        QP12["QP-12 Triple stats"]
        QP13["QP-13 ExpandInto"]
        QP14["QP-14 Direction reversal"]
        QP15["QP-15 Logical plan IR"]
    end

    subgraph "Planner (Planned)"
        QP06["QP-06<br/>Histogram stats"]
        QP09["QP-09<br/>Operator fusion"]
        QP10["QP-10<br/>Adaptive exec"]
    end

    subgraph "Indexes (Done ✅)"
        IX01["IX-01..06<br/>DROP/SHOW/Composite/Unique"]
    end

    subgraph "Indexes (Planned)"
        IX07["IX-07<br/>Full-text index"]
        IX08["IX-08<br/>OR union scans"]
    end

    subgraph "Performance (Done ✅)"
        PF01["PF-01 CSR"]
        PF04["PF-04 Late materialization"]
        PF06["PF-06 AST cache"]
        PF07["PF-07 MVCC<br/>(Phase 5.2 v1)"]
        PF09["PF-09 WCO joins<br/>(LeapFrog TrieJoin)"]
    end

    subgraph "Performance (Planned)"
        PF10["PF-10<br/>Parallel exec"]
    end

    subgraph "Data Structures (Done ✅)"
        DS01["DS-01 Triple stats"]
        DS02["DS-02 Sorted adjacency"]
    end

    subgraph "Data Structures (Planned)"
        DS03["DS-03<br/>Type-partitioned adj"]
    end

    subgraph "SDK / MCP (Done ✅)"
        SK01["SK-01..06<br/>Rust/Python/TS SDK + CLI"]
        SK09["SK-09 npm publish"]
        SK10["SK-10 EXPLAIN/PROFILE"]
        SK11["SK-11 Schema/Stats"]
        SK12["SK-12<br/>samyama-mcp-serve"]
        SK13["SK-13<br/>cricket-kg MCP"]
    end

    subgraph "SDK (Planned)"
        SK14["SK-14<br/>clinicaltrials MCP"]
        SK15["SK-15<br/>assetops MCP"]
    end

    subgraph "HA (Done ✅)"
        HA01["HA-01 Raft"]
        HA02["HA-02 Sharding"]
        HA03["HA-03 Vector persist"]
    end

    subgraph "HA (In Progress 🔵)"
        HA05["HA-05<br/>Graph sharding<br/>(per-shard Raft — ADR-034)"]
    end

    subgraph "HA (Planned)"
        HA04["HA-04<br/>Temporal queries<br/>(AT TIME syntax)"]
        HA06["HA-06<br/>Distributed exec"]
    end

    subgraph "Distributed & MVCC 2026 (Shipped ✅ / ⚠ reverted)"
        XSC["Cross-Shard Read<br/>Coordinator<br/>(PRs #394–#404)"]
        VDS["Versioned-Disk<br/>Write + Recovery<br/>(PR #405)"]
        WAM["Applied-Watermark<br/>Wiring (slice-d lag gate)<br/>(PR #406)"]
        TOM["Deleted-at-T<br/>Tombstones"]
        GC["Retention-Window GC<br/>(bounded by watermark)"]
        V2PC["Versioned-Tombstone 2PC<br/>⚠ reverted #494"]
    end

    subgraph "AI (Done ✅)"
        AI01["AI-01 GAK runtime"]
        AI02["AI-02 NLQ"]
        AI03["AI-03 Auto-embed"]
    end

    subgraph "AI / JIT KG (Planned)"
        AI07["AI-07<br/>Enterprise connectors"]
        AI08["AI-08<br/>Demand-driven agent"]
        AI09["AI-09<br/>Text-to-SQL bridge"]
        AI10["AI-10<br/>JIT KG demo"]
    end

    subgraph "GPU (Done ✅)"
        GP01["GP-01..10<br/>PageRank, CDLP, LCC,<br/>PCA, triangles, vectors,<br/>aggregates, sort"]
    end

    subgraph "Benchmarks (Done ✅)"
        BM01["BM-01..03<br/>Graphalytics, SNB, FinBench"]
    end

    subgraph "Benchmarks (Planned)"
        BM04["BM-04<br/>SF10 scale"]
        BM05["BM-05<br/>SNB BI tuning"]
        BM07["BM-07<br/>Comparative bench"]
    end

    subgraph "Visualizer (Done ✅)"
        VZ01["VZ-01..05<br/>Plan DAG, PROFILE,<br/>Stats, Console, Features"]
        VZ07["VZ-07..10<br/>Schema, CSV/JSON Import, E2E"]
    end

    subgraph "KG Projects"
        KG01["KG-01<br/>AACT full loader<br/>(in progress)"]
    end

    %% Dependencies
    CY01 & CY02 & QE03 & CY04 --> BM05
    CY04 --> CY05
    PF06 --> QP05
    QP01 & QP02 --> BM04
    PF07 --> HA04
    DS02 --> PF09
    HA05 --> HA06
    QE01 --> QP11
    QP12 --> QP11
    DS02 --> QP13
    QP14 --> QP11
    QP15 --> QP11
    SK09 --> VZ01
    SK10 --> VZ01
    SK11 --> VZ07
    QE07 --> VZ07
    SK12 --> SK13
    SK12 --> SK14
    SK12 --> SK15

    %% JIT KG chain
    AI01 --> AI07
    AI02 --> AI07
    SK12 --> AI07
    AI02 --> AI09
    AI07 --> AI08
    AI09 --> AI08
    AI08 --> AI10

    %% KG-01
    IX01 --> KG01

    %% Benchmark deps
    BM07 -.-> BM05

    style QE01 fill:#51cf66,stroke:#333,color:#fff
    style QE02 fill:#51cf66,stroke:#333,color:#fff
    style QE03 fill:#51cf66,stroke:#333,color:#fff
    style QE07 fill:#51cf66,stroke:#333,color:#fff
    style CY01 fill:#51cf66,stroke:#333,color:#fff
    style CY02 fill:#51cf66,stroke:#333,color:#fff
    style CY04 fill:#51cf66,stroke:#333,color:#fff
    style CY05 fill:#51cf66,stroke:#333,color:#fff
    style QP01 fill:#51cf66,stroke:#333,color:#fff
    style QP02 fill:#51cf66,stroke:#333,color:#fff
    style QP05 fill:#51cf66,stroke:#333,color:#fff
    style QP11 fill:#51cf66,stroke:#333,color:#fff
    style QP12 fill:#51cf66,stroke:#333,color:#fff
    style QP13 fill:#51cf66,stroke:#333,color:#fff
    style QP14 fill:#51cf66,stroke:#333,color:#fff
    style QP15 fill:#51cf66,stroke:#333,color:#fff
    style IX01 fill:#51cf66,stroke:#333,color:#fff
    style PF01 fill:#51cf66,stroke:#333,color:#fff
    style PF04 fill:#51cf66,stroke:#333,color:#fff
    style PF06 fill:#51cf66,stroke:#333,color:#fff
    style PF07 fill:#51cf66,stroke:#333,color:#fff
    style PF09 fill:#51cf66,stroke:#333,color:#fff
    style DS01 fill:#51cf66,stroke:#333,color:#fff
    style DS02 fill:#51cf66,stroke:#333,color:#fff
    style SK01 fill:#51cf66,stroke:#333,color:#fff
    style SK09 fill:#51cf66,stroke:#333,color:#fff
    style SK10 fill:#51cf66,stroke:#333,color:#fff
    style SK11 fill:#51cf66,stroke:#333,color:#fff
    style SK12 fill:#51cf66,stroke:#333,color:#fff
    style SK13 fill:#51cf66,stroke:#333,color:#fff
    style HA01 fill:#51cf66,stroke:#333,color:#fff
    style HA02 fill:#51cf66,stroke:#333,color:#fff
    style HA03 fill:#51cf66,stroke:#333,color:#fff
    style HA05 fill:#4a9eff,stroke:#333,color:#fff
    style AI01 fill:#51cf66,stroke:#333,color:#fff
    style AI02 fill:#51cf66,stroke:#333,color:#fff
    style AI03 fill:#51cf66,stroke:#333,color:#fff
    style GP01 fill:#51cf66,stroke:#333,color:#fff
    style BM01 fill:#51cf66,stroke:#333,color:#fff
    style VZ01 fill:#51cf66,stroke:#333,color:#fff
    style VZ07 fill:#51cf66,stroke:#333,color:#fff
    style KG01 fill:#4a9eff,stroke:#333,color:#fff
    style AI07 fill:#fff,stroke:#333
    style AI08 fill:#fff,stroke:#333
    style AI09 fill:#fff,stroke:#333
    style AI10 fill:#fff,stroke:#333

    %% Distributed & MVCC 2026 — internals of PF-07 / HA-05
    PF07 --> XSC
    PF07 --> VDS
    PF07 --> WAM
    PF07 --> TOM
    PF07 --> GC
    HA05 --> V2PC
    style XSC fill:#51cf66,stroke:#333,color:#fff
    style VDS fill:#51cf66,stroke:#333,color:#fff
    style WAM fill:#51cf66,stroke:#333,color:#fff
    style TOM fill:#51cf66,stroke:#333,color:#fff
    style GC fill:#51cf66,stroke:#333,color:#fff
    style V2PC fill:#ff922b,stroke:#333,color:#fff

6. Data Flow: Query → Enrichment → Response

This diagram shows the runtime data flow for a JIT KG query, incorporating the planned AI-07..AI-10 features.

sequenceDiagram
    participant U as User / Agent
    participant MCP as MCP Server
    participant NLQ as NLQ Pipeline
    participant QE as Query Engine
    participant GS as GraphStore
    participant AG as GAK Agent
    participant SRC as Enterprise Source<br/>(OneDrive / OLTP)

    U->>MCP: Natural language question
    MCP->>NLQ: text_to_cypher(question, schema)
    NLQ->>QE: MATCH (n:Person)-[:AUTHORED]->(d:Document)...
    QE->>GS: Execute query
    GS-->>QE: 0 results (gap detected)
    QE-->>MCP: Empty result set

    Note over MCP,AG: AI-08: Demand-driven enrichment triggers

    MCP->>AG: process_trigger(gap_context)
    AG->>SRC: AI-07: Pull from OneDrive (documents)
    SRC-->>AG: Document metadata + content
    AG->>NLQ: Extract entities (LLM)
    NLQ-->>AG: Cypher: CREATE (p:Person)..., CREATE (d:Document)...
    AG->>QE: Execute enrichment Cypher
    QE->>GS: MERGE nodes + edges

    AG->>SRC: AI-09: text-to-SQL (OLTP database)
    SRC-->>AG: Relational rows
    AG->>NLQ: Transform to graph entities (LLM)
    NLQ-->>AG: Cypher: CREATE (proj:Project)...
    AG->>QE: Execute enrichment Cypher
    QE->>GS: MERGE nodes + edges

    Note over MCP,GS: Graph enriched — re-execute original query

    MCP->>QE: Re-execute original Cypher
    QE->>GS: Execute query
    GS-->>QE: Results (populated)
    QE-->>MCP: Result set
    MCP-->>U: Answer with graph context

7. Deployment Architecture

graph TB
    subgraph "Samyama Server"
        SGE_BIN["samyama-graph<br/>(release binary)"]
        ROCKS["RocksDB<br/>(persistent storage)"]
        SI_DIST["samyama-insight<br/>(static dist/)"]
    end

    subgraph "Developer Workflow"
        SG_DEV["samyama-graph<br/>(cargo build)"]
        PY_DEV["Python SDK<br/>(maturin develop)"]
        KG_DEV["KG projects<br/>(python -m etl.loader)"]
    end

    subgraph "External Services"
        LLM["LLM Provider<br/>(OpenAI / Claude / Ollama)"]
    end

    SGE_BIN -->|":6379 RESP"| ROCKS
    SGE_BIN -->|":8080 HTTP"| SI_DIST
    SG_DEV -->|"local path remote 'sg'"| SGE_BIN
    SG_DEV --> PY_DEV --> KG_DEV
    SGE_BIN -->|"NLQ / GAK"| LLM

    style SGE_BIN fill:#ff6b6b,stroke:#333,color:#fff
    style SG_DEV fill:#4a9eff,stroke:#333,color:#fff

Production topologies in use today

The diagram above captures the dev-loop shape. In production, four topologies are exercised.

a) Single-node Docker (api.samyama.dev pattern). Sandbox and pilot tenants run this. A single samyama:1.x-licensed container (Debian-slim runtime, RocksDB in /data) exposes :6379 (RESP) and :8080 (HTTP) behind nginx for TLS termination. Healthcheck hits /api/status. Deploy script: samyama-graph-enterprise/deploy/enterprise/scripts/deploy.sh on the target host, invoked from release.sh over SSH. Systemd unit exists (samyama-enterprise.service) but is disabled in favour of Docker; the license file is baked into the image.

b) HA cluster (Raft, N=3) — dev-ha branch only. Three peers running the same image with an openraft-based transport; leader serves the client protocol, followers proxy write requests. RF (replication factor) support lives only on the dev-ha branch of samyama-graph-enterprise; ADR-034 tracks the production HA work. Not yet in a shipped release.

c) Sharded cluster (Phase 5.2) — code-only, no deploy script yet. The versioned-storage + per-shard Raft + cross-shard read coordinator stack (§5 “Distributed & MVCC 2026”) is on dev; there is currently no deploy.sh mode for it. Standing this up requires per-shard state-machine wiring plus a shard-layout config — no one-command deploy path.

d) Ecosystem sidecars around a deployed engine. Wherever the engine runs, the same set of adjuncts attach:

• nginx — TLS + Basic-Auth for the visualizer and REST paths.
• samyama-chat (FastAPI) — GraphRAG chat UI on a separate port; talks to :8080 and configures per-tenant LLMs via PATCH /api/tenants/:id.
• graphrag-rs — MCP server + KG builder; not a sidecar but a peer binary that embeds samyama-graph via a cargo path+version dep and can populate a fresh tenant from a folder of docs.
• samyama_mcp (Python, FastMCP v2) — stdio MCP bridge to the engine’s schema/tools; attached from a client machine, not deployed alongside the server.
• samyama-insight (React + Vite) — dashboard served as static assets on the same host, or bundled inside the engine binary via rust-embed.

External deployment used one-off: AWS spot cluster (samyama-graph/deploy/aws-spot-cluster/) — biomed-100M staging, ETL and hero-KG loads (chembl, opentargets, UMLS). Not a Raft cluster; ephemeral ETL boxes.

8. Version Sync Points

These are the files that carry a version and are updated together on a version bump (Step 0.5 in the workflow).

Verified 2026-10-06. OSS aligns at 1.11.0, and the alignment is enforced rather than observed: tests/version_consistency.rs fails the build if any crate manifest, an internal path pin, api/openapi.yaml, src/lib.rs, CLAUDE.md or the README badge disagrees, and prepare-release.yml bumps all of them in one step.

SGE enforces the same alignment, and is two releases behind OSS. Measured on main, 2026-10-06: root, cli, the crates, sdk/python/pyproject.toml, api/openapi.yaml and the README badge all at 1.9.0, newest tag v1.9.0 — cut 2026-10-02 on main’s tip, with the bump arriving as the last position of the OSS 1205–1320 port (samyama-graph-enterprise#638). Against OSS at 1.11.0 that is two minors. As of the same date, 1.10.0 is in flight and not yet merged; it lands the same way, as the final position of the next port batch, and will leave SGE one minor behind rather than two. SGE’s internal consistency holds either way — it is the gap to OSS, not the agreement within SGE, that the port narrows. The three that used to drift there are fixed: crates/samyama-gpu (was 1.1.0), the ten internal path pins (were 1.1.0), and the README badge (was 0.7.0, a full major behind — samyama-graph-enterprise#623 fixed it and added the check that reads it). SGE has the pin check and the badge check now, not just the manifest check.

One straggler remains, in both repos, for the same reason:

• sdk/python/samyama_mcp/__init__.py — 0.7.0 in OSS, 0.6.1 in SGE. pip show samyama reports the real version while samyama_mcp.__version__ reports these. No consistency test in either repo reads that file, so nothing catches it. Bumping it resets a clock that drifts again; deriving it from installed distribution metadata would make it unable to drift.

OSS tag lag: gone. v1.11.0 was tagged 2026-10-05 and published to PyPI, npm, GHCR and ECR Public, each verified against the registry rather than taken from a green CI run. ECR’s mirror, which needed a manual push for 1.10.0 and left the automation an open question as of 2026-10-02, ran unattended on the tag this time and emitted a clean two-platform index — so that question is answered for the ordinary tag path. crates.io is the exception, for a structural reason: the workflow authenticates with GitHub OIDC Trusted Publishing, and crates.io does not permit such a token to create a crate, only to add versions to one that exists. Crates already on crates.io therefore received 1.11.0 through CI as usual; crates publishing for the first time await one manual cargo publish before CI can ever carry them. Before 1.11.0 came v1.10.0 (2026-09-29), v1.9.0 (2026-09-21) and v1.8.0 (2026-09-15).

graph LR
    V["Version<br/>(currently 1.11.0)"]

    V --> CT["Cargo.toml<br/>(root)"]
    V --> CLI["cli/Cargo.toml"]
    V --> SDKRS["crates/samyama-sdk/<br/>Cargo.toml"]
    V --> OPTC["crates/samyama-optimization/<br/>Cargo.toml"]
    V --> ALGOC["crates/samyama-graph-algorithms/<br/>Cargo.toml"]
    V --> GPUCT["crates/samyama-gpu/<br/>Cargo.toml"]
    V --> PYC["sdk/python/Cargo.toml"]
    V --> PYP["sdk/python/pyproject.toml"]
    V --> MCPI["sdk/python/samyama_mcp/<br/>__init__.py<br/>⚠ 0.7.0 straggler"]
    V --> TSP["sdk/typescript/package.json"]
    V --> TSL["sdk/typescript/package-lock.json"]
    V --> API["api/openapi.yaml"]
    V --> LIB["src/lib.rs<br/>(test_version)"]
    V --> CMD["CLAUDE.md"]
    V --> RM["README.md<br/>(version badge + GHCR image tag)"]

    style V fill:#ffd43b,stroke:#333
    style MCPI fill:#ffe0b2,stroke:#e65100

9. Technology Stack

Versions pinned from samyama-graph/Cargo.toml at tree version 1.11.0 (re-read against v1.11.0 on 2026-10-06; every pin in the table below was unchanged from the 1.10.0 reading, so the table is carried forward on evidence rather than assumption).