How md-sohail-ai/promptforge works
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: autonomous_loop.py Autonomous agent loop · main.ts Desktop shell · generate_code_handler.py Generation workflow handler · nexus-shell.tsx Nexus task UI
Components 25
Desktop experience
- Nexus task UI
frontend/components/nexus/nexus-shell.tsx - Agent activity UI
frontend/components/agent-activity/agent-activity-feed.tsx - Desktop shell
electron/main.ts
Agent runtime
- Agent API routes
backend/api/routes/agent_runtime.py - Agent orchestrator
backend/agent_runtime/orchestrator.py - Autonomous agent loop
backend/agent_runtime/autonomous_loop.py - Tool-plan planner
backend/agent_runtime/router_planner.py - Tool execution
backend/agent_runtime/tool_executor.py - Sessions and run state
backend/agent_runtime/session_store.py
Firmware lifecycle
- ChangeSet review
backend/changes/service.py - Firmware generation
backend/services/code_generation_service.py - Generation workflow handler
backend/workflow/generate_code_handler.py - Project persistence
backend/services/project_service.py - Firmware build
backend/services/platformio_service.py - Flash service
backend/services/flash_service.py - Serial monitoring
backend/runtime/serial_runtime.py
Model services
- Model router
backend/model_router/router.py - LLM provider service
backend/services/llm_service.py - Provider adapters
backend/model_router/providers - Model settings store
backend/model_router/sqlite_storage.py
Backend platform
- FastAPI application
backend/api/app.py - Shadow harness host
harness/src/server.ts
Other components
- Engineer
- PlatformIO
- Connected board
Connections 23
- Engineer → Nexus task UI: submits task
README.md - Nexus task UI → Agent activity UI: views progress
README.md - Desktop shell → FastAPI application: starts backend
README.md - FastAPI application → Agent API routes: routes requests
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
README.md - Autonomous agent loop → Sessions and run state: persists sessions
README.md - Autonomous agent loop → ChangeSet review: stages edits
README.md - Autonomous agent loop → Firmware build: builds firmware
README.md - Autonomous agent loop → Flash service: requests approved flash
README.md - Autonomous agent loop → Serial monitoring: routes monitor actions
README.md - Autonomous agent loop → Model router: requests model planning
- Generation workflow handler → Firmware generation: generates project
backend/workflow/generate_code_handler.py - Generation workflow handler → Project persistence: persists project
backend/workflow/generate_code_handler.py - Firmware generation → LLM provider service: requests generation
backend/services/code_generation_service.py - LLM provider service → Provider adapters: calls provider
backend/services/llm_service.py - Model router → Model settings store: stores settings
- Firmware build → PlatformIO: builds project
README.md - Flash service → Connected board: flashes firmware
README.md - Serial monitoring → Connected board: reads telemetry
README.md - Desktop shell → Shadow harness host: hosts in shadow mode
README.md