# pavan1290/sigma architecture

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

- Interactive diagram: https://gitdiagram.com/pavan1290/sigma
- Repository: https://github.com/pavan1290/sigma

## Overview

#### Purpose and Runtime Shape
SIGMA-OS is a local desktop-oriented intelligent-agent system: a React/Vite UI talks to a Python FastAPI service that routes natural-language tasks to system, email, and browser automation agents. An Electron main process packages/launches the application for Windows. Primary launch paths are `start.sh`, `backend/app.py`, `src/main.jsx`, and `main.cjs`.

#### Client and Desktop Shell
The interactive client is a React application centered on the assistant/chat experience, model selection, API-key management, formatted result display, and system status. It communicates with FastAPI through REST plus a WebSocket channel. Electron is the desktop boundary; shipped Windows artifacts embed the Python backend under `release-fixed/win-unpacked/resources/app.asar.unpacked/backend/app.py`.
- `src/main.jsx`
- `src/App.jsx`
- `src/components/IntelligentAssistant.jsx`
- `main.cjs`

#### API Gateway and Real-Time Control Plane
FastAPI is the application-facing backend, exposing health, model, API-key, command, and WebSocket endpoints (documented as port 5000 and `/ws`). It accepts UI/API commands, applies model and agent routing, and returns or streams execution updates. This is the key boundary between untrusted user requests and privileged automation.
- `backend/app.py`
- `backend/models.py`
- `backend/db.py`

#### Agent Routing and Execution
The agent core coordinates task interpretation and dispatch to capability-specific agents. `SystemAgent` handles local shell/files/processes/screenshots; `EmailAgent` handles Gmail operations; `WebAgent` drives browser automation. Their results are normalized for UI/MCP consumers rather than exposing raw execution details directly.
- `intelligent_agents/agent_core.py`
- `intelligent_agents/system_agent.py`
- `intelligent_agents/email_agent.py`
- `intelligent_agents/web_agent.py`

#### Model and Output Layer
Model management abstracts interchangeable inference providers and separates “thinking” from execution model selection. Provider keys come from environment/UI-managed configuration; supported integrations include Groq, Google Gemini, OpenAI, Anthropic, and local Ollama. Output formatting converts command and automation results into structured, display-oriented responses.
- `intelligent_agents/model_manager.py`
- `intelligent_agents/output_formatter.py`
- `.env.example`

#### MCP Integration Boundary
The MCP server publishes system, email, web, analysis, and model capabilities as standard callable tools for external LLM clients such as Claude. It is an alternate ingress/control path alongside FastAPI, delegating tool calls into the same agent capabilities.
- `intelligent_agents/mcp_server.py`
- `intelligent_agents/__init__.py`

#### Automation Workflows and Resilience
A separate backend automation subsystem supports orchestrated workflows, scheduled tasks, monitoring-triggered rules, retries, and recovery. Example JSON definitions indicate workflows/rules are data-driven inputs to this subsystem, distinct from single interactive agent commands.
- `backend/automation/orchestrator.py`
- `backend/automation/workflow_engine.py`
- `backend/automation/rules_engine.py`
- `backend/automation/task_scheduler.py`
- `backend/automation/error_recovery.py`

#### External Dependencies and Privilege Boundaries
Python 3.10+ hosts FastAPI and agents; Node.js runs Vite/React and Electron. Browser automation requires Playwright. System automation uses host-level facilities (shell, filesystem, process inspection, screenshots), while email crosses Gmail APIs and models cross external AI-provider APIs. These integrations make credential handling and command/tool authorization architecturally sensitive.

