# starrfree/solver-agent architecture

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

- Interactive diagram: https://gitdiagram.com/starrfree/solver-agent
- Repository: https://github.com/starrfree/solver-agent

## Overview

Solver Agent turns a user’s technical problem into an auditable solution: the backend coordinates solver and specialist agents, records typed steps in a persistent ledger, and verifies the result; the Angular UI streams progress and exposes the proof, artifacts, and conversation controls. Separate branches support proof narration, side-talk, exports, and usage tracking. The graph reflects documented capabilities and the sampled wiring; several tool implementations and route handlers were not excerpted, so those links are omitted or marked unverified.

Main entry points: [`backend/src/services/solverOrchestrator.ts`](https://github.com/starrfree/solver-agent/blob/main/backend/src/services/solverOrchestrator.ts) (Solver orchestrator), [`backend/src/index.ts`](https://github.com/starrfree/solver-agent/blob/main/backend/src/index.ts) (HTTP application), [`backend/src/routes/conversations.ts`](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/conversations.ts) (Conversation routes), [`backend/src/repositories/ledgerRepo.ts`](https://github.com/starrfree/solver-agent/blob/main/backend/src/repositories/ledgerRepo.ts) (Ledger repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interface"]
  node_ui["Conversation workspace<br/>[app.component.ts]"]
  node_state["Conversation state"]
  node_client["API and stream clients<br/>[api.service.ts]"]
  node_content["Ledger and proof views"]
  node_artifacts["Artifact panel"]
end

subgraph group_api["Backend API"]
  node_server["HTTP application<br/>[index.ts]"]
  node_conversation_routes["Conversation routes<br/>[conversations.ts]"]
  node_message_routes["Message routes<br/>[messages.ts]"]
  node_stream_routes["Live event route<br/>[stream.ts]"]
  node_export_routes["Export routes<br/>[export.ts]"]
end

subgraph group_reasoning["Solver workflow"]
  node_orchestrator["Solver orchestrator"]
  node_main_solver["Main solver agent<br/>[mainSolverAgent.ts]"]
  node_specialists["Specialist agents and tools"]
  node_llm["Provider facade<br/>[llmClient.ts]"]
  node_python["Computation sandbox<br/>[runner.ts]"]
  node_narrative["Proof narrator"]
end

subgraph group_persistence["Persistence and events"]
  node_ledger["Ledger repository<br/>[ledgerRepo.ts]"]
  node_conversations["Conversation repository"]
  node_mongo[("MongoDB<br/>[mongo.ts]")]
  node_events["Event bus<br/>[eventBus.ts]"]
end

subgraph group_support["Supporting capabilities"]
  node_side_talk["Side-talk service<br/>[sideTalk.ts]"]
  node_exports["Export rendering<br/>[buildExport.ts]"]
  node_usage["Usage tracking<br/>[usageTracker.ts]"]
end

node_user(("Researcher"))
node_providers(("LLM providers"))

node_user -->|"poses problem"| node_ui
node_ui -->|"loads conversations"| node_state
node_state -->|"calls API"| node_client
node_client -.->|"sends requests"| node_server
node_server -->|"routes requests"| node_conversation_routes
node_server -->|"routes requests"| node_message_routes
node_server -->|"routes requests"| node_stream_routes
node_server -->|"routes requests"| node_export_routes
node_conversation_routes -->|"starts runs"| node_orchestrator
node_conversation_routes -->|"reads and writes"| node_conversations
node_conversation_routes -->|"reads and writes"| node_ledger
node_message_routes -.->|"dispatches run"| node_orchestrator
node_orchestrator -->|"runs solver turn"| node_main_solver
node_orchestrator -->|"updates ledger"| node_ledger
node_orchestrator -->|"loads conversation"| node_conversations
node_main_solver -.->|"delegates computation"| node_specialists
node_specialists -.->|"runs code"| node_python
node_main_solver -.->|"requests responses"| node_llm
node_llm -->|"dispatches calls"| node_providers
node_orchestrator -->|"emits progress"| node_events
node_narrative -->|"reads and saves proof"| node_ledger
node_narrative -->|"emits narrative event"| node_events
node_ledger -->|"persists entries"| node_mongo
node_conversations -->|"persists conversations"| node_mongo
node_stream_routes -.->|"streams events"| node_events
node_state -.->|"supplies view state"| node_content
node_content -.->|"opens artifacts"| node_artifacts
node_export_routes -.->|"builds exports"| node_exports
node_user -.->|"interrogates solution"| node_side_talk
node_llm -->|"records call usage"| node_usage

click node_ui "https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/app.component.ts"
click node_state "https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/core/state/conversation-store.service.ts"
click node_client "https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/core/api/api.service.ts"
click node_content "https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/features/content/content.component.ts"
click node_artifacts "https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/features/artifacts/artifacts-panel.component.ts"
click node_server "https://github.com/starrfree/solver-agent/blob/main/backend/src/index.ts"
click node_conversation_routes "https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/conversations.ts"
click node_message_routes "https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/messages.ts"
click node_stream_routes "https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/stream.ts"
click node_export_routes "https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/export.ts"
click node_orchestrator "https://github.com/starrfree/solver-agent/blob/main/backend/src/services/solverOrchestrator.ts"
click node_main_solver "https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/mainSolverAgent.ts"
click node_specialists "https://github.com/starrfree/solver-agent/tree/main/backend/src/agents"
click node_llm "https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/llmClient.ts"
click node_python "https://github.com/starrfree/solver-agent/blob/main/backend/src/python/runner.ts"
click node_narrative "https://github.com/starrfree/solver-agent/blob/main/backend/src/services/narrativeService.ts"
click node_ledger "https://github.com/starrfree/solver-agent/blob/main/backend/src/repositories/ledgerRepo.ts"
click node_conversations "https://github.com/starrfree/solver-agent/blob/main/backend/src/repositories/conversationRepo.ts"
click node_mongo "https://github.com/starrfree/solver-agent/blob/main/backend/src/db/mongo.ts"
click node_events "https://github.com/starrfree/solver-agent/blob/main/backend/src/events/eventBus.ts"
click node_side_talk "https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/sideTalk.ts"
click node_exports "https://github.com/starrfree/solver-agent/blob/main/backend/src/export/buildExport.ts"
click node_usage "https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/usageTracker.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_ui,node_state,node_client,node_content,node_artifacts toneBlue
class node_server,node_conversation_routes,node_message_routes,node_stream_routes,node_export_routes toneAmber
class node_orchestrator,node_main_solver,node_specialists,node_llm,node_python,node_narrative toneMint
class node_ledger,node_conversations,node_mongo,node_events toneRose
class node_side_talk,node_exports,node_usage,node_user,node_providers toneIndigo
```

## Components

### User interface

- [Conversation workspace](https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/app.component.ts): `frontend/src/app/app.component.ts`
- [Conversation state](https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/core/state/conversation-store.service.ts): `frontend/src/app/core/state/conversation-store.service.ts`
- [API and stream clients](https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/core/api/api.service.ts): `frontend/src/app/core/api/api.service.ts`
- [Ledger and proof views](https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/features/content/content.component.ts): `frontend/src/app/features/content/content.component.ts`
- [Artifact panel](https://github.com/starrfree/solver-agent/blob/main/frontend/src/app/features/artifacts/artifacts-panel.component.ts): `frontend/src/app/features/artifacts/artifacts-panel.component.ts`

### Backend API

- [HTTP application](https://github.com/starrfree/solver-agent/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [Conversation routes](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/conversations.ts): `backend/src/routes/conversations.ts`
- [Message routes](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/messages.ts): `backend/src/routes/messages.ts`
- [Live event route](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/stream.ts): `backend/src/routes/stream.ts`
- [Export routes](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/export.ts): `backend/src/routes/export.ts`

### Solver workflow

- [Solver orchestrator](https://github.com/starrfree/solver-agent/blob/main/backend/src/services/solverOrchestrator.ts): `backend/src/services/solverOrchestrator.ts`
- [Main solver agent](https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/mainSolverAgent.ts): `backend/src/agents/mainSolverAgent.ts`
- [Specialist agents and tools](https://github.com/starrfree/solver-agent/tree/main/backend/src/agents): `backend/src/agents`
- [Provider facade](https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/llmClient.ts): `backend/src/agents/llmClient.ts`
- [Computation sandbox](https://github.com/starrfree/solver-agent/blob/main/backend/src/python/runner.ts): `backend/src/python/runner.ts`
- [Proof narrator](https://github.com/starrfree/solver-agent/blob/main/backend/src/services/narrativeService.ts): `backend/src/services/narrativeService.ts`

### Persistence and events

- [Ledger repository](https://github.com/starrfree/solver-agent/blob/main/backend/src/repositories/ledgerRepo.ts): `backend/src/repositories/ledgerRepo.ts`
- [Conversation repository](https://github.com/starrfree/solver-agent/blob/main/backend/src/repositories/conversationRepo.ts): `backend/src/repositories/conversationRepo.ts`
- [MongoDB](https://github.com/starrfree/solver-agent/blob/main/backend/src/db/mongo.ts): `backend/src/db/mongo.ts`
- [Event bus](https://github.com/starrfree/solver-agent/blob/main/backend/src/events/eventBus.ts): `backend/src/events/eventBus.ts`

### Supporting capabilities

- [Side-talk service](https://github.com/starrfree/solver-agent/blob/main/backend/src/routes/sideTalk.ts): `backend/src/routes/sideTalk.ts`
- [Export rendering](https://github.com/starrfree/solver-agent/blob/main/backend/src/export/buildExport.ts): `backend/src/export/buildExport.ts`
- [Usage tracking](https://github.com/starrfree/solver-agent/blob/main/backend/src/agents/usageTracker.ts): `backend/src/agents/usageTracker.ts`

### Other components

- **Researcher**
- **LLM providers**

## Connections

- Researcher → Conversation workspace: poses problem (evidence: `README.md`)
- Conversation workspace → Conversation state: loads conversations (evidence: `frontend/src/app/app.component.ts`)
- Conversation state → API and stream clients: calls API (evidence: `frontend/src/app/core/state/conversation-store.service.ts`)
- API and stream clients → HTTP application: sends requests
- HTTP application → Conversation routes: routes requests (evidence: `backend/src/index.ts`)
- HTTP application → Message routes: routes requests (evidence: `backend/src/index.ts`)
- HTTP application → Live event route: routes requests (evidence: `backend/src/index.ts`)
- HTTP application → Export routes: routes requests (evidence: `backend/src/index.ts`)
- Conversation routes → Solver orchestrator: starts runs (evidence: `backend/src/routes/conversations.ts`)
- Conversation routes → Conversation repository: reads and writes (evidence: `backend/src/routes/conversations.ts`)
- Conversation routes → Ledger repository: reads and writes (evidence: `backend/src/routes/conversations.ts`)
- Message routes → Solver orchestrator: dispatches run
- Solver orchestrator → Main solver agent: runs solver turn (evidence: `backend/src/services/solverOrchestrator.ts`)
- Solver orchestrator → Ledger repository: updates ledger (evidence: `backend/src/services/solverOrchestrator.ts`)
- Solver orchestrator → Conversation repository: loads conversation (evidence: `backend/src/services/solverOrchestrator.ts`)
- Main solver agent → Specialist agents and tools: delegates computation
- Specialist agents and tools → Computation sandbox: runs code
- Main solver agent → Provider facade: requests responses
- Provider facade → LLM providers: dispatches calls (evidence: `backend/src/agents/llmClient.ts`)
- Solver orchestrator → Event bus: emits progress (evidence: `backend/src/services/solverOrchestrator.ts`)
- Proof narrator → Ledger repository: reads and saves proof (evidence: `backend/src/services/narrativeService.ts`)
- Proof narrator → Event bus: emits narrative event (evidence: `backend/src/services/narrativeService.ts`)
- Ledger repository → MongoDB: persists entries (evidence: `backend/src/repositories/ledgerRepo.ts`)
- Conversation repository → MongoDB: persists conversations (evidence: `backend/src/repositories/conversationRepo.ts`)
- Live event route → Event bus: streams events
- Conversation state → Ledger and proof views: supplies view state
- Ledger and proof views → Artifact panel: opens artifacts
- Export routes → Export rendering: builds exports
- Researcher → Side-talk service: interrogates solution
- Provider facade → Usage tracking: records call usage (evidence: `backend/src/agents/llmClient.ts`)
