# roopesh-kosuri/code-os architecture

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

- Interactive diagram: https://gitdiagram.com/roopesh-kosuri/code-os
- Repository: https://github.com/roopesh-kosuri/code-os

## Overview

CODE-OS is a local-first Electron AI IDE backed by a FastAPI service. The main user journey is to open a workspace, ask an AI agent to work on it, inspect proposed changes, approve mutations, and review verification results. Its documented capabilities also include multi-agent planning, Duo escalation, terminal execution, security scanning, semantic search, Git, and pipeline generation. The graph combines README-described behavior with relationships visible in sampled excerpts and the source index; several feature links are therefore documented rather than verified call paths.

Main entry points: [`backend/app/features/ai/team/team_routes.py`](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/team/team_routes.py) (Team workflow API), [`src/App.tsx`](https://github.com/roopesh-kosuri/code-os/blob/main/src/App.tsx) (Application shell), [`backend/app/features/ai/chat_harness.py`](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/chat_harness.py) (Rony chat harness), [`src/features/ai/console/TeamConsole.tsx`](https://github.com/roopesh-kosuri/code-os/blob/main/src/features/ai/console/TeamConsole.tsx) (Agent Console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["Application shell<br/>[App.tsx]"]
  node_shell["IDE workspace<br/>[AppShell.tsx]"]
  node_stores["AI and workspace state<br/>[aiStore.ts]"]
  node_api["Typed API client<br/>[api.ts]"]
end

subgraph group_agent["AI agent workflows"]
  node_chat["Rony chat harness<br/>[chat_harness.py]"]
  node_team_ui["Agent Console<br/>[TeamConsole.tsx]"]
  node_team_routes["Team workflow API<br/>[team_routes.py]"]
  node_dag["DAG executor<br/>[dag_engine.py]"]
  node_job["Job state<br/>[job_service.py]"]
  node_mutation["Guarded mutations"]
  node_staging["Change review"]
end

subgraph group_workspace["Workspace tools"]
  node_workspace_api["Workspace management<br/>[service.py]"]
  node_terminal["Terminal execution<br/>[service.py]"]
  node_security["Code security scanner<br/>[scanner_service.py]"]
  node_rag["Semantic retrieval"]
  node_indexing["Repository indexing<br/>[service.py]"]
  node_git["Git integration<br/>[service.py]"]
  node_pipeline["CI/CD generator<br/>[yaml_generator.py]"]
end

subgraph group_service["Backend services"]
  node_backend["Backend application<br/>[main.py]"]
end

subgraph group_integrations["External integrations"]
  node_providers["AI providers"]
  node_provider{{"Selected AI provider"}}
end

node_user(("Developer"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_shell
node_shell -->|"presents"| node_team_ui
node_app -->|"initializes"| node_stores
node_stores -->|"requests"| node_api
node_api -->|"sends HTTP"| node_backend
node_backend -->|"mounts routes"| node_workspace_api
node_user -->|"asks for code"| node_chat
node_chat -.->|"proposes guarded edits"| node_mutation
node_mutation -.->|"stages changes"| node_staging
node_user -->|"starts team task"| node_team_ui
node_team_ui -.->|"submits workflow"| node_team_routes
node_team_routes -->|"creates job"| node_job
node_team_routes -->|"orchestrates workflow"| node_dag
node_dag -->|"updates status"| node_job
node_chat -.->|"requests inference"| node_providers
node_team_routes -.->|"runs agents"| node_providers
node_providers -.->|"calls model"| node_provider
node_user -->|"runs commands"| node_terminal
node_user -->|"requests scan"| node_security
node_user -->|"searches code"| node_rag
node_user -.->|"opens repository"| node_indexing
node_user -->|"uses Git"| node_git
node_user -->|"generates pipeline"| node_pipeline

click node_app "https://github.com/roopesh-kosuri/code-os/blob/main/src/App.tsx"
click node_shell "https://github.com/roopesh-kosuri/code-os/blob/main/src/components/layout/AppShell.tsx"
click node_stores "https://github.com/roopesh-kosuri/code-os/blob/main/src/stores/aiStore.ts"
click node_api "https://github.com/roopesh-kosuri/code-os/blob/main/src/lib/api.ts"
click node_backend "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/main.py"
click node_workspace_api "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/workspaces/service.py"
click node_chat "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/chat_harness.py"
click node_team_ui "https://github.com/roopesh-kosuri/code-os/blob/main/src/features/ai/console/TeamConsole.tsx"
click node_team_routes "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/team/team_routes.py"
click node_dag "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/dag_engine.py"
click node_job "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/job_service.py"
click node_mutation "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/harness/mutation_pipeline.py"
click node_staging "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/staging/staging_review_service.py"
click node_providers "https://github.com/roopesh-kosuri/code-os/tree/main/backend/app/features/ai/providers"
click node_terminal "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/terminal/service.py"
click node_security "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/security/scanner_service.py"
click node_rag "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/rag/vector_index_service.py"
click node_indexing "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/indexing/service.py"
click node_git "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/git/service.py"
click node_pipeline "https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/cicd/yaml_generator.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_app,node_shell,node_stores,node_api toneBlue
class node_chat,node_team_ui,node_team_routes,node_dag,node_job,node_mutation,node_staging toneAmber
class node_workspace_api,node_terminal,node_security,node_rag,node_indexing,node_git,node_pipeline toneMint
class node_backend toneRose
class node_providers,node_provider,node_user toneIndigo
```

## Components

### Desktop experience

- [Application shell](https://github.com/roopesh-kosuri/code-os/blob/main/src/App.tsx): `src/App.tsx`
- [IDE workspace](https://github.com/roopesh-kosuri/code-os/blob/main/src/components/layout/AppShell.tsx): `src/components/layout/AppShell.tsx`
- [AI and workspace state](https://github.com/roopesh-kosuri/code-os/blob/main/src/stores/aiStore.ts): `src/stores/aiStore.ts`
- [Typed API client](https://github.com/roopesh-kosuri/code-os/blob/main/src/lib/api.ts): `src/lib/api.ts`

### AI agent workflows

- [Rony chat harness](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/chat_harness.py): `backend/app/features/ai/chat_harness.py`
- [Agent Console](https://github.com/roopesh-kosuri/code-os/blob/main/src/features/ai/console/TeamConsole.tsx): `src/features/ai/console/TeamConsole.tsx`
- [Team workflow API](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/team/team_routes.py): `backend/app/features/ai/team/team_routes.py`
- [DAG executor](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/dag_engine.py): `backend/app/features/ai/dag_engine.py`
- [Job state](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/job_service.py): `backend/app/features/ai/job_service.py`
- [Guarded mutations](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/harness/mutation_pipeline.py): `backend/app/features/ai/harness/mutation_pipeline.py`
- [Change review](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/staging/staging_review_service.py): `backend/app/features/ai/staging/staging_review_service.py`

### Workspace tools

- [Workspace management](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/workspaces/service.py): `backend/app/features/workspaces/service.py`
- [Terminal execution](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/terminal/service.py): `backend/app/features/terminal/service.py`
- [Code security scanner](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/security/scanner_service.py): `backend/app/features/ai/security/scanner_service.py`
- [Semantic retrieval](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/rag/vector_index_service.py): `backend/app/features/ai/rag/vector_index_service.py`
- [Repository indexing](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/indexing/service.py): `backend/app/features/indexing/service.py`
- [Git integration](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/git/service.py): `backend/app/features/git/service.py`
- [CI/CD generator](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/features/ai/cicd/yaml_generator.py): `backend/app/features/ai/cicd/yaml_generator.py`

### Backend services

- [Backend application](https://github.com/roopesh-kosuri/code-os/blob/main/backend/app/main.py): `backend/app/main.py`

### External integrations

- [AI providers](https://github.com/roopesh-kosuri/code-os/tree/main/backend/app/features/ai/providers): `backend/app/features/ai/providers`
- **Selected AI provider**

### Other components

- **Developer**

## Connections

- Developer → Application shell: uses (evidence: `README.md`)
- Application shell → IDE workspace: renders (evidence: `src/App.tsx`)
- IDE workspace → Agent Console: presents (evidence: `src/components/layout/AppShell.tsx`)
- Application shell → AI and workspace state: initializes (evidence: `src/App.tsx`)
- AI and workspace state → Typed API client: requests (evidence: `src/stores/aiStore.ts`)
- Typed API client → Backend application: sends HTTP (evidence: `src/lib/api.ts`)
- Backend application → Workspace management: mounts routes (evidence: `backend/app/main.py`)
- Developer → Rony chat harness: asks for code (evidence: `README.md`)
- Rony chat harness → Guarded mutations: proposes guarded edits
- Guarded mutations → Change review: stages changes (evidence: `backend/app/features/ai/staging/staging_review_service.py`)
- Developer → Agent Console: starts team task (evidence: `README.md`)
- Agent Console → Team workflow API: submits workflow
- Team workflow API → Job state: creates job (evidence: `backend/app/features/ai/team/team_routes.py`)
- Team workflow API → DAG executor: orchestrates workflow (evidence: `backend/app/features/ai/team/team_routes.py`)
- DAG executor → Job state: updates status (evidence: `backend/app/features/ai/dag_engine.py`)
- Rony chat harness → AI providers: requests inference
- Team workflow API → AI providers: runs agents
- AI providers → Selected AI provider: calls model
- Developer → Terminal execution: runs commands (evidence: `README.md`)
- Developer → Code security scanner: requests scan (evidence: `README.md`)
- Developer → Semantic retrieval: searches code (evidence: `README.md`)
- Developer → Repository indexing: opens repository
- Developer → Git integration: uses Git (evidence: `README.md`)
- Developer → CI/CD generator: generates pipeline (evidence: `README.md`)
