# alinejenita/codepilot architecture

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

- Interactive diagram: https://gitdiagram.com/alinejenita/codepilot
- Repository: https://github.com/alinejenita/codepilot

## Overview

CodePilot is a local Ollama-powered coding assistant with a web chat and terminal CLI. Users submit prompts, the backend runs a bounded agent turn with workspace tools and optional skills, then returns an answer and tool trace for display. Users can also inspect workspace files in the web UI. The README documents opt-in edits and pytest execution. The agent loop and some UI/CLI source were not sampled, so those documented capabilities are shown without speculative internal call paths.

Main entry points: [`frontend/src/App.jsx`](https://github.com/alinejenita/codepilot/blob/main/frontend/src/App.jsx) (Web Application), [`backend/app/agent/loop.py`](https://github.com/alinejenita/codepilot/blob/main/backend/app/agent/loop.py) (Agent Loop), [`backend/app/api/routes_chat.py`](https://github.com/alinejenita/codepilot/blob/main/backend/app/api/routes_chat.py) (Chat and Workspace API), [`cli/main.py`](https://github.com/alinejenita/codepilot/blob/main/cli/main.py) (Terminal CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_web["Web Application<br/>[App.jsx]"]
  node_session_ui["Session Controls<br/>[Sidebar.jsx]"]
  node_header["Model Controls<br/>[Header.jsx]"]
  node_message["Chat and Trace<br/>[ChatMessage.jsx]"]
  node_workspace_ui["Workspace Preview<br/>[WorkspacePanel.jsx]"]
  node_api_client["Web API Client<br/>[api.js]"]
  node_cli["Terminal CLI<br/>[main.py]"]
  node_trace_panel["Tool Activity Panel"]
end

subgraph group_backend["API and Agent"]
  node_api["FastAPI App<br/>[main.py]"]
  node_chat_api["Chat and Workspace API<br/>[routes_chat.py]"]
  node_health_api["Health API<br/>[routes_health.py]"]
  node_agent["Agent Loop<br/>[loop.py]"]
  node_skills["Skill Loader<br/>[skills.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
end

subgraph group_workspace["Workspace Tools"]
  node_file_tools["Workspace File Tools<br/>[file_tools.py]"]
  node_workspace_data[("Workspace Files")]
  node_skill_files["Bundled Skills"]
end

subgraph group_local["Local Runtime"]
  node_ollama["Ollama"]
end

node_user(("User"))

node_user -->|"submits prompt"| node_web
node_user -->|"enters task"| node_cli
node_web -->|"manages sessions"| node_session_ui
node_web -->|"renders controls"| node_header
node_web -->|"renders replies"| node_message
node_web -->|"renders preview"| node_workspace_ui
node_web -->|"requests chat"| node_api_client
node_workspace_ui -->|"requests files"| node_api_client
node_api_client -->|"posts chat"| node_chat_api
node_api_client -->|"fetches status"| node_health_api
node_api -->|"registers routes"| node_chat_api
node_api -->|"registers routes"| node_health_api
node_chat_api -->|"runs agent turn"| node_agent
node_chat_api -->|"lists and reads"| node_file_tools
node_chat_api -->|"uses settings"| node_config
node_health_api -->|"reads settings"| node_config
node_health_api -->|"checks models"| node_ollama
node_agent -->|"requests inference"| node_ollama
node_agent -->|"uses workspace tools"| node_file_tools
node_agent -->|"loads relevant skills"| node_skills
node_skills -->|"discovers and reads"| node_skill_files
node_file_tools -->|"reads and writes"| node_workspace_data
node_cli -->|"runs agent turns"| node_agent
node_cli -->|"uses settings"| node_config
node_cli -->|"lists skills"| node_skills
node_message -->|"renders tool traces"| node_trace_panel
node_agent -.->|"may run pytest"| node_file_tools

click node_web "https://github.com/alinejenita/codepilot/blob/main/frontend/src/App.jsx"
click node_session_ui "https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/Sidebar.jsx"
click node_header "https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/Header.jsx"
click node_message "https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/ChatMessage.jsx"
click node_workspace_ui "https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/WorkspacePanel.jsx"
click node_api_client "https://github.com/alinejenita/codepilot/blob/main/frontend/src/services/api.js"
click node_cli "https://github.com/alinejenita/codepilot/blob/main/cli/main.py"
click node_api "https://github.com/alinejenita/codepilot/blob/main/backend/app/main.py"
click node_chat_api "https://github.com/alinejenita/codepilot/blob/main/backend/app/api/routes_chat.py"
click node_health_api "https://github.com/alinejenita/codepilot/blob/main/backend/app/api/routes_health.py"
click node_agent "https://github.com/alinejenita/codepilot/blob/main/backend/app/agent/loop.py"
click node_skills "https://github.com/alinejenita/codepilot/blob/main/backend/app/agent/skills.py"
click node_config "https://github.com/alinejenita/codepilot/blob/main/backend/app/config.py"
click node_file_tools "https://github.com/alinejenita/codepilot/blob/main/backend/app/tools/file_tools.py"
click node_workspace_data "https://github.com/alinejenita/codepilot/tree/main/workspace"
click node_skill_files "https://github.com/alinejenita/codepilot/tree/main/skills"
click node_trace_panel "https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/ToolActivityPanel.jsx"

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,node_session_ui,node_header,node_message,node_workspace_ui,node_api_client,node_cli,node_trace_panel,node_user toneBlue
class node_api,node_chat_api,node_health_api,node_agent,node_skills,node_config toneAmber
class node_file_tools,node_workspace_data,node_skill_files toneMint
class node_ollama toneRose
```

## Components

### User Interfaces

- [Web Application](https://github.com/alinejenita/codepilot/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Session Controls](https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/Sidebar.jsx): `frontend/src/components/Sidebar.jsx`
- [Model Controls](https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/Header.jsx): `frontend/src/components/Header.jsx`
- [Chat and Trace](https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/ChatMessage.jsx): `frontend/src/components/ChatMessage.jsx`
- [Workspace Preview](https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/WorkspacePanel.jsx): `frontend/src/components/WorkspacePanel.jsx`
- [Web API Client](https://github.com/alinejenita/codepilot/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`
- [Terminal CLI](https://github.com/alinejenita/codepilot/blob/main/cli/main.py): `cli/main.py`
- [Tool Activity Panel](https://github.com/alinejenita/codepilot/blob/main/frontend/src/components/ToolActivityPanel.jsx): `frontend/src/components/ToolActivityPanel.jsx`

### API and Agent

- [FastAPI App](https://github.com/alinejenita/codepilot/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat and Workspace API](https://github.com/alinejenita/codepilot/blob/main/backend/app/api/routes_chat.py): `backend/app/api/routes_chat.py`
- [Health API](https://github.com/alinejenita/codepilot/blob/main/backend/app/api/routes_health.py): `backend/app/api/routes_health.py`
- [Agent Loop](https://github.com/alinejenita/codepilot/blob/main/backend/app/agent/loop.py): `backend/app/agent/loop.py`
- [Skill Loader](https://github.com/alinejenita/codepilot/blob/main/backend/app/agent/skills.py): `backend/app/agent/skills.py`
- [Runtime Settings](https://github.com/alinejenita/codepilot/blob/main/backend/app/config.py): `backend/app/config.py`

### Workspace Tools

- [Workspace File Tools](https://github.com/alinejenita/codepilot/blob/main/backend/app/tools/file_tools.py): `backend/app/tools/file_tools.py`
- [Workspace Files](https://github.com/alinejenita/codepilot/tree/main/workspace): `workspace`
- [Bundled Skills](https://github.com/alinejenita/codepilot/tree/main/skills): `skills`

### Local Runtime

- **Ollama**

### Other components

- **User**

## Connections

- User → Web Application: submits prompt (evidence: `README.md`)
- User → Terminal CLI: enters task (evidence: `README.md`)
- Web Application → Session Controls: manages sessions (evidence: `frontend/src/App.jsx`)
- Web Application → Model Controls: renders controls (evidence: `frontend/src/App.jsx`)
- Web Application → Chat and Trace: renders replies (evidence: `frontend/src/App.jsx`)
- Web Application → Workspace Preview: renders preview (evidence: `frontend/src/App.jsx`)
- Web Application → Web API Client: requests chat (evidence: `frontend/src/App.jsx`)
- Workspace Preview → Web API Client: requests files (evidence: `frontend/src/components/WorkspacePanel.jsx`)
- Web API Client → Chat and Workspace API: posts chat (evidence: `frontend/src/services/api.js`)
- Web API Client → Health API: fetches status (evidence: `frontend/src/services/api.js`)
- FastAPI App → Chat and Workspace API: registers routes (evidence: `backend/app/main.py`)
- FastAPI App → Health API: registers routes (evidence: `backend/app/main.py`)
- Chat and Workspace API → Agent Loop: runs agent turn (evidence: `backend/app/api/routes_chat.py`)
- Chat and Workspace API → Workspace File Tools: lists and reads (evidence: `backend/app/api/routes_chat.py`)
- Chat and Workspace API → Runtime Settings: uses settings (evidence: `backend/app/api/routes_chat.py`)
- Health API → Runtime Settings: reads settings (evidence: `backend/app/api/routes_health.py`)
- Health API → Ollama: checks models (evidence: `backend/app/api/routes_health.py`)
- Agent Loop → Ollama: requests inference (evidence: `README.md`)
- Agent Loop → Workspace File Tools: uses workspace tools (evidence: `README.md`)
- Agent Loop → Skill Loader: loads relevant skills (evidence: `README.md`)
- Skill Loader → Bundled Skills: discovers and reads (evidence: `backend/app/agent/skills.py`)
- Workspace File Tools → Workspace Files: reads and writes (evidence: `README.md`)
- Terminal CLI → Agent Loop: runs agent turns (evidence: `cli/main.py`)
- Terminal CLI → Runtime Settings: uses settings (evidence: `cli/main.py`)
- Terminal CLI → Skill Loader: lists skills (evidence: `cli/main.py`)
- Chat and Trace → Tool Activity Panel: renders tool traces (evidence: `frontend/src/components/ChatMessage.jsx`)
- Agent Loop → Workspace File Tools: may run pytest (evidence: `README.md`)
