# chaitanya-sharmaa/axon architecture

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

- Interactive diagram: https://gitdiagram.com/chaitanya-sharmaa/axon
- Repository: https://github.com/chaitanya-sharmaa/axon

## Overview

Axon Bridge is an OpenAI-compatible LLM proxy and cost-optimization layer. An application sends an OpenAI-style request to Axon; the proxy applies caching, request protections and payload optimization, chooses a model/provider, forwards the request and returns a compatible response. Separate product paths provide agentic dispatch and loop protections, Assistants threads and file-backed RAG, and an admin dashboard for live operational visibility. The graph follows the documented capabilities and sampled route/service behavior; several internal links are omitted where implementation wiring was not sampled.

Main entry points: [`axon/api/routes/v1_openai_routes.py`](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_openai_routes.py) (OpenAI-compatible routes), [`axon/app.py`](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/app.py) (FastAPI application), [`axon/api/routes/proxy_routes.py`](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/proxy_routes.py) (HTTP upstream proxy), [`axon/api/routes/v1_assistants_routes.py`](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_assistants_routes.py) (Assistants API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_proxy["Proxy workflow"]
  node_app["FastAPI application<br/>[app.py]"]
  node_openai["OpenAI-compatible routes"]
  node_proxyroute["HTTP upstream proxy<br/>[proxy_routes.py]"]
end

subgraph group_intelligence["Optimization and safety"]
  node_optimization["Token optimization<br/>[token_optimizer.py]"]
  node_router["Model routing<br/>[smart_router.py]"]
  node_security["Prompt and PII safety<br/>[security_policy.py]"]
  node_vision["Vision optimization"]
end

subgraph group_state["Memory and state"]
  node_assistants["Assistants API"]
  node_memory[("Thread memory<br/>[memory_store.py]")]
  node_vector[("RAG vector search<br/>[vector_store.py]")]
  node_cache[("Exact-match cache<br/>[kv_cache.py]")]
end

subgraph group_agentic["Agent workflows"]
  node_agentpipeline["Agentic middleware<br/>[pipeline.py]"]
  node_loop["Loop detection<br/>[loop_detector.py]"]
  node_agentroutes["Agent dispatch routes<br/>[agent_routes.py]"]
  node_orchestrator["Agent orchestrator"]
end

subgraph group_operations["Operations and UI"]
  node_dashboard["Admin dashboard<br/>[App.jsx]"]
  node_adminroutes["Admin routes"]
  node_logger[("Request and event logs<br/>[request_logger.py]")]
end

node_application(("Client application"))
node_upstream["LLM provider"]

node_application -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_openai
node_app -->|"mounts routes"| node_proxyroute
node_app -->|"mounts routes"| node_agentroutes
node_app -->|"mounts routes"| node_assistants
node_app -->|"mounts routes"| node_adminroutes
node_openai -->|"checks and reads"| node_cache
node_openai -->|"downscales images"| node_vision
node_openai -->|"optimizes payload"| node_optimization
node_openai -->|"selects model"| node_router
node_openai -->|"applies protections"| node_security
node_openai -->|"forwards request"| node_upstream
node_upstream -->|"returns response"| node_openai
node_proxyroute -->|"forwards HTTP"| node_upstream
node_proxyroute -->|"encodes response"| node_optimization
node_proxyroute -->|"logs session event"| node_memory
node_agentroutes -->|"dispatches work"| node_orchestrator
node_agentroutes -->|"records swarm event"| node_memory
node_agentpipeline -->|"checks tool loops"| node_loop
node_assistants -->|"reads and writes threads"| node_memory
node_assistants -->|"searches attached files"| node_vector
node_dashboard -->|"queries operations"| node_adminroutes
node_adminroutes -->|"reads request logs"| node_logger

click node_app "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/app.py"
click node_openai "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_openai_routes.py"
click node_proxyroute "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/proxy_routes.py"
click node_optimization "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/token_optimizer.py"
click node_router "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/smart_router.py"
click node_security "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/security_policy.py"
click node_vision "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/vision_optimizer.py"
click node_agentpipeline "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agentic/pipeline.py"
click node_loop "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agentic/loop_detector.py"
click node_agentroutes "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/agent_routes.py"
click node_orchestrator "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agent_orchestrator.py"
click node_assistants "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_assistants_routes.py"
click node_memory "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/memory_store.py"
click node_vector "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/vector_store.py"
click node_cache "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/kv_cache.py"
click node_dashboard "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/dashboard/src/App.jsx"
click node_adminroutes "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/dashboard_routes.py"
click node_logger "https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/request_logger.py"

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_app,node_openai,node_proxyroute,node_application toneBlue
class node_optimization,node_router,node_security,node_vision toneAmber
class node_assistants,node_memory,node_vector,node_cache toneMint
class node_agentpipeline,node_loop,node_agentroutes,node_orchestrator toneRose
class node_dashboard,node_adminroutes,node_logger,node_upstream toneIndigo
```

## Components

### Proxy workflow

- [FastAPI application](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/app.py): `axon/app.py`
- [OpenAI-compatible routes](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_openai_routes.py): `axon/api/routes/v1_openai_routes.py`
- [HTTP upstream proxy](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/proxy_routes.py): `axon/api/routes/proxy_routes.py`

### Optimization and safety

- [Token optimization](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/token_optimizer.py): `axon/services/token_optimizer.py`
- [Model routing](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/smart_router.py): `axon/services/smart_router.py`
- [Prompt and PII safety](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/security_policy.py): `axon/services/security_policy.py`
- [Vision optimization](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/vision_optimizer.py): `axon/services/vision_optimizer.py`

### Memory and state

- [Assistants API](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/v1_assistants_routes.py): `axon/api/routes/v1_assistants_routes.py`
- [Thread memory](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/memory_store.py): `axon/services/memory_store.py`
- [RAG vector search](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/vector_store.py): `axon/services/vector_store.py`
- [Exact-match cache](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/kv_cache.py): `axon/services/kv_cache.py`

### Agent workflows

- [Agentic middleware](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agentic/pipeline.py): `axon/services/agentic/pipeline.py`
- [Loop detection](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agentic/loop_detector.py): `axon/services/agentic/loop_detector.py`
- [Agent dispatch routes](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/agent_routes.py): `axon/api/routes/agent_routes.py`
- [Agent orchestrator](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/agent_orchestrator.py): `axon/services/agent_orchestrator.py`

### Operations and UI

- [Admin dashboard](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/dashboard/src/App.jsx): `axon/dashboard/src/App.jsx`
- [Admin routes](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/api/routes/dashboard_routes.py): `axon/api/routes/dashboard_routes.py`
- [Request and event logs](https://github.com/chaitanya-sharmaa/axon/blob/main/axon/services/request_logger.py): `axon/services/request_logger.py`

### Other components

- **Client application**
- **LLM provider**

## Connections

- Client application → FastAPI application: sends requests
- FastAPI application → OpenAI-compatible routes: mounts routes
- FastAPI application → HTTP upstream proxy: mounts routes
- FastAPI application → Agent dispatch routes: mounts routes
- FastAPI application → Assistants API: mounts routes
- FastAPI application → Admin routes: mounts routes
- OpenAI-compatible routes → Exact-match cache: checks and reads
- OpenAI-compatible routes → Vision optimization: downscales images
- OpenAI-compatible routes → Token optimization: optimizes payload
- OpenAI-compatible routes → Model routing: selects model
- OpenAI-compatible routes → Prompt and PII safety: applies protections
- OpenAI-compatible routes → LLM provider: forwards request
- LLM provider → OpenAI-compatible routes: returns response
- HTTP upstream proxy → LLM provider: forwards HTTP
- HTTP upstream proxy → Token optimization: encodes response
- HTTP upstream proxy → Thread memory: logs session event
- Agent dispatch routes → Agent orchestrator: dispatches work
- Agent dispatch routes → Thread memory: records swarm event
- Agentic middleware → Loop detection: checks tool loops
- Assistants API → Thread memory: reads and writes threads
- Assistants API → RAG vector search: searches attached files
- Admin dashboard → Admin routes: queries operations
- Admin routes → Request and event logs: reads request logs