# jasgujral/mokata-oss architecture

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

- Interactive diagram: https://gitdiagram.com/jasgujral/mokata-oss
- Repository: https://github.com/jasgujral/mokata-oss

## Overview

1. **Repository shape: a Python core with multiple integration surfaces**
   - The main product is the `src/mokata` Python package, exposed as a CLI and also embedded into Claude Code via plugin/MCP/hook surfaces.
   - Surrounding it are docs, templates for slash commands, reusable “skills,” a VS Code extension, hook scripts, packaging assets, and a large test suite.

2. **Core execution boundary: deterministic engine vs AI-facing surfaces**
   - The `cli.py`, `__main__.py`, `pipeline.py`, `engine/`, `execmode/`, `modes/`, and related modules implement the deterministic orchestration layer.
   - The AI tools themselves are outside the core; mokata provides guarded workflows, context selection, gates, and audit rather than being an LLM runtime.

3. **Primary product flow: spec-driven pipeline**
   - The central flow is brainstorm → spec → test → develop → review, with gating between phases.
   - `engine/` contains phase/gate logic such as completeness, compliance, premortem, preview, and ship; this is the “no code before spec passes” boundary emphasized in the README.

4. **Governance subsystem: writes are mediated and audited**
   - `govern/` is the safety/control plane: rules, secrets, token budgeting, trust, hooks, lifecycle, ledger, revert, and gate enforcement.
   - Durable actions like writing code, memory, or config are human-gated and recorded; the audit ledger is a key cross-cutting data store for decision traceability.

5. **Knowledge subsystem: structural codebase awareness**
   - `knowledge/` provides codebase lookup and graph-style navigation through backends like grep and graph adapters, with Neo4j support present as an optional backend.
   - The repo explicitly treats the knowledge graph as “adopted” with a grep fallback, so architecture diagrams should show knowledge as a pluggable read layer feeding context selection and routing.

6. **Memory subsystem: persistent, local-first, self-healing state**
   - `memory/` handles episodic/decision memory, consolidation, embedding/vector retrieval, tiered storage, and backend abstraction.
   - The README indicates SQLite as the default local store and Postgres for shared/team setups; memory is a first-class durable subsystem, not an add-on.

7. **Execution modes: sequential vs parallel subagent orchestration**
   - `execmode/` contains routing, selection, decomposition, estimation, review, and task orchestration for different run styles.
   - The architecture supports a lowest-cost sequential path and a parallel fan-out model with isolated subagents and review, so the diagram should show execution mode as a strategy layer above the engine.

8. **Session and portability layer**
   - `session_bundle.py`, `session_transport.py`, `resume.py`, and `share.py` support packaging, transferring, and resuming work across machines or teammates.
   - This creates a portable session artifact boundary: checkpoints, brainstorm state, and relevant memory can be bundled, scanned, and reloaded.

9. **Team and shared-backend capabilities**
   - `team.py`, `team_audit.py`, `vault.py`, `stacks.py`, and `share.py` support team onboarding, shared memory/backends, stack distribution, and vault-backed sharing.
   - The architecture is explicitly multi-project and project-scoped when using shared storage, so shared services must be drawn with project-key partitioning.

10. **Editor and agent integrations**
   - `editors/vscode/` is a separate VS Code extension surface, and `mcp_server.py` plus `adapters/mcp.py` expose Model Context Protocol integration.
   - The repo also has plugin metadata under `.claude-plugin/` and shell/Python hooks under `hooks/`, showing multiple integration paths into external agent runtimes.

11. **Profiles, manifests, and command surfaces**
   - `manifest.py`, `profiles.py`, `config.py`, `schema.py`, `stacks/`, and `templates/` define the configurable command/runtime surface and packaged command templates.
   - Profiles control which layers are active: minimal, standard, or full, with optional backends and tools degrading safely when unavailable.

12. **Operational and supply-chain boundary**
   - `.github/workflows/`, release assets, packaging files, and scripts show a strong release/CI layer: reproducible builds, SBOM/provenance, security checks, docs publication, and cross-platform validation.
   - The project is local-first and telemetry-free by design; external services are optional and only present when explicitly configured.

13. **Testing strategy mirrors the architecture**
   - Tests cover CLI wiring, engine phases, governance, memory, knowledge, sessions, MCP, VS Code integration, platform support, and release behavior.
   - The test layout indicates the repo is organized around subsystem contracts and end-to-end pipeline behavior, which is useful for diagramming boundaries and data flow confidence.

