# valgorithms/ai-router architecture

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

## Overview

VZG Coders AI Router accepts a coding prompt through a CLI or OpenAI-compatible HTTP server, selects and invokes models, evaluates responses, escalates failures, and records metrics. Jev can influence initial model choice and judge response quality; without it, transport failures drive fallback. The graph preserves the model adapters and shared HTTP, configuration, evaluation, and result layers. Relationships for the CLI and API server rely on README/SOURCE INDEX evidence where their source was not excerpted; unsampled internals are not inferred.

Main entry points: [`src/Router.php`](https://github.com/valgorithms/ai-router/blob/master/src/Router.php) (Routing and escalation), [`src/Application.php`](https://github.com/valgorithms/ai-router/blob/master/src/Application.php) (Application setup), [`src/Model/ModelResult.php`](https://github.com/valgorithms/ai-router/blob/master/src/Model/ModelResult.php) (Model result), [`src/Evaluation/Evaluator.php`](https://github.com/valgorithms/ai-router/blob/master/src/Evaluation/Evaluator.php) (Response evaluator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI"]
  node_api["HTTP API server<br/>[ApiServer.php]"]
  node_application["Application setup<br/>[Application.php]"]
end

subgraph group_routing["Routing and evaluation"]
  node_router["Routing and escalation<br/>[Router.php]"]
  node_jev["Jev client<br/>[JevClient.php]"]
  node_evaluator["Response evaluator<br/>[Evaluator.php]"]
  node_evaluation_result["Evaluation result"]
  node_metrics[("Metrics store<br/>[MetricsStore.php]")]
end

subgraph group_models["Model adapters"]
  node_model_interface["Model interface<br/>[ModelInterface.php]"]
  node_model_result["Model result<br/>[ModelResult.php]"]
  node_ollama["Ollama adapter<br/>[OllamaModel.php]"]
  node_claude["Claude adapter<br/>[ClaudeModel.php]"]
  node_openai["OpenAI adapter<br/>[OpenAiModel.php]"]
  node_copilot["Copilot adapter<br/>[CopilotModel.php]"]
end

subgraph group_support["Shared support"]
  node_env["Environment config<br/>[Env.php]"]
  node_http["HTTP client<br/>[HttpClient.php]"]
end

node_user(("Prompt user"))
node_client(("OpenAI-compatible client"))
node_jev_service{{"Jev service"}}
node_model_services{{"Model services"}}

node_user -->|"submits prompt"| node_cli
node_cli -->|"starts app"| node_application
node_user -->|"sends chat"| node_client
node_client -->|"calls API"| node_api
node_api -->|"dispatches request"| node_router
node_application -->|"loads config"| node_env
node_application -->|"constructs router"| node_router
node_application -->|"configures"| node_ollama
node_application -->|"configures optionally"| node_claude
node_application -->|"configures optionally"| node_openai
node_application -->|"configures"| node_copilot
node_application -->|"configures optionally"| node_jev
node_application -->|"constructs"| node_evaluator
node_application -->|"constructs"| node_metrics
node_router -->|"chooses initial model"| node_jev
node_router -->|"attempts model"| node_ollama
node_router -->|"escalates to"| node_claude
node_router -->|"escalates to"| node_openai
node_router -->|"escalates to"| node_copilot
node_router -->|"evaluates response"| node_evaluator
node_evaluator -->|"judges response"| node_jev
node_jev -->|"requests decisions"| node_jev_service
node_router -->|"records attempt"| node_metrics
node_evaluator -->|"returns evaluation"| node_evaluation_result
node_router -->|"uses result"| node_model_result
node_evaluator -->|"evaluates result"| node_model_result
node_router -->|"dispatches completion"| node_model_interface
node_ollama -->|"sends requests"| node_http
node_claude -->|"sends requests"| node_http
node_openai -->|"sends requests"| node_http
node_jev -->|"sends requests"| node_http
node_ollama -->|"returns completion"| node_model_result
node_claude -->|"returns completion"| node_model_result
node_openai -->|"returns completion"| node_model_result
node_copilot -->|"returns completion"| node_model_result
node_ollama -->|"calls local model"| node_model_services
node_claude -->|"calls provider"| node_model_services
node_openai -->|"calls provider"| node_model_services
node_copilot -->|"runs CLI"| node_model_services

click node_cli "https://github.com/valgorithms/ai-router/blob/master/bin/ai-router"
click node_api "https://github.com/valgorithms/ai-router/blob/master/src/Server/ApiServer.php"
click node_application "https://github.com/valgorithms/ai-router/blob/master/src/Application.php"
click node_router "https://github.com/valgorithms/ai-router/blob/master/src/Router.php"
click node_jev "https://github.com/valgorithms/ai-router/blob/master/src/JevClient.php"
click node_evaluator "https://github.com/valgorithms/ai-router/blob/master/src/Evaluation/Evaluator.php"
click node_evaluation_result "https://github.com/valgorithms/ai-router/blob/master/src/Evaluation/EvaluationResult.php"
click node_metrics "https://github.com/valgorithms/ai-router/blob/master/src/Metrics/MetricsStore.php"
click node_model_interface "https://github.com/valgorithms/ai-router/blob/master/src/Model/ModelInterface.php"
click node_model_result "https://github.com/valgorithms/ai-router/blob/master/src/Model/ModelResult.php"
click node_ollama "https://github.com/valgorithms/ai-router/blob/master/src/Model/OllamaModel.php"
click node_claude "https://github.com/valgorithms/ai-router/blob/master/src/Model/ClaudeModel.php"
click node_openai "https://github.com/valgorithms/ai-router/blob/master/src/Model/OpenAiModel.php"
click node_copilot "https://github.com/valgorithms/ai-router/blob/master/src/Model/CopilotModel.php"
click node_env "https://github.com/valgorithms/ai-router/blob/master/src/Support/Env.php"
click node_http "https://github.com/valgorithms/ai-router/blob/master/src/Support/HttpClient.php"

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_cli,node_api,node_application,node_user,node_client toneBlue
class node_router,node_jev,node_evaluator,node_evaluation_result,node_metrics toneAmber
class node_model_interface,node_model_result,node_ollama,node_claude,node_openai,node_copilot toneMint
class node_env,node_http toneRose
class node_jev_service,node_model_services toneIndigo
```

## Components

### Entry points

- [CLI](https://github.com/valgorithms/ai-router/blob/master/bin/ai-router): `bin/ai-router`
- [HTTP API server](https://github.com/valgorithms/ai-router/blob/master/src/Server/ApiServer.php): `src/Server/ApiServer.php`
- [Application setup](https://github.com/valgorithms/ai-router/blob/master/src/Application.php): `src/Application.php`

### Routing and evaluation

- [Routing and escalation](https://github.com/valgorithms/ai-router/blob/master/src/Router.php): `src/Router.php`
- [Jev client](https://github.com/valgorithms/ai-router/blob/master/src/JevClient.php): `src/JevClient.php`
- [Response evaluator](https://github.com/valgorithms/ai-router/blob/master/src/Evaluation/Evaluator.php): `src/Evaluation/Evaluator.php`
- [Evaluation result](https://github.com/valgorithms/ai-router/blob/master/src/Evaluation/EvaluationResult.php): `src/Evaluation/EvaluationResult.php`
- [Metrics store](https://github.com/valgorithms/ai-router/blob/master/src/Metrics/MetricsStore.php): `src/Metrics/MetricsStore.php`

### Model adapters

- [Model interface](https://github.com/valgorithms/ai-router/blob/master/src/Model/ModelInterface.php): `src/Model/ModelInterface.php`
- [Model result](https://github.com/valgorithms/ai-router/blob/master/src/Model/ModelResult.php): `src/Model/ModelResult.php`
- [Ollama adapter](https://github.com/valgorithms/ai-router/blob/master/src/Model/OllamaModel.php): `src/Model/OllamaModel.php`
- [Claude adapter](https://github.com/valgorithms/ai-router/blob/master/src/Model/ClaudeModel.php): `src/Model/ClaudeModel.php`
- [OpenAI adapter](https://github.com/valgorithms/ai-router/blob/master/src/Model/OpenAiModel.php): `src/Model/OpenAiModel.php`
- [Copilot adapter](https://github.com/valgorithms/ai-router/blob/master/src/Model/CopilotModel.php): `src/Model/CopilotModel.php`

### Shared support

- [Environment config](https://github.com/valgorithms/ai-router/blob/master/src/Support/Env.php): `src/Support/Env.php`
- [HTTP client](https://github.com/valgorithms/ai-router/blob/master/src/Support/HttpClient.php): `src/Support/HttpClient.php`

### Other components

- **Prompt user**
- **OpenAI-compatible client**
- **Jev service**
- **Model services**

## Connections

- Prompt user → CLI: submits prompt (evidence: `README.md`)
- CLI → Application setup: starts app (evidence: `README.md`)
- Prompt user → OpenAI-compatible client: sends chat (evidence: `README.md`)
- OpenAI-compatible client → HTTP API server: calls API (evidence: `README.md`)
- HTTP API server → Routing and escalation: dispatches request (evidence: `src/Server/ApiServer.php`)
- Application setup → Environment config: loads config (evidence: `src/Application.php`)
- Application setup → Routing and escalation: constructs router (evidence: `src/Application.php`)
- Application setup → Ollama adapter: configures (evidence: `src/Application.php`)
- Application setup → Claude adapter: configures optionally (evidence: `src/Application.php`)
- Application setup → OpenAI adapter: configures optionally (evidence: `src/Application.php`)
- Application setup → Copilot adapter: configures (evidence: `src/Application.php`)
- Application setup → Jev client: configures optionally (evidence: `src/Application.php`)
- Application setup → Response evaluator: constructs (evidence: `src/Application.php`)
- Application setup → Metrics store: constructs (evidence: `src/Application.php`)
- Routing and escalation → Jev client: chooses initial model (evidence: `src/Router.php`)
- Routing and escalation → Ollama adapter: attempts model (evidence: `README.md`)
- Routing and escalation → Claude adapter: escalates to (evidence: `README.md`)
- Routing and escalation → OpenAI adapter: escalates to (evidence: `README.md`)
- Routing and escalation → Copilot adapter: escalates to (evidence: `README.md`)
- Routing and escalation → Response evaluator: evaluates response (evidence: `src/Router.php`)
- Response evaluator → Jev client: judges response (evidence: `src/Evaluation/Evaluator.php`)
- Jev client → Jev service: requests decisions (evidence: `src/JevClient.php`)
- Routing and escalation → Metrics store: records attempt (evidence: `src/Router.php`)
- Response evaluator → Evaluation result: returns evaluation (evidence: `src/Evaluation/Evaluator.php`)
- Routing and escalation → Model result: uses result (evidence: `src/Router.php`)
- Response evaluator → Model result: evaluates result (evidence: `src/Evaluation/Evaluator.php`)
- Routing and escalation → Model interface: dispatches completion (evidence: `src/Router.php`)
- Ollama adapter → HTTP client: sends requests (evidence: `src/Model/OllamaModel.php`)
- Claude adapter → HTTP client: sends requests (evidence: `src/Model/ClaudeModel.php`)
- OpenAI adapter → HTTP client: sends requests (evidence: `src/Model/OpenAiModel.php`)
- Jev client → HTTP client: sends requests (evidence: `src/JevClient.php`)
- Ollama adapter → Model result: returns completion (evidence: `src/Model/OllamaModel.php`)
- Claude adapter → Model result: returns completion (evidence: `src/Model/ClaudeModel.php`)
- OpenAI adapter → Model result: returns completion (evidence: `src/Model/OpenAiModel.php`)
- Copilot adapter → Model result: returns completion (evidence: `src/Model/CopilotModel.php`)
- Ollama adapter → Model services: calls local model (evidence: `README.md`)
- Claude adapter → Model services: calls provider (evidence: `README.md`)
- OpenAI adapter → Model services: calls provider (evidence: `README.md`)
- Copilot adapter → Model services: runs CLI (evidence: `README.md`)
