# md-sohail-ai/promptforge architecture

> Architecture diagram of the GitHub repository md-sohail-ai/promptforge, 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/md-sohail-ai/promptforge
- Repository: https://github.com/md-sohail-ai/promptforge

## Overview

ForgeX is a desktop embedded-development workspace whose primary flow is a user task becoming an agent plan, staged firmware edits, a build and repair cycle, then (with explicit approval) flashing and serial monitoring. The graph preserves the Nexus task UI, agent runtime, firmware lifecycle, model routing, and Electron/API boundary. Several subsystem connections are documented in the README or visible in the SOURCE INDEX; unsampled implementation details are not inferred.

Main entry points: [`backend/agent_runtime/autonomous_loop.py`](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/autonomous_loop.py) (Autonomous agent loop), [`electron/main.ts`](https://github.com/md-sohail-ai/promptforge/blob/main/electron/main.ts) (Desktop shell), [`backend/workflow/generate_code_handler.py`](https://github.com/md-sohail-ai/promptforge/blob/main/backend/workflow/generate_code_handler.py) (Generation workflow handler), [`frontend/components/nexus/nexus-shell.tsx`](https://github.com/md-sohail-ai/promptforge/blob/main/frontend/components/nexus/nexus-shell.tsx) (Nexus task UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Desktop experience"]
  node_nexus["Nexus task UI<br/>[nexus-shell.tsx]"]
  node_activity["Agent activity UI"]
  node_electron["Desktop shell<br/>[main.ts]"]
end

subgraph group_agent["Agent runtime"]
  node_agent_api["Agent API routes<br/>[agent_runtime.py]"]
  node_orchestrator["Agent orchestrator<br/>[orchestrator.py]"]
  node_agent_loop["Autonomous agent loop<br/>[autonomous_loop.py]"]
  node_planner["Tool-plan planner<br/>[router_planner.py]"]
  node_agent_tools["Tool execution<br/>[tool_executor.py]"]
  node_agent_state[("Sessions and run state<br/>[session_store.py]")]
end

subgraph group_firmware["Firmware lifecycle"]
  node_changes["ChangeSet review<br/>[service.py]"]
  node_generation["Firmware generation"]
  node_generation_handler["Generation workflow handler"]
  node_projects["Project persistence<br/>[project_service.py]"]
  node_build["Firmware build"]
  node_flash["Flash service<br/>[flash_service.py]"]
  node_serial["Serial monitoring<br/>[serial_runtime.py]"]
end

subgraph group_models["Model services"]
  node_model_router["Model router<br/>[router.py]"]
  node_llm["LLM provider service<br/>[llm_service.py]"]
  node_providers["Provider adapters"]
  node_model_store[("Model settings store<br/>[sqlite_storage.py]")]
end

subgraph group_platform["Backend platform"]
  node_api["FastAPI application<br/>[app.py]"]
  node_harness["Shadow harness host<br/>[server.ts]"]
end

node_user(("Engineer"))
node_platformio["PlatformIO"]
node_board["Connected board"]

node_user -->|"submits task"| node_nexus
node_nexus -->|"views progress"| node_activity
node_electron -->|"starts backend"| node_api
node_api -->|"routes requests"| node_agent_api
node_agent_api -.->|"dispatches agent work"| node_orchestrator
node_orchestrator -.->|"runs agent loop"| node_agent_loop
node_agent_loop -.->|"requests tool plans"| node_planner
node_agent_loop -->|"executes tools"| node_agent_tools
node_agent_loop -->|"persists sessions"| node_agent_state
node_agent_loop -->|"stages edits"| node_changes
node_agent_loop -->|"builds firmware"| node_build
node_agent_loop -->|"requests approved flash"| node_flash
node_agent_loop -->|"routes monitor actions"| node_serial
node_agent_loop -->|"requests model planning"| node_model_router
node_generation_handler -->|"generates project"| node_generation
node_generation_handler -->|"persists project"| node_projects
node_generation -->|"requests generation"| node_llm
node_llm -->|"calls provider"| node_providers
node_model_router -.->|"stores settings"| node_model_store
node_build -->|"builds project"| node_platformio
node_flash -->|"flashes firmware"| node_board
node_serial -->|"reads telemetry"| node_board
node_electron -->|"hosts in shadow mode"| node_harness

click node_nexus "https://github.com/md-sohail-ai/promptforge/blob/main/frontend/components/nexus/nexus-shell.tsx"
click node_activity "https://github.com/md-sohail-ai/promptforge/blob/main/frontend/components/agent-activity/agent-activity-feed.tsx"
click node_electron "https://github.com/md-sohail-ai/promptforge/blob/main/electron/main.ts"
click node_api "https://github.com/md-sohail-ai/promptforge/blob/main/backend/api/app.py"
click node_agent_api "https://github.com/md-sohail-ai/promptforge/blob/main/backend/api/routes/agent_runtime.py"
click node_orchestrator "https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/orchestrator.py"
click node_agent_loop "https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/autonomous_loop.py"
click node_planner "https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/router_planner.py"
click node_agent_tools "https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/tool_executor.py"
click node_agent_state "https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/session_store.py"
click node_changes "https://github.com/md-sohail-ai/promptforge/blob/main/backend/changes/service.py"
click node_generation "https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/code_generation_service.py"
click node_generation_handler "https://github.com/md-sohail-ai/promptforge/blob/main/backend/workflow/generate_code_handler.py"
click node_projects "https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/project_service.py"
click node_build "https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/platformio_service.py"
click node_flash "https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/flash_service.py"
click node_serial "https://github.com/md-sohail-ai/promptforge/blob/main/backend/runtime/serial_runtime.py"
click node_model_router "https://github.com/md-sohail-ai/promptforge/blob/main/backend/model_router/router.py"
click node_llm "https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/llm_service.py"
click node_providers "https://github.com/md-sohail-ai/promptforge/tree/main/backend/model_router/providers"
click node_model_store "https://github.com/md-sohail-ai/promptforge/blob/main/backend/model_router/sqlite_storage.py"
click node_harness "https://github.com/md-sohail-ai/promptforge/blob/main/harness/src/server.ts"

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_nexus,node_activity,node_electron toneBlue
class node_agent_api,node_orchestrator,node_agent_loop,node_planner,node_agent_tools,node_agent_state toneAmber
class node_changes,node_generation,node_generation_handler,node_projects,node_build,node_flash,node_serial toneMint
class node_model_router,node_llm,node_providers,node_model_store toneRose
class node_api,node_harness,node_user,node_platformio,node_board toneIndigo
```

## Components

### Desktop experience

- [Nexus task UI](https://github.com/md-sohail-ai/promptforge/blob/main/frontend/components/nexus/nexus-shell.tsx): `frontend/components/nexus/nexus-shell.tsx`
- [Agent activity UI](https://github.com/md-sohail-ai/promptforge/blob/main/frontend/components/agent-activity/agent-activity-feed.tsx): `frontend/components/agent-activity/agent-activity-feed.tsx`
- [Desktop shell](https://github.com/md-sohail-ai/promptforge/blob/main/electron/main.ts): `electron/main.ts`

### Agent runtime

- [Agent API routes](https://github.com/md-sohail-ai/promptforge/blob/main/backend/api/routes/agent_runtime.py): `backend/api/routes/agent_runtime.py`
- [Agent orchestrator](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/orchestrator.py): `backend/agent_runtime/orchestrator.py`
- [Autonomous agent loop](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/autonomous_loop.py): `backend/agent_runtime/autonomous_loop.py`
- [Tool-plan planner](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/router_planner.py): `backend/agent_runtime/router_planner.py`
- [Tool execution](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/tool_executor.py): `backend/agent_runtime/tool_executor.py`
- [Sessions and run state](https://github.com/md-sohail-ai/promptforge/blob/main/backend/agent_runtime/session_store.py): `backend/agent_runtime/session_store.py`

### Firmware lifecycle

- [ChangeSet review](https://github.com/md-sohail-ai/promptforge/blob/main/backend/changes/service.py): `backend/changes/service.py`
- [Firmware generation](https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/code_generation_service.py): `backend/services/code_generation_service.py`
- [Generation workflow handler](https://github.com/md-sohail-ai/promptforge/blob/main/backend/workflow/generate_code_handler.py): `backend/workflow/generate_code_handler.py`
- [Project persistence](https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/project_service.py): `backend/services/project_service.py`
- [Firmware build](https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/platformio_service.py): `backend/services/platformio_service.py`
- [Flash service](https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/flash_service.py): `backend/services/flash_service.py`
- [Serial monitoring](https://github.com/md-sohail-ai/promptforge/blob/main/backend/runtime/serial_runtime.py): `backend/runtime/serial_runtime.py`

### Model services

- [Model router](https://github.com/md-sohail-ai/promptforge/blob/main/backend/model_router/router.py): `backend/model_router/router.py`
- [LLM provider service](https://github.com/md-sohail-ai/promptforge/blob/main/backend/services/llm_service.py): `backend/services/llm_service.py`
- [Provider adapters](https://github.com/md-sohail-ai/promptforge/tree/main/backend/model_router/providers): `backend/model_router/providers`
- [Model settings store](https://github.com/md-sohail-ai/promptforge/blob/main/backend/model_router/sqlite_storage.py): `backend/model_router/sqlite_storage.py`

### Backend platform

- [FastAPI application](https://github.com/md-sohail-ai/promptforge/blob/main/backend/api/app.py): `backend/api/app.py`
- [Shadow harness host](https://github.com/md-sohail-ai/promptforge/blob/main/harness/src/server.ts): `harness/src/server.ts`

### Other components

- **Engineer**
- **PlatformIO**
- **Connected board**

## Connections

- Engineer → Nexus task UI: submits task (evidence: `README.md`)
- Nexus task UI → Agent activity UI: views progress (evidence: `README.md`)
- Desktop shell → FastAPI application: starts backend (evidence: `README.md`)
- FastAPI application → Agent API routes: routes requests (evidence: `backend/api/app.py`)
- Agent API routes → Agent orchestrator: dispatches agent work
- Agent orchestrator → Autonomous agent loop: runs agent loop
- Autonomous agent loop → Tool-plan planner: requests tool plans
- Autonomous agent loop → Tool execution: executes tools (evidence: `README.md`)
- Autonomous agent loop → Sessions and run state: persists sessions (evidence: `README.md`)
- Autonomous agent loop → ChangeSet review: stages edits (evidence: `README.md`)
- Autonomous agent loop → Firmware build: builds firmware (evidence: `README.md`)
- Autonomous agent loop → Flash service: requests approved flash (evidence: `README.md`)
- Autonomous agent loop → Serial monitoring: routes monitor actions (evidence: `README.md`)
- Autonomous agent loop → Model router: requests model planning
- Generation workflow handler → Firmware generation: generates project (evidence: `backend/workflow/generate_code_handler.py`)
- Generation workflow handler → Project persistence: persists project (evidence: `backend/workflow/generate_code_handler.py`)
- Firmware generation → LLM provider service: requests generation (evidence: `backend/services/code_generation_service.py`)
- LLM provider service → Provider adapters: calls provider (evidence: `backend/services/llm_service.py`)
- Model router → Model settings store: stores settings
- Firmware build → PlatformIO: builds project (evidence: `README.md`)
- Flash service → Connected board: flashes firmware (evidence: `README.md`)
- Serial monitoring → Connected board: reads telemetry (evidence: `README.md`)
- Desktop shell → Shadow harness host: hosts in shadow mode (evidence: `README.md`)