Main entry points: [`src/mokata/govern`](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/govern) (Governance), [`src/mokata/pipeline.py`](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/pipeline.py) (Pipeline), [`src/mokata/engine`](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/engine) (Engine), [`src/mokata/execmode`](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/execmode) (Exec modes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core engine"]
  node_cli["CLI<br/>entrypoint<br/>[cli.py]"]
  node_main["Module main<br/>entrypoint<br/>[__main__.py]"]
  node_pipeline["Pipeline<br/>orchestrator<br/>[pipeline.py]"]
  node_engine{{"Engine<br/>phase gates"}}
  node_execmode{{"Exec modes<br/>routing strategy"}}
  node_govern{{"Governance<br/>control plane"}}
  node_knowledge{{"Knowledge<br/>read layer"}}
  node_profiles["Profiles<br/>config surface<br/>[profiles.py]"]
  node_manifest["Manifest<br/>schema config<br/>[manifest.py]"]
end

subgraph group_surfaces["Surfaces"]
  node_mcp["MCP server<br/>integration server<br/>[mcp_server.py]"]
  node_adapters{{"Adapters<br/>interop layer"}}
  node_hooks["Hooks<br/>guard scripts"]
  node_vscode["VS Code<br/>editor extension"]
  node_templates["Templates<br/>command pack"]
end

subgraph group_state["State and sharing"]
  node_memory[("Memory<br/>durable store")]
  node_session["Sessions<br/>portable artifact<br/>[session_bundle.py]"]
  node_team["Team<br/>shared coordination<br/>[team.py]"]
  node_share["Share<br/>distribution<br/>[share.py]"]
end

subgraph group_distribution["Packaging"]
  node_docs["Docs<br/>documentation"]
  node_ci["CI & release<br/>supply chain<br/>[ci.yml]"]
end

node_cli -->|"runs"| node_pipeline
node_main -->|"dispatches"| node_cli
node_pipeline -->|"gates"| node_engine
node_pipeline -->|"selects"| node_execmode
node_engine -->|"requests context"| node_knowledge
node_engine -->|"enforces"| node_govern
node_execmode -->|"routes context"| node_knowledge
node_execmode -->|"reads/writes"| node_memory
node_govern -->|"records"| node_memory
node_govern -->|"protects"| node_session
node_knowledge -->|"augments"| node_memory
node_profiles -->|"configures"| node_manifest
node_manifest -->|"renders"| node_templates
node_mcp -->|"exposes"| node_adapters
node_hooks -->|"guarded by"| node_govern
node_vscode -->|"connects"| node_mcp
node_session -->|"bundles"| node_share
node_share -->|"enables"| node_team
node_docs -.->|"documents"| node_templates
node_ci -->|"validates"| node_cli
node_ci -.->|"checks"| node_vscode

click node_cli "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/cli.py"
click node_main "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/__main__.py"
click node_pipeline "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/pipeline.py"
click node_engine "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/engine"
click node_execmode "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/execmode"
click node_govern "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/govern"
click node_knowledge "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/knowledge"
click node_memory "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/memory"
click node_profiles "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/profiles.py"
click node_manifest "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/manifest.py"
click node_mcp "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/mcp_server.py"
click node_adapters "https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/adapters"
click node_hooks "https://github.com/jasgujral/mokata-oss/tree/main/hooks"
click node_vscode "https://github.com/jasgujral/mokata-oss/tree/main/editors/vscode"
click node_templates "https://github.com/jasgujral/mokata-oss/tree/main/templates"
click node_session "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/session_bundle.py"
click node_team "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/team.py"
click node_share "https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/share.py"
click node_docs "https://github.com/jasgujral/mokata-oss/tree/main/docs"
click node_ci "https://github.com/jasgujral/mokata-oss/blob/main/.github/workflows/ci.yml"

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_cli,node_main,node_pipeline,node_engine,node_execmode,node_govern,node_knowledge,node_profiles,node_manifest toneBlue
class node_mcp,node_adapters,node_hooks,node_vscode,node_templates toneAmber
class node_memory,node_session,node_team,node_share toneMint
class node_docs,node_ci toneRose
```

## Components

### Core engine

Deterministic orchestration, governance, knowledge, memory, and execution modes.

- [CLI](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/cli.py): entrypoint · Main command entry and top-level wiring. · `src/mokata/cli.py`
- [Module main](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/__main__.py): entrypoint · Python module execution entrypoint. · `src/mokata/__main__.py`
- [Pipeline](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/pipeline.py): orchestrator · Spec-driven run pipeline and phase coordination. · `src/mokata/pipeline.py`
- [Engine](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/engine): phase gates · Phase, completeness, compliance, premortem, preview, and ship gates. · `src/mokata/engine`
- [Exec modes](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/execmode): routing strategy · Sequential and parallel execution strategies for subagent orchestration. · `src/mokata/execmode`
- [Governance](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/govern): control plane · Rules, budgets, hooks, trust, ledger, revert, and gate enforcement. · `src/mokata/govern`
- [Knowledge](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/knowledge): read layer · Codebase awareness and context lookup with pluggable backends. · `src/mokata/knowledge`
- [Profiles](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/profiles.py): config surface · Activation profiles for minimal, standard, and full runtime sets. · `src/mokata/profiles.py`
- [Manifest](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/manifest.py): schema config · Packaged command/runtime manifest definitions. · `src/mokata/manifest.py`

### Surfaces

CLI, MCP, editor, hooks, and command templates exposed to users and agents.

- [MCP server](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/mcp_server.py): integration server · Model Context Protocol server surface. · `src/mokata/mcp_server.py`
- [Adapters](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/adapters): interop layer · Contract and MCP adapter wiring for external runtimes. · `src/mokata/adapters`
- [Hooks](https://github.com/jasgujral/mokata-oss/tree/main/hooks): guard scripts · Launch and secret-guard hook entrypoints. · `hooks`
- [VS Code](https://github.com/jasgujral/mokata-oss/tree/main/editors/vscode): editor extension · Separate editor extension surface for chat and MCP integration. · `editors/vscode`
- [Templates](https://github.com/jasgujral/mokata-oss/tree/main/templates): command pack · Reusable slash-command and skill templates. · `templates`

### State and sharing

Portable session artifacts, shared team storage, and vault-backed coordination.

- [Memory](https://github.com/jasgujral/mokata-oss/tree/main/src/mokata/memory): durable store · Local-first episodic, consolidated, and vector memory. · `src/mokata/memory`
- [Sessions](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/session_bundle.py): portable artifact · Bundle, transport, resume, and sharing boundary for portable work state. · `src/mokata/session_bundle.py`
- [Team](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/team.py): shared coordination · Shared-backend onboarding, audit, stacks, and vault coordination. · `src/mokata/team.py`
- [Share](https://github.com/jasgujral/mokata-oss/blob/main/src/mokata/share.py): distribution · Portable sharing and project-scoped distribution of state. · `src/mokata/share.py`

### Packaging

Docs, plugin metadata, release assets, and CI supply-chain plumbing.

- [Docs](https://github.com/jasgujral/mokata-oss/tree/main/docs): documentation · Concepts, how-tos, reference docs, and tutorials. · `docs`
- [CI & release](https://github.com/jasgujral/mokata-oss/blob/main/.github/workflows/ci.yml): supply chain · Workflows, packaging, and reproducible release tooling. · `.github/workflows/ci.yml`

## Connections

- CLI → Pipeline: runs · CLI commands drive the deterministic product pipeline.
- Module main → CLI: dispatches · Module execution delegates to CLI wiring.
- Pipeline → Engine: gates · Pipeline uses engine phase gates before code change execution.
- Pipeline → Exec modes: selects · Pipeline chooses sequential or parallel execution strategy.
- Engine → Knowledge: requests context · Gates and phases consult codebase awareness for grounding.
- Engine → Governance: enforces · Governance mediates writes, trust, budgets, and audit.
- Exec modes → Knowledge: routes context · Execution modes use knowledge-backed routing and decomposition.
- Exec modes → Memory: reads/writes · Subagent execution can persist and retrieve state from memory.
- Governance → Memory: records · Governance persists decisions, lifecycle events, and durable traces.
- Governance → Sessions: protects · Session resume and portable artifacts pass through safety controls.
- Knowledge → Memory: augments · Knowledge lookup is informed by remembered context when available.
- Profiles → Manifest: configures · Profiles shape which command and runtime surfaces are active.
- Manifest → Templates: renders · Manifested command surfaces are packaged as templates.
- MCP server → Adapters: exposes · MCP server uses adapter contracts for external tool integration.
- Hooks → Governance: guarded by · Hook scripts trigger governed lifecycle and secret checks.
- VS Code → MCP server: connects · Editor extension talks through MCP integration paths.
- Sessions → Share: bundles · Portable sessions are packaged for transfer and resume.
- Share → Team: enables · Shared distribution supports team-scoped collaboration and backends.
- Docs → Templates: documents · Docs explain the command and skill template surface.
- CI & release → CLI: validates · CI and release workflows validate CLI and packaging behavior.
- CI & release → VS Code: checks · Supply-chain and release checks cover editor extension builds.