Main entry points: [`backend/app.py`](https://github.com/pavan1290/sigma/blob/main/backend/app.py) (FastAPI Gateway), [`intelligent_agents/agent_core.py`](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/agent_core.py) (Agent Core), [`backend/automation/orchestrator.py`](https://github.com/pavan1290/sigma/blob/main/backend/automation/orchestrator.py) (Automation Orchestrator), [`intelligent_agents/output_formatter.py`](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/output_formatter.py) (Output Formatter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Client"]
  node_launcher["Launch Script<br/>shell launcher<br/>[start.sh]"]
  node_electron["Electron Main<br/>desktop shell<br/>[main.cjs]"]
  node_react_entry["React Entry<br/>Vite client<br/>[main.jsx]"]
  node_assistant_ui["Assistant UI<br/>React chat UI"]
end

subgraph group_api["API &amp; Control Plane"]
  node_fastapi["FastAPI Gateway<br/>REST and WebSocket API<br/>[app.py]"]
  node_api_models["API Models<br/>request models<br/>[models.py]"]
  node_data_store[("Backend Database<br/>application persistence<br/>[db.py]")]
  node_mcp_server["MCP Server<br/>tool server<br/>[mcp_server.py]"]
end

subgraph group_agents["Agent Execution"]
  node_agent_core["Agent Core<br/>task router<br/>[agent_core.py]"]
  node_system_agent["System Agent<br/>host automation<br/>[system_agent.py]"]
  node_email_agent["Email Agent<br/>Gmail automation<br/>[email_agent.py]"]
  node_web_agent["Web Agent<br/>browser automation<br/>[web_agent.py]"]
  node_model_manager["Model Manager<br/>inference provider router<br/>[model_manager.py]"]
  node_output_formatter["Output Formatter<br/>response formatter"]
end

subgraph group_automation["Workflow Automation"]
  node_orchestrator["Automation Orchestrator<br/>workflow coordinator<br/>[orchestrator.py]"]
  node_workflow_engine["Workflow Engine<br/>data-driven workflows<br/>[workflow_engine.py]"]
  node_rules_engine["Rules Engine<br/>monitoring rules<br/>[rules_engine.py]"]
  node_task_scheduler["Task Scheduler<br/>scheduled execution<br/>[task_scheduler.py]"]
  node_error_recovery["Error Recovery<br/>retry and recovery<br/>[error_recovery.py]"]
end

subgraph group_integrations["External Boundaries"]
  node_host_system{{"Host System<br/>shell, files, processes, screenshots"}}
  node_gmail{{"Gmail API<br/>email service"}}
  node_browser{{"Playwright Browser<br/>browser runtime"}}
  node_ai_providers{{"AI Providers<br/>[.env.example]"}}
end

node_launcher -->|"starts"| node_fastapi
node_electron -->|"hosts"| node_react_entry
node_react_entry -->|"renders"| node_assistant_ui
node_assistant_ui -->|"REST and WebSocket"| node_fastapi
node_fastapi -->|"validates"| node_api_models
node_fastapi -->|"reads and writes"| node_data_store
node_fastapi -->|"routes commands"| node_agent_core
node_fastapi -->|"starts automation"| node_orchestrator
node_mcp_server -->|"delegates tools"| node_agent_core
node_agent_core -->|"selects models"| node_model_manager
node_agent_core -->|"dispatches"| node_system_agent
node_agent_core -->|"dispatches"| node_email_agent
node_agent_core -->|"dispatches"| node_web_agent
node_system_agent -->|"automates"| node_host_system
node_email_agent -->|"calls"| node_gmail
node_web_agent -->|"drives"| node_browser
node_model_manager -->|"invokes inference"| node_ai_providers
node_system_agent -->|"results"| node_output_formatter
node_email_agent -->|"results"| node_output_formatter
node_web_agent -->|"results"| node_output_formatter
node_output_formatter -->|"structured response"| node_fastapi
node_orchestrator -->|"runs workflows"| node_workflow_engine
node_orchestrator -->|"evaluates rules"| node_rules_engine
node_orchestrator -->|"schedules tasks"| node_task_scheduler
node_orchestrator -->|"recovers failures"| node_error_recovery
node_workflow_engine -->|"executes tasks"| node_agent_core
node_rules_engine -->|"triggers workflows"| node_orchestrator
node_task_scheduler -->|"triggers runs"| node_orchestrator

click node_launcher "https://github.com/pavan1290/sigma/blob/main/start.sh"
click node_electron "https://github.com/pavan1290/sigma/blob/main/main.cjs"
click node_react_entry "https://github.com/pavan1290/sigma/blob/main/src/main.jsx"
click node_assistant_ui "https://github.com/pavan1290/sigma/blob/main/src/components/IntelligentAssistant.jsx"
click node_fastapi "https://github.com/pavan1290/sigma/blob/main/backend/app.py"
click node_api_models "https://github.com/pavan1290/sigma/blob/main/backend/models.py"
click node_data_store "https://github.com/pavan1290/sigma/blob/main/backend/db.py"
click node_agent_core "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/agent_core.py"
click node_system_agent "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/system_agent.py"
click node_email_agent "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/email_agent.py"
click node_web_agent "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/web_agent.py"
click node_model_manager "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/model_manager.py"
click node_output_formatter "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/output_formatter.py"
click node_mcp_server "https://github.com/pavan1290/sigma/blob/main/intelligent_agents/mcp_server.py"
click node_orchestrator "https://github.com/pavan1290/sigma/blob/main/backend/automation/orchestrator.py"
click node_workflow_engine "https://github.com/pavan1290/sigma/blob/main/backend/automation/workflow_engine.py"
click node_rules_engine "https://github.com/pavan1290/sigma/blob/main/backend/automation/rules_engine.py"
click node_task_scheduler "https://github.com/pavan1290/sigma/blob/main/backend/automation/task_scheduler.py"
click node_error_recovery "https://github.com/pavan1290/sigma/blob/main/backend/automation/error_recovery.py"
click node_ai_providers "https://github.com/pavan1290/sigma/blob/main/.env.example"

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_launcher,node_electron,node_react_entry,node_assistant_ui toneBlue
class node_fastapi,node_api_models,node_data_store,node_mcp_server toneAmber
class node_agent_core,node_system_agent,node_email_agent,node_web_agent,node_model_manager,node_output_formatter toneMint
class node_orchestrator,node_workflow_engine,node_rules_engine,node_task_scheduler,node_error_recovery toneRose
class node_host_system,node_gmail,node_browser,node_ai_providers toneIndigo
```

## Components

### Desktop Client

- [Launch Script](https://github.com/pavan1290/sigma/blob/main/start.sh): shell launcher · `start.sh`
- [Electron Main](https://github.com/pavan1290/sigma/blob/main/main.cjs): desktop shell · Packages and launches the Windows desktop application. · `main.cjs`
- [React Entry](https://github.com/pavan1290/sigma/blob/main/src/main.jsx): Vite client · `src/main.jsx`
- [Assistant UI](https://github.com/pavan1290/sigma/blob/main/src/components/IntelligentAssistant.jsx): React chat UI · Chat, model selection, API-key management, results, and status. · `src/components/IntelligentAssistant.jsx`

### API & Control Plane

- [FastAPI Gateway](https://github.com/pavan1290/sigma/blob/main/backend/app.py): REST and WebSocket API · Privileged boundary for UI and API commands. · `backend/app.py`
- [API Models](https://github.com/pavan1290/sigma/blob/main/backend/models.py): request models · `backend/models.py`
- [Backend Database](https://github.com/pavan1290/sigma/blob/main/backend/db.py): application persistence · `backend/db.py`
- [MCP Server](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/mcp_server.py): tool server · Alternate ingress for external LLM clients. · `intelligent_agents/mcp_server.py`

### Agent Execution

- [Agent Core](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/agent_core.py): task router · Interprets tasks and dispatches capability agents. · `intelligent_agents/agent_core.py`
- [System Agent](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/system_agent.py): host automation · `intelligent_agents/system_agent.py`
- [Email Agent](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/email_agent.py): Gmail automation · `intelligent_agents/email_agent.py`
- [Web Agent](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/web_agent.py): browser automation · `intelligent_agents/web_agent.py`
- [Model Manager](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/model_manager.py): inference provider router · Separates thinking and execution model selection. · `intelligent_agents/model_manager.py`
- [Output Formatter](https://github.com/pavan1290/sigma/blob/main/intelligent_agents/output_formatter.py): response formatter · Normalizes execution results for UI and MCP consumers. · `intelligent_agents/output_formatter.py`

### Workflow Automation

- [Automation Orchestrator](https://github.com/pavan1290/sigma/blob/main/backend/automation/orchestrator.py): workflow coordinator · `backend/automation/orchestrator.py`
- [Workflow Engine](https://github.com/pavan1290/sigma/blob/main/backend/automation/workflow_engine.py): data-driven workflows · `backend/automation/workflow_engine.py`
- [Rules Engine](https://github.com/pavan1290/sigma/blob/main/backend/automation/rules_engine.py): monitoring rules · `backend/automation/rules_engine.py`
- [Task Scheduler](https://github.com/pavan1290/sigma/blob/main/backend/automation/task_scheduler.py): scheduled execution · `backend/automation/task_scheduler.py`
- [Error Recovery](https://github.com/pavan1290/sigma/blob/main/backend/automation/error_recovery.py): retry and recovery · `backend/automation/error_recovery.py`

### External Boundaries

- **Host System**: shell, files, processes, screenshots · Privileged local-system boundary.
- **Gmail API**: email service
- **Playwright Browser**: browser runtime
- [AI Providers](https://github.com/pavan1290/sigma/blob/main/.env.example): Groq, Gemini, OpenAI, Anthropic, Ollama · Provider credentials are configured through environment or UI-managed settings. · `.env.example`

## Connections

- Launch Script → FastAPI Gateway: starts
- Electron Main → React Entry: hosts
- React Entry → Assistant UI: renders
- Assistant UI → FastAPI Gateway: REST and WebSocket
- FastAPI Gateway → API Models: validates
- FastAPI Gateway → Backend Database: reads and writes
- FastAPI Gateway → Agent Core: routes commands
- FastAPI Gateway → Automation Orchestrator: starts automation
- MCP Server → Agent Core: delegates tools
- Agent Core → Model Manager: selects models
- Agent Core → System Agent: dispatches
- Agent Core → Email Agent: dispatches
- Agent Core → Web Agent: dispatches
- System Agent → Host System: automates
- Email Agent → Gmail API: calls
- Web Agent → Playwright Browser: drives
- Model Manager → AI Providers: invokes inference
- System Agent → Output Formatter: results
- Email Agent → Output Formatter: results
- Web Agent → Output Formatter: results
- Output Formatter → FastAPI Gateway: structured response
- Automation Orchestrator → Workflow Engine: runs workflows
- Automation Orchestrator → Rules Engine: evaluates rules
- Automation Orchestrator → Task Scheduler: schedules tasks
- Automation Orchestrator → Error Recovery: recovers failures
- Workflow Engine → Agent Core: executes tasks
- Rules Engine → Automation Orchestrator: triggers workflows
- Task Scheduler → Automation Orchestrator: triggers runs