# vishwajitvm/omnishell architecture

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

- Interactive diagram: https://gitdiagram.com/vishwajitvm/omnishell
- Repository: https://github.com/vishwajitvm/omnishell

## Overview

OmniShell turns natural-language requests into answers or guarded host workflows, with scheduled and recurring execution as a persistent branch. The README documents the five-stage control plane, agent swarm, human approval, host execution, verification, and scheduled-task/log storage. Source excerpts show the NestJS page controller, backend logging, and host executor behavior, but omit much of backend wiring; internal relationships beyond those excerpts are therefore based on README-described architecture.

Main entry points: [`backend/main.py`](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py) (Agentic backend), [`frontend/src/app.controller.ts`](https://github.com/vishwajitvm/omnishell/blob/master/frontend/src/app.controller.ts) (Web control center), [`backend/local_executor.py`](https://github.com/vishwajitvm/omnishell/blob/master/backend/local_executor.py) (Host execution agent), [`frontend/views`](https://github.com/vishwajitvm/omnishell/tree/master/frontend/views) (Dashboard views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_web_ui["Web control center<br/>[app.controller.ts]"]
  node_views["Dashboard views"]
end

subgraph group_control["Request control"]
  node_backend["Agentic backend<br/>[main.py]"]
  node_intent{{"Intent and planning agents<br/>[main.py]"}}
  node_policy{{"Safety and policy gates<br/>[main.py]"}}
  node_research["Research and knowledge<br/>[main.py]"]
  node_capabilities["Capability routing<br/>[main.py]"]
  node_approval["Human approval<br/>[main.py]"]
  node_answer["Knowledge response<br/>[main.py]"]
end

subgraph group_execution["Execution and scheduling"]
  node_host["Host execution agent<br/>[local_executor.py]"]
  node_native_os["Native OS commands"]
  node_verify["Execution verification<br/>[local_executor.py]"]
  node_scheduler["Scheduled workflows<br/>[main.py]"]
end

subgraph group_state["State and services"]
  node_logs[("Execution logs<br/>[main.py]")]
  node_redis[("Redis cache")]
end

node_user(("User"))

node_user -->|"submits request"| node_web_ui
node_web_ui -->|"renders pages"| node_views
node_web_ui -->|"sends request"| node_backend
node_backend -->|"analyzes intent"| node_intent
node_intent -->|"checks policy"| node_policy
node_policy -->|"routes request"| node_capabilities
node_intent -.->|"supports research"| node_research
node_capabilities -->|"returns knowledge"| node_answer
node_capabilities -->|"requires approval"| node_approval
node_approval -->|"authorizes execution"| node_host
node_host -->|"runs commands"| node_native_os
node_native_os -->|"checks outcome"| node_verify
node_verify -->|"returns result"| node_web_ui
node_capabilities -->|"queues workflow"| node_scheduler
node_backend -->|"writes execution log"| node_logs
node_backend -->|"reads and writes cache"| node_redis

click node_web_ui "https://github.com/vishwajitvm/omnishell/blob/master/frontend/src/app.controller.ts"
click node_views "https://github.com/vishwajitvm/omnishell/tree/master/frontend/views"
click node_backend "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_intent "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_policy "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_research "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_capabilities "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_approval "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_answer "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_host "https://github.com/vishwajitvm/omnishell/blob/master/backend/local_executor.py"
click node_verify "https://github.com/vishwajitvm/omnishell/blob/master/backend/local_executor.py"
click node_scheduler "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py"
click node_logs "https://github.com/vishwajitvm/omnishell/blob/master/backend/main.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_web_ui,node_views,node_user toneBlue
class node_backend,node_intent,node_policy,node_research,node_capabilities,node_approval,node_answer toneAmber
class node_host,node_native_os,node_verify,node_scheduler toneMint
class node_logs,node_redis toneRose
```

## Components

### Frontend

- [Web control center](https://github.com/vishwajitvm/omnishell/blob/master/frontend/src/app.controller.ts): `frontend/src/app.controller.ts`
- [Dashboard views](https://github.com/vishwajitvm/omnishell/tree/master/frontend/views): `frontend/views`

### Request control

- [Agentic backend](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Intent and planning agents](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Safety and policy gates](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Research and knowledge](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Capability routing](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Human approval](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- [Knowledge response](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`

### Execution and scheduling

- [Host execution agent](https://github.com/vishwajitvm/omnishell/blob/master/backend/local_executor.py): `backend/local_executor.py`
- **Native OS commands**
- [Execution verification](https://github.com/vishwajitvm/omnishell/blob/master/backend/local_executor.py): `backend/local_executor.py`
- [Scheduled workflows](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`

### State and services

- [Execution logs](https://github.com/vishwajitvm/omnishell/blob/master/backend/main.py): `backend/main.py`
- **Redis cache**

### Other components

- **User**

## Connections

- User → Web control center: submits request (evidence: `README.md`)
- Web control center → Dashboard views: renders pages (evidence: `frontend/src/app.controller.ts`)
- Web control center → Agentic backend: sends request (evidence: `README.md`)
- Agentic backend → Intent and planning agents: analyzes intent (evidence: `README.md`)
- Intent and planning agents → Safety and policy gates: checks policy (evidence: `README.md`)
- Safety and policy gates → Capability routing: routes request (evidence: `README.md`)
- Intent and planning agents → Research and knowledge: supports research (evidence: `README.md`)
- Capability routing → Knowledge response: returns knowledge (evidence: `README.md`)
- Capability routing → Human approval: requires approval (evidence: `README.md`)
- Human approval → Host execution agent: authorizes execution (evidence: `README.md`)
- Host execution agent → Native OS commands: runs commands (evidence: `README.md`)
- Native OS commands → Execution verification: checks outcome (evidence: `README.md`)
- Execution verification → Web control center: returns result (evidence: `README.md`)
- Capability routing → Scheduled workflows: queues workflow (evidence: `README.md`)
- Agentic backend → Execution logs: writes execution log (evidence: `backend/main.py`)
- Agentic backend → Redis cache: reads and writes cache (evidence: `backend/main.py`)
