# zen4-bit/proxima architecture

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

- Interactive diagram: https://gitdiagram.com/zen4-bit/proxima
- Repository: https://github.com/zen4-bit/proxima

## Overview

Proxima is a local AI gateway for editor and desktop clients, with browser-session routing and BYOK/local-model routing. A typical request enters through its MCP server, is routed and enriched, then reaches a provider; the MCP pipeline also tracks usage and request state. The repository additionally contains a Python self-healing agent with computer/coding tools, cross-session memory, and a web interface. The README documents these capabilities; source excerpts and the SOURCE INDEX support only some internal call edges, so other links are omitted rather than inferred.

Main entry points: [`src/mcp/index.js`](https://github.com/zen4-bit/proxima/blob/main/src/mcp/index.js) (MCP Server), [`src/mcp/pipeline.js`](https://github.com/zen4-bit/proxima/blob/main/src/mcp/pipeline.js) (Request Pipeline), [`electron/main-v2.cjs`](https://github.com/zen4-bit/proxima/blob/main/electron/main-v2.cjs) (Local Gateway), [`proxima-agent/proxima_agent/agent.py`](https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/agent.py) (Python Agent)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gateway["Client Gateway"]
  node_mcp["MCP Server<br/>[index.js]"]
  node_chattools["Chat Tools<br/>[tools-chat.js]"]
  node_codetools["Code Tools<br/>[tools-code.js]"]
  node_searchtools["Search Tools<br/>[tools-search.js]"]
  node_workflowtools["Workflow Tools<br/>[tools-workflow.js]"]
end

subgraph group_routing["Model Routing"]
  node_pipeline["Request Pipeline<br/>[pipeline.js]"]
  node_smartrouter["Smart Router<br/>[smart-router.js]"]
  node_context["Context Middleware"]
  node_retry["Retry Engine<br/>[retry-engine.js]"]
  node_ipc["Provider IPC<br/>[ipc-bridge.js]"]
  node_electron["Local Gateway<br/>[main-v2.cjs]"]
  node_session["Browser Sessions<br/>[chatgpt-engine.js]"]
  node_byok["BYOK Router<br/>[router.cjs]"]
  node_keys[("Key Storage<br/>[keys.cjs]")]
end

subgraph group_agent["Agent Runtime"]
  node_agent["Python Agent<br/>[agent.py]"]
  node_agenttools["Agent Tools<br/>[registry.py]"]
end

subgraph group_memory["State and Memory"]
  node_tokens["Usage Tracking<br/>[token-tracker.js]"]
  node_memoryintel["Memory Intelligence"]
  node_memorystore[("Memory Store<br/>[memory-store.js]")]
end

subgraph group_interfaces["User Interfaces"]
  node_web["Agent Web Server<br/>[server.py]"]
  node_webdb[("Web State DB<br/>[db.py]")]
  node_cli["Command Line<br/>[proxima-cli.cjs]"]
  node_sdk["Client SDKs<br/>[proxima.js]"]
end

node_editor(("Editor Client"))

node_editor -->|"requests tools"| node_mcp
node_mcp -->|"registers tools"| node_chattools
node_mcp -->|"registers tools"| node_codetools
node_mcp -->|"registers tools"| node_searchtools
node_mcp -->|"registers tools"| node_workflowtools
node_mcp -->|"uses pipeline"| node_pipeline
node_pipeline -->|"injects context"| node_context
node_pipeline -->|"retries calls"| node_retry
node_pipeline -->|"records outcomes"| node_smartrouter
node_pipeline -->|"estimates tokens"| node_tokens
node_mcp -->|"connects to"| node_ipc
node_ipc -.->|"forwards requests"| node_electron
node_electron -.->|"routes sessions"| node_session
node_electron -.->|"routes BYOK"| node_byok
node_byok -->|"reads keys"| node_keys
node_mcp -->|"initializes memory"| node_memoryintel
node_mcp -->|"initializes store"| node_memorystore
node_agent -.->|"uses tools"| node_agenttools
node_agent -.->|"uses cross-session memory"| node_memoryintel
node_web -->|"uses database"| node_webdb
node_cli -.->|"controls local gateway"| node_electron
node_sdk -.->|"calls local endpoint"| node_electron

click node_mcp "https://github.com/zen4-bit/proxima/blob/main/src/mcp/index.js"
click node_chattools "https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-chat.js"
click node_codetools "https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-code.js"
click node_searchtools "https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-search.js"
click node_workflowtools "https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-workflow.js"
click node_pipeline "https://github.com/zen4-bit/proxima/blob/main/src/mcp/pipeline.js"
click node_smartrouter "https://github.com/zen4-bit/proxima/blob/main/src/agentic/smart-router.js"
click node_context "https://github.com/zen4-bit/proxima/blob/main/src/agentic/context7-middleware.js"
click node_retry "https://github.com/zen4-bit/proxima/blob/main/src/retry/retry-engine.js"
click node_ipc "https://github.com/zen4-bit/proxima/blob/main/src/mcp/ipc-bridge.js"
click node_electron "https://github.com/zen4-bit/proxima/blob/main/electron/main-v2.cjs"
click node_session "https://github.com/zen4-bit/proxima/blob/main/electron/providers/engines/chatgpt-engine.js"
click node_byok "https://github.com/zen4-bit/proxima/blob/main/electron/api/byok/router.cjs"
click node_keys "https://github.com/zen4-bit/proxima/blob/main/electron/api/byok/keys.cjs"
click node_tokens "https://github.com/zen4-bit/proxima/blob/main/src/cost/token-tracker.js"
click node_memoryintel "https://github.com/zen4-bit/proxima/blob/main/src/memory/memory-intelligence.js"
click node_memorystore "https://github.com/zen4-bit/proxima/blob/main/src/memory/memory-store.js"
click node_agent "https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/agent.py"
click node_agenttools "https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/tools/registry.py"
click node_web "https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/web/server.py"
click node_webdb "https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/web/db.py"
click node_cli "https://github.com/zen4-bit/proxima/blob/main/cli/proxima-cli.cjs"
click node_sdk "https://github.com/zen4-bit/proxima/blob/main/sdk/proxima.js"

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_mcp,node_chattools,node_codetools,node_searchtools,node_workflowtools,node_editor toneBlue
class node_pipeline,node_smartrouter,node_context,node_retry,node_ipc,node_electron,node_session,node_byok,node_keys toneAmber
class node_agent,node_agenttools toneMint
class node_tokens,node_memoryintel,node_memorystore toneRose
class node_web,node_webdb,node_cli,node_sdk toneIndigo
```

## Components

### Client Gateway

- [MCP Server](https://github.com/zen4-bit/proxima/blob/main/src/mcp/index.js): `src/mcp/index.js`
- [Chat Tools](https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-chat.js): `src/mcp/tools-chat.js`
- [Code Tools](https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-code.js): `src/mcp/tools-code.js`
- [Search Tools](https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-search.js): `src/mcp/tools-search.js`
- [Workflow Tools](https://github.com/zen4-bit/proxima/blob/main/src/mcp/tools-workflow.js): `src/mcp/tools-workflow.js`

### Model Routing

- [Request Pipeline](https://github.com/zen4-bit/proxima/blob/main/src/mcp/pipeline.js): `src/mcp/pipeline.js`
- [Smart Router](https://github.com/zen4-bit/proxima/blob/main/src/agentic/smart-router.js): `src/agentic/smart-router.js`
- [Context Middleware](https://github.com/zen4-bit/proxima/blob/main/src/agentic/context7-middleware.js): `src/agentic/context7-middleware.js`
- [Retry Engine](https://github.com/zen4-bit/proxima/blob/main/src/retry/retry-engine.js): `src/retry/retry-engine.js`
- [Provider IPC](https://github.com/zen4-bit/proxima/blob/main/src/mcp/ipc-bridge.js): `src/mcp/ipc-bridge.js`
- [Local Gateway](https://github.com/zen4-bit/proxima/blob/main/electron/main-v2.cjs): `electron/main-v2.cjs`
- [Browser Sessions](https://github.com/zen4-bit/proxima/blob/main/electron/providers/engines/chatgpt-engine.js): `electron/providers/engines/chatgpt-engine.js`
- [BYOK Router](https://github.com/zen4-bit/proxima/blob/main/electron/api/byok/router.cjs): `electron/api/byok/router.cjs`
- [Key Storage](https://github.com/zen4-bit/proxima/blob/main/electron/api/byok/keys.cjs): `electron/api/byok/keys.cjs`

### Agent Runtime

- [Python Agent](https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/agent.py): `proxima-agent/proxima_agent/agent.py`
- [Agent Tools](https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/tools/registry.py): `proxima-agent/proxima_agent/tools/registry.py`

### State and Memory

- [Usage Tracking](https://github.com/zen4-bit/proxima/blob/main/src/cost/token-tracker.js): `src/cost/token-tracker.js`
- [Memory Intelligence](https://github.com/zen4-bit/proxima/blob/main/src/memory/memory-intelligence.js): `src/memory/memory-intelligence.js`
- [Memory Store](https://github.com/zen4-bit/proxima/blob/main/src/memory/memory-store.js): `src/memory/memory-store.js`

### User Interfaces

- [Agent Web Server](https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/web/server.py): `proxima-agent/proxima_agent/web/server.py`
- [Web State DB](https://github.com/zen4-bit/proxima/blob/main/proxima-agent/proxima_agent/web/db.py): `proxima-agent/proxima_agent/web/db.py`
- [Command Line](https://github.com/zen4-bit/proxima/blob/main/cli/proxima-cli.cjs): `cli/proxima-cli.cjs`
- [Client SDKs](https://github.com/zen4-bit/proxima/blob/main/sdk/proxima.js): `sdk/proxima.js`

### Other components

- **Editor Client**

## Connections

- Editor Client → MCP Server: requests tools (evidence: `README.md`)
- MCP Server → Chat Tools: registers tools (evidence: `src/mcp/index.js`)
- MCP Server → Code Tools: registers tools (evidence: `src/mcp/index.js`)
- MCP Server → Search Tools: registers tools (evidence: `src/mcp/index.js`)
- MCP Server → Workflow Tools: registers tools (evidence: `src/mcp/index.js`)
- MCP Server → Request Pipeline: uses pipeline (evidence: `src/mcp/index.js`)
- Request Pipeline → Context Middleware: injects context (evidence: `src/mcp/pipeline.js`)
- Request Pipeline → Retry Engine: retries calls (evidence: `src/mcp/pipeline.js`)
- Request Pipeline → Smart Router: records outcomes (evidence: `src/mcp/pipeline.js`)
- Request Pipeline → Usage Tracking: estimates tokens (evidence: `src/mcp/pipeline.js`)
- MCP Server → Provider IPC: connects to (evidence: `src/mcp/index.js`)
- Provider IPC → Local Gateway: forwards requests
- Local Gateway → Browser Sessions: routes sessions (evidence: `README.md`)
- Local Gateway → BYOK Router: routes BYOK (evidence: `README.md`)
- BYOK Router → Key Storage: reads keys (evidence: `electron/api/byok/router.cjs`)
- MCP Server → Memory Intelligence: initializes memory (evidence: `src/mcp/index.js`)
- MCP Server → Memory Store: initializes store (evidence: `src/mcp/index.js`)
- Python Agent → Agent Tools: uses tools
- Python Agent → Memory Intelligence: uses cross-session memory (evidence: `README.md`)
- Agent Web Server → Web State DB: uses database (evidence: `proxima-agent/proxima_agent/web/server.py`)
- Command Line → Local Gateway: controls local gateway
- Client SDKs → Local Gateway: calls local endpoint