# anisharun412/operatingagent architecture

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

- Interactive diagram: https://gitdiagram.com/anisharun412/operatingagent
- Repository: https://github.com/anisharun412/operatingagent

## Overview

#### Purpose and Current Maturity
This monorepo is scaffolded for a desktop autonomous AI operating agent. It will execute multi-step local-machine goals through sandboxed MCP tools and compare two interchangeable orchestration implementations: native Plan-and-Execute/ReAct versus LangGraph. Most runtime packages currently expose only package initializers/placeholders, so the intended architecture is clearer than the implemented application surface.

#### Entry Points and Execution Surfaces
Python services and agents are independently launched from the uv workspace:
- API: intended FastAPI entry point `api.main:app`, although no `main.py` exists yet under `packages/api/src/api/`.
- Native agent module: `packages/agent-native/src/agent_native/__init__.py`.
- LangGraph agent module: `packages/agent-langgraph/src/agent_langgraph/__init__.py`.
- MCP servers run as separate Python modules, e.g. `packages/mcp-servers/file-server/src/file_server/__init__.py`.
The desktop and frontend directories exist but are placeholders: `apps/desktop/__placeholder__.txt`, `apps/frontend/__placeholder__.txt`.

#### Shared Agent Contract Layer
`packages/common` is the architectural seam intended to keep both agent tracks behaviorally comparable and tool-agnostic. It contains shared agent abstractions, interfaces, tool definitions, events, configuration, enums, and exceptions:
- `packages/common/src/common/agent.py`
- `packages/common/src/common/interfaces.py`
- `packages/common/src/common/tools.py`
- `packages/common/src/common/events.py`
Both orchestration implementations should consume these contracts rather than directly coupling to a specific tool process or UI.

#### Parallel Orchestration Tracks
The comparison’s central boundary is between two agent runtimes operating over the same MCP-exposed tool layer:
- Native Plan-and-Execute plus ReAct: `packages/agent-native/src/agent_native/__init__.py`
- LangGraph StateGraph: `packages/agent-langgraph/src/agent_langgraph/__init__.py`
Expected flow is goal input → planning → iterative tool selection/execution → verification → result/events. Deterministic risk classification and verification are MVP requirements, but their concrete implementations are not yet present.

#### MCP Tool Boundary and Sandboxed Execution
Tools are isolated as standalone FastMCP server packages, allowing either agent to invoke identical capabilities through a process/protocol boundary:
- File operations: `packages/mcp-servers/file-server/src/file_server/__init__.py`
- Terminal execution: `packages/mcp-servers/terminal-server/src/terminal_server/__init__.py`
- Git operations: `packages/mcp-servers/git-server/src/git_server/__init__.py`
- Search: `packages/mcp-servers/search-server/src/search_server/__init__.py`
The sandbox wrapper is the intended containment boundary for local execution: `packages/sandbox/src/sandbox/__init__.py`. Docker sandbox images are planned at `infra/sandbox-images/__placeholder__.txt`.

#### API, Desktop, and Observability Boundaries
The intended API package mediates clients and agent execution: `packages/api/src/api/__init__.py`. A Tauri desktop shell and separate React track UIs are described in the README, but this tree has only placeholder app directories, so no client/backend contract exists yet.
Observability is isolated for OpenTelemetry and Langfuse instrumentation:
- `packages/observability/src/observability/__init__.py`
- `infra/docker/langfuse/__placeholder__.txt`

#### Evaluation and Supporting Infrastructure
The evaluation package is intended to benchmark orchestration overhead, latency, reliability, and code volume across the two agent tracks: `packages/evaluation/src/evaluation/__init__.py`. Planned persistent/telemetry infrastructure includes PostgreSQL, Qdrant, and Langfuse:
- `infra/docker/postgres/__placeholder__.txt`
- `infra/docker/qdrant/__placeholder__.txt`
- `infra/docker/langfuse/__placeholder__.txt`
Knowledge and memory MCP servers are Phase 2 extensions, separating semantic memory/RAG from the MVP execution path: `packages/mcp-servers/knowledge-server/src/knowledge_server/__init__.py`, `packages/mcp-servers/memory-server/src/memory_server/__init__.py`.

