# mayurkhalse/sarthi architecture

> Architecture diagram of the GitHub repository mayurkhalse/sarthi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mayurkhalse/sarthi
- Repository: https://github.com/mayurkhalse/sarthi

## Overview

Sarthi is a local MCP quality gate for AI coding agents, with a CLI and Antigravity setup adapter. The principal workflow detects and caches a project stack, supplies relevant engineering standards and workflows to the agent, then verifies project changes and reports whether the completion gate passes. Verification includes deterministic checks and sandboxed test execution. The graph also shows the documented standards-provider and platform-sandbox branches. Some subsystems are represented by their exact tree paths because their source was not sampled; edges without direct evidence are omitted.

Main entry points: [`src/sarthi/core/verify/verifier.py`](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/verifier.py) (Verification orchestrator), [`src/sarthi/mcp/tools.py`](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/mcp/tools.py) (MCP tools), [`src/sarthi/core/context.py`](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/context.py) (Context builder), [`src/sarthi/core/providers/registry.py`](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/registry.py) (Provider registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent entry points"]
  node_mcp["MCP server<br/>[server.py]"]
  node_tools["MCP tools<br/>[tools.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_antigravity["Antigravity adapter<br/>[adapter.py]"]
end

subgraph group_context["Project context"]
  node_context_builder["Context builder<br/>[context.py]"]
  node_stack["Stack detection<br/>[stack_detector.py]"]
  node_config["Project config<br/>[config.py]"]
  node_pathguard["Path guard<br/>[pathguard.py]"]
end

subgraph group_knowledge["Standards knowledge"]
  node_selector["Resource selector<br/>[selector.py]"]
  node_registry["Provider registry<br/>[registry.py]"]
  node_ecc["ECC provider<br/>[ecc.py]"]
  node_native["Native standards<br/>[native.py]"]
  node_workspace["Workspace standards<br/>[workspace.py]"]
  node_compiler["Resource compiler<br/>[compiler.py]"]
  node_rules["Rule loader<br/>[rules.py]"]
end

subgraph group_verification["Verification gate"]
  node_verifier["Verification orchestrator<br/>[verifier.py]"]
  node_runners["Check runners"]
  node_reporter["Findings reporter<br/>[reporter.py]"]
  node_trust["Command trust<br/>[trust.py]"]
  node_test_runner["Test runner<br/>[tests.py]"]
end

subgraph group_isolation["Execution isolation"]
  node_sandbox_manager["Sandbox manager<br/>[manager.py]"]
  node_staging["Workspace staging<br/>[staging.py]"]
  node_linux["Linux backend<br/>[linux.py]"]
  node_other_backends["Platform backends"]
end

node_agent(("AI agent"))

node_agent -->|"uses stdio"| node_mcp
node_mcp -->|"registers tools"| node_tools
node_agent -->|"requests standards"| node_tools
node_cli -->|"initializes project"| node_context_builder
node_antigravity -->|"configures server"| node_mcp
node_tools -->|"builds context"| node_context_builder
node_context_builder -->|"detects stack"| node_stack
node_context_builder -->|"loads config"| node_config
node_context_builder -->|"guards paths"| node_pathguard
node_tools -->|"selects standards"| node_selector
node_selector -->|"lists resources"| node_registry
node_registry -.->|"discovers provider"| node_ecc
node_registry -.->|"discovers provider"| node_native
node_registry -.->|"discovers provider"| node_workspace
node_selector -.->|"compiles resources"| node_compiler
node_tools -->|"fetches rules"| node_rules
node_tools -->|"runs verification"| node_verifier
node_verifier -->|"loads context"| node_context_builder
node_verifier -->|"loads rules"| node_rules
node_verifier -->|"dispatches checks"| node_runners
node_verifier -->|"checks commands"| node_trust
node_verifier -.->|"reports findings"| node_reporter
node_runners -.->|"includes test checks"| node_test_runner
node_test_runner -->|"executes in sandbox"| node_sandbox_manager
node_sandbox_manager -->|"dispatches backend"| node_linux
node_sandbox_manager -->|"selects by platform"| node_other_backends
node_sandbox_manager -.->|"stages workspace"| node_staging

click node_mcp "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/mcp/server.py"
click node_tools "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/mcp/tools.py"
click node_cli "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/cli.py"
click node_antigravity "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/adapters/antigravity/adapter.py"
click node_context_builder "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/context.py"
click node_stack "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/stack_detector.py"
click node_config "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/config.py"
click node_pathguard "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/pathguard.py"
click node_selector "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/resources/selector.py"
click node_registry "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/registry.py"
click node_ecc "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/ecc.py"
click node_native "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/native.py"
click node_workspace "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/workspace.py"
click node_compiler "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/resources/compiler.py"
click node_rules "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/rules.py"
click node_verifier "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/verifier.py"
click node_runners "https://github.com/mayurkhalse/sarthi/tree/main/src/sarthi/core/verify/runners"
click node_reporter "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/reporter.py"
click node_trust "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/trust.py"
click node_sandbox_manager "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/manager.py"
click node_staging "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/staging.py"
click node_linux "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/backends/linux.py"
click node_other_backends "https://github.com/mayurkhalse/sarthi/tree/main/src/sarthi/core/sandbox/backends"
click node_test_runner "https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/runners/tests.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_tools,node_cli,node_antigravity toneBlue
class node_context_builder,node_stack,node_config,node_pathguard toneAmber
class node_selector,node_registry,node_ecc,node_native,node_workspace,node_compiler,node_rules toneMint
class node_verifier,node_runners,node_reporter,node_trust,node_test_runner toneRose
class node_sandbox_manager,node_staging,node_linux,node_other_backends,node_agent toneIndigo
```

## Components

### Agent entry points

- [MCP server](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/mcp/server.py): `src/sarthi/mcp/server.py`
- [MCP tools](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/mcp/tools.py): `src/sarthi/mcp/tools.py`
- [CLI](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/cli.py): `src/sarthi/cli.py`
- [Antigravity adapter](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/adapters/antigravity/adapter.py): `src/sarthi/adapters/antigravity/adapter.py`

### Project context

- [Context builder](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/context.py): `src/sarthi/core/context.py`
- [Stack detection](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/stack_detector.py): `src/sarthi/core/stack_detector.py`
- [Project config](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/config.py): `src/sarthi/core/config.py`
- [Path guard](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/pathguard.py): `src/sarthi/core/pathguard.py`

### Standards knowledge

- [Resource selector](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/resources/selector.py): `src/sarthi/core/resources/selector.py`
- [Provider registry](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/registry.py): `src/sarthi/core/providers/registry.py`
- [ECC provider](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/ecc.py): `src/sarthi/core/providers/ecc.py`
- [Native standards](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/native.py): `src/sarthi/core/providers/native.py`
- [Workspace standards](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/providers/workspace.py): `src/sarthi/core/providers/workspace.py`
- [Resource compiler](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/resources/compiler.py): `src/sarthi/core/resources/compiler.py`
- [Rule loader](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/rules.py): `src/sarthi/core/rules.py`

### Verification gate

- [Verification orchestrator](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/verifier.py): `src/sarthi/core/verify/verifier.py`
- [Check runners](https://github.com/mayurkhalse/sarthi/tree/main/src/sarthi/core/verify/runners): `src/sarthi/core/verify/runners`
- [Findings reporter](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/reporter.py): `src/sarthi/core/verify/reporter.py`
- [Command trust](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/trust.py): `src/sarthi/core/verify/trust.py`
- [Test runner](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/verify/runners/tests.py): `src/sarthi/core/verify/runners/tests.py`

### Execution isolation

- [Sandbox manager](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/manager.py): `src/sarthi/core/sandbox/manager.py`
- [Workspace staging](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/staging.py): `src/sarthi/core/sandbox/staging.py`
- [Linux backend](https://github.com/mayurkhalse/sarthi/blob/main/src/sarthi/core/sandbox/backends/linux.py): `src/sarthi/core/sandbox/backends/linux.py`
- [Platform backends](https://github.com/mayurkhalse/sarthi/tree/main/src/sarthi/core/sandbox/backends): `src/sarthi/core/sandbox/backends`

### Other components

- **AI agent**

## Connections

- AI agent → MCP server: uses stdio (evidence: `README.md`)
- MCP server → MCP tools: registers tools (evidence: `src/sarthi/mcp/server.py`)
- AI agent → MCP tools: requests standards (evidence: `README.md`)
- CLI → Context builder: initializes project (evidence: `src/sarthi/cli.py`)
- Antigravity adapter → MCP server: configures server (evidence: `src/sarthi/adapters/antigravity/adapter.py`)
- MCP tools → Context builder: builds context (evidence: `src/sarthi/mcp/tools.py`)
- Context builder → Stack detection: detects stack (evidence: `src/sarthi/core/context.py`)
- Context builder → Project config: loads config (evidence: `src/sarthi/core/context.py`)
- Context builder → Path guard: guards paths (evidence: `src/sarthi/core/context.py`)
- MCP tools → Resource selector: selects standards (evidence: `src/sarthi/mcp/tools.py`)
- Resource selector → Provider registry: lists resources (evidence: `src/sarthi/core/resources/selector.py`)
- Provider registry → ECC provider: discovers provider
- Provider registry → Native standards: discovers provider
- Provider registry → Workspace standards: discovers provider
- Resource selector → Resource compiler: compiles resources
- MCP tools → Rule loader: fetches rules (evidence: `src/sarthi/mcp/tools.py`)
- MCP tools → Verification orchestrator: runs verification (evidence: `src/sarthi/mcp/tools.py`)
- Verification orchestrator → Context builder: loads context (evidence: `src/sarthi/core/verify/verifier.py`)
- Verification orchestrator → Rule loader: loads rules (evidence: `src/sarthi/core/verify/verifier.py`)
- Verification orchestrator → Check runners: dispatches checks (evidence: `src/sarthi/core/verify/verifier.py`)
- Verification orchestrator → Command trust: checks commands (evidence: `src/sarthi/core/verify/verifier.py`)
- Verification orchestrator → Findings reporter: reports findings
- Check runners → Test runner: includes test checks (evidence: `src/sarthi/core/verify/runners/tests.py`)
- Test runner → Sandbox manager: executes in sandbox (evidence: `src/sarthi/core/verify/runners/tests.py`)
- Sandbox manager → Linux backend: dispatches backend (evidence: `src/sarthi/core/sandbox/manager.py`)
- Sandbox manager → Platform backends: selects by platform (evidence: `src/sarthi/core/sandbox/manager.py`)
- Sandbox manager → Workspace staging: stages workspace (evidence: `src/sarthi/core/sandbox/manager.py`)