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/>~90% OpenCypher"]
        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-08-19. Most files now align at 1.7.0. Two stragglers remain — treat as bump-together candidates on the next release, not intentional independence:

• crates/samyama-gpu/Cargo.toml — 1.1.0 (last bumped when GPU landed in OSS)
• sdk/python/samyama_mcp/__init__.py — 0.7.0 (__version__ string not updated alongside the parent SDK)

OSS tag lag: last published tag is v1.1.0; the tree is at 1.7.0 — 6 minors of unreleased work. Every 1.7.0 in this section is a WIP number, not a shipped SKU.

SGE tracks its own scheme: root/cli/crates at 1.1.0, sdk/python/pyproject.toml at 0.7.0, and its CLAUDE.md still reads v0.9.0 (stale — needs bumping alongside next OSS→SGE sync).

graph LR
    V["Version<br/>(currently 1.7.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<br/>⚠ 1.1.0 straggler"]
    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/>(ECR image tag)"]

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

9. Technology Stack

Versions pinned from samyama-graph/Cargo.toml at tree version 1.7.0 (verified 2026-08-19).