Main entry points: [`packages/agent-native/src/agent_native/__init__.py`](https://github.com/anisharun412/operatingagent/blob/main/packages/agent-native/src/agent_native/__init__.py) (Native Plan/ReAct agent), [`packages/agent-langgraph/src/agent_langgraph/__init__.py`](https://github.com/anisharun412/operatingagent/blob/main/packages/agent-langgraph/src/agent_langgraph/__init__.py) (LangGraph agent), [`packages/api/src/api/__init__.py`](https://github.com/anisharun412/operatingagent/blob/main/packages/api/src/api/__init__.py) (API service), [`packages/mcp-servers/terminal-server/src/terminal_server/__init__.py`](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/terminal-server/src/terminal_server/__init__.py) (Terminal MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client surfaces"]
  node_desktop["Tauri desktop shell<br/>desktop placeholder"]
  node_frontend["React frontend<br/>web placeholder"]
end

subgraph group_orchestration["Agent orchestration"]
  node_api["API service<br/>FastAPI<br/>[__init__.py]"]
  node_contracts["Shared agent contracts<br/>Python package<br/>[agent.py]"]
  node_native["Native Plan/ReAct agent<br/>Python agent<br/>[__init__.py]"]
  node_langgraph["LangGraph agent<br/>StateGraph agent<br/>[__init__.py]"]
end

subgraph group_mcp["MCP tool boundary"]
  node_file_mcp{{"File MCP server<br/>FastMCP server<br/>[__init__.py]"}}
  node_terminal_mcp{{"Terminal MCP server<br/>FastMCP server<br/>[__init__.py]"}}
  node_git_mcp{{"Git MCP server<br/>FastMCP server<br/>[__init__.py]"}}
  node_search_mcp{{"Search MCP server<br/>FastMCP server<br/>[__init__.py]"}}
  node_knowledge_mcp{{"Knowledge MCP server<br/>Phase 2 MCP server<br/>[__init__.py]"}}
  node_memory_mcp{{"Memory MCP server<br/>Phase 2 MCP server<br/>[__init__.py]"}}
end

subgraph group_platform["Platform and evaluation"]
  node_sandbox["Sandbox wrapper<br/>Python package<br/>[__init__.py]"]
  node_sandbox_images["Sandbox images<br/>Docker placeholder"]
  node_observability["Observability<br/>instrumentation package<br/>[__init__.py]"]
  node_evaluation["Agent evaluation<br/>benchmark package<br/>[__init__.py]"]
  node_postgres[("PostgreSQL<br/>planned database")]
  node_qdrant[("Qdrant<br/>planned vector database")]
  node_langfuse[("Langfuse<br/>planned telemetry service")]
end

node_desktop -.->|"goal requests"| node_api
node_frontend -.->|"goal requests"| node_api
node_api -->|"dispatches goal"| node_native
node_api -->|"dispatches goal"| node_langgraph
node_native -->|"uses contracts"| node_contracts
node_langgraph -->|"uses contracts"| node_contracts
node_native -->|"MCP tools"| node_file_mcp
node_native -->|"MCP tools"| node_terminal_mcp
node_native -->|"MCP tools"| node_git_mcp
node_native -->|"MCP tools"| node_search_mcp
node_langgraph -->|"MCP tools"| node_file_mcp
node_langgraph -->|"MCP tools"| node_terminal_mcp
node_langgraph -->|"MCP tools"| node_git_mcp
node_langgraph -->|"MCP tools"| node_search_mcp
node_terminal_mcp -->|"contained execution"| node_sandbox
node_sandbox -.->|"planned runtime images"| node_sandbox_images
node_native -->|"events and traces"| node_observability
node_langgraph -->|"events and traces"| node_observability
node_observability -.->|"telemetry export"| node_langfuse
node_evaluation -->|"benchmarks"| node_native
node_evaluation -->|"benchmarks"| node_langgraph
node_knowledge_mcp -.->|"planned retrieval store"| node_qdrant
node_memory_mcp -.->|"planned persistence"| node_postgres

click node_desktop "https://github.com/anisharun412/operatingagent/blob/main/apps/desktop/__placeholder__.txt"
click node_frontend "https://github.com/anisharun412/operatingagent/blob/main/apps/frontend/__placeholder__.txt"
click node_api "https://github.com/anisharun412/operatingagent/blob/main/packages/api/src/api/__init__.py"
click node_contracts "https://github.com/anisharun412/operatingagent/blob/main/packages/common/src/common/agent.py"
click node_native "https://github.com/anisharun412/operatingagent/blob/main/packages/agent-native/src/agent_native/__init__.py"
click node_langgraph "https://github.com/anisharun412/operatingagent/blob/main/packages/agent-langgraph/src/agent_langgraph/__init__.py"
click node_file_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/file-server/src/file_server/__init__.py"
click node_terminal_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/terminal-server/src/terminal_server/__init__.py"
click node_git_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/git-server/src/git_server/__init__.py"
click node_search_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/search-server/src/search_server/__init__.py"
click node_knowledge_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/knowledge-server/src/knowledge_server/__init__.py"
click node_memory_mcp "https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/memory-server/src/memory_server/__init__.py"
click node_sandbox "https://github.com/anisharun412/operatingagent/blob/main/packages/sandbox/src/sandbox/__init__.py"
click node_sandbox_images "https://github.com/anisharun412/operatingagent/blob/main/infra/sandbox-images/__placeholder__.txt"
click node_observability "https://github.com/anisharun412/operatingagent/blob/main/packages/observability/src/observability/__init__.py"
click node_evaluation "https://github.com/anisharun412/operatingagent/blob/main/packages/evaluation/src/evaluation/__init__.py"
click node_postgres "https://github.com/anisharun412/operatingagent/blob/main/infra/docker/postgres/__placeholder__.txt"
click node_qdrant "https://github.com/anisharun412/operatingagent/blob/main/infra/docker/qdrant/__placeholder__.txt"
click node_langfuse "https://github.com/anisharun412/operatingagent/blob/main/infra/docker/langfuse/__placeholder__.txt"

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_desktop,node_frontend toneBlue
class node_api,node_contracts,node_native,node_langgraph toneAmber
class node_file_mcp,node_terminal_mcp,node_git_mcp,node_search_mcp,node_knowledge_mcp,node_memory_mcp toneMint
class node_sandbox,node_sandbox_images,node_observability,node_evaluation,node_postgres,node_qdrant,node_langfuse toneRose
```

## Components

### Client surfaces

Placeholder desktop and web shells.

- [Tauri desktop shell](https://github.com/anisharun412/operatingagent/blob/main/apps/desktop/__placeholder__.txt): desktop placeholder · `apps/desktop/__placeholder__.txt`
- [React frontend](https://github.com/anisharun412/operatingagent/blob/main/apps/frontend/__placeholder__.txt): web placeholder · `apps/frontend/__placeholder__.txt`

### Agent orchestration

Interchangeable implementations share one contract layer.

- [API service](https://github.com/anisharun412/operatingagent/blob/main/packages/api/src/api/__init__.py): FastAPI · Intended client-to-agent mediation; the app entry point is not implemented yet. · `packages/api/src/api/__init__.py`
- [Shared agent contracts](https://github.com/anisharun412/operatingagent/blob/main/packages/common/src/common/agent.py): Python package · Tool-agnostic agent interfaces, tools, events, and abstractions. · `packages/common/src/common/agent.py`
- [Native Plan/ReAct agent](https://github.com/anisharun412/operatingagent/blob/main/packages/agent-native/src/agent_native/__init__.py): Python agent · Plan-and-Execute plus ReAct orchestration track. · `packages/agent-native/src/agent_native/__init__.py`
- [LangGraph agent](https://github.com/anisharun412/operatingagent/blob/main/packages/agent-langgraph/src/agent_langgraph/__init__.py): StateGraph agent · LangGraph orchestration track evaluated against the native agent. · `packages/agent-langgraph/src/agent_langgraph/__init__.py`

### MCP tool boundary

Standalone tool servers expose identical capabilities to either agent.

- [File MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/file-server/src/file_server/__init__.py): FastMCP server · `packages/mcp-servers/file-server/src/file_server/__init__.py`
- [Terminal MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/terminal-server/src/terminal_server/__init__.py): FastMCP server · `packages/mcp-servers/terminal-server/src/terminal_server/__init__.py`
- [Git MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/git-server/src/git_server/__init__.py): FastMCP server · `packages/mcp-servers/git-server/src/git_server/__init__.py`
- [Search MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/search-server/src/search_server/__init__.py): FastMCP server · `packages/mcp-servers/search-server/src/search_server/__init__.py`
- [Knowledge MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/knowledge-server/src/knowledge_server/__init__.py): Phase 2 MCP server · Planned semantic knowledge and RAG extension. · `packages/mcp-servers/knowledge-server/src/knowledge_server/__init__.py`
- [Memory MCP server](https://github.com/anisharun412/operatingagent/blob/main/packages/mcp-servers/memory-server/src/memory_server/__init__.py): Phase 2 MCP server · Planned agent memory extension. · `packages/mcp-servers/memory-server/src/memory_server/__init__.py`

### Platform and evaluation

Sandboxing, telemetry, planned storage, and comparison tooling.

- [Sandbox wrapper](https://github.com/anisharun412/operatingagent/blob/main/packages/sandbox/src/sandbox/__init__.py): Python package · Containment boundary for local-machine execution. · `packages/sandbox/src/sandbox/__init__.py`
- [Sandbox images](https://github.com/anisharun412/operatingagent/blob/main/infra/sandbox-images/__placeholder__.txt): Docker placeholder · `infra/sandbox-images/__placeholder__.txt`
- [Observability](https://github.com/anisharun412/operatingagent/blob/main/packages/observability/src/observability/__init__.py): instrumentation package · OpenTelemetry and Langfuse instrumentation boundary. · `packages/observability/src/observability/__init__.py`
- [Agent evaluation](https://github.com/anisharun412/operatingagent/blob/main/packages/evaluation/src/evaluation/__init__.py): benchmark package · Compares overhead, latency, reliability, and code volume. · `packages/evaluation/src/evaluation/__init__.py`
- [PostgreSQL](https://github.com/anisharun412/operatingagent/blob/main/infra/docker/postgres/__placeholder__.txt): planned database · `infra/docker/postgres/__placeholder__.txt`
- [Qdrant](https://github.com/anisharun412/operatingagent/blob/main/infra/docker/qdrant/__placeholder__.txt): planned vector database · `infra/docker/qdrant/__placeholder__.txt`
- [Langfuse](https://github.com/anisharun412/operatingagent/blob/main/infra/docker/langfuse/__placeholder__.txt): planned telemetry service · `infra/docker/langfuse/__placeholder__.txt`

## Connections

- Tauri desktop shell → API service: goal requests
- React frontend → API service: goal requests
- API service → Native Plan/ReAct agent: dispatches goal
- API service → LangGraph agent: dispatches goal
- Native Plan/ReAct agent → Shared agent contracts: uses contracts
- LangGraph agent → Shared agent contracts: uses contracts
- Native Plan/ReAct agent → File MCP server: MCP tools
- Native Plan/ReAct agent → Terminal MCP server: MCP tools
- Native Plan/ReAct agent → Git MCP server: MCP tools
- Native Plan/ReAct agent → Search MCP server: MCP tools
- LangGraph agent → File MCP server: MCP tools
- LangGraph agent → Terminal MCP server: MCP tools
- LangGraph agent → Git MCP server: MCP tools
- LangGraph agent → Search MCP server: MCP tools
- Terminal MCP server → Sandbox wrapper: contained execution
- Sandbox wrapper → Sandbox images: planned runtime images
- Native Plan/ReAct agent → Observability: events and traces
- LangGraph agent → Observability: events and traces
- Observability → Langfuse: telemetry export
- Agent evaluation → Native Plan/ReAct agent: benchmarks
- Agent evaluation → LangGraph agent: benchmarks
- Knowledge MCP server → Qdrant: planned retrieval store
- Memory MCP server → PostgreSQL: planned persistence