# adamkessler/switchmaxxer architecture

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

- Interactive diagram: https://gitdiagram.com/adamkessler/switchmaxxer
- Repository: https://github.com/adamkessler/switchmaxxer

## Overview

1. Switchmaxxer is a TypeScript/Node 22+ repository with three primary runtime surfaces: a long-lived local gateway, a CLI control plane, and an MCP control plane for agents. The gateway is the data plane; CLI and MCP are management surfaces that talk to the same configuration and observability state.

2. The central architectural boundary is the split config model: `config.json` holds runtime/security/gateway/observability settings, while sibling `catalog.json` holds `models`, `service_providers`, and `routes`. Optional local secrets live separately in owner-only secrets files or environment variables. This split is fundamental to the repo’s data flow and to how CLI/MCP mutations persist.

3. The gateway subsystem is the core HTTP server. It listens locally by default, exposes OpenAI-compatible `/v1/chat/completions` and Anthropic-compatible `/anthropic/v1/messages`, resolves a client-supplied route name to a catalog entry, applies route policy, authenticates requests, rate-limits them, and forwards to the selected upstream provider. It also exposes health, runtime config, status, reload, and service-control-related surfaces.

4. The proxy subsystem sits behind the gateway as the provider-facing translation layer. It adapts request/response dialects between OpenAI and Anthropic shapes, handles streaming translation and buffering, classifies upstream errors, and enforces provider endpoint policy. This is the main outbound boundary to external LLM APIs such as OpenAI, Anthropic, Gemini, Grok, MiniMax, and OpenRouter.

5. The CLI subsystem is the operator interface. It wires commands into shared runtime services for gateway lifecycle, config inspection/mutation, entity CRUD, direct invocation, route testing, logs, tracing, benchmarking, optimization, and pruning. It is not a separate business logic stack; most commands are thin adapters over shared subsystem code.

6. The MCP subsystem is the agent-facing mirror of the CLI. It exposes tools for the same control-plane capabilities: config, gateway, routes/models/providers, observability, benchmark runs, optimize runs, and privileged ledger operations. The repo explicitly treats CLI and MCP as aligned surfaces over the same underlying contracts and payload builders.

7. Observability is a first-class local subsystem backed by SQLite via Node’s built-in `node:sqlite`. It persists observations, traces, benchmark runs, optimize runs, config mutation audits, snapshots, and ledger events. The flow described in the repo is: observations → traces → benchmark runs → optimize runs → ledger events, with retention/prune operations able to clean the whole store.

8. Optimization is layered on top of observability and config mutation. Cost optimization uses catalog rate cards and token workloads; latency optimization reuses benchmark execution. Apply/restore actions are explicit config mutations backed by snapshots and audit records, so optimization is both a recommendation engine and a controlled write path.

9. Configuration management is a distinct subsystem with validation, normalization, redaction, import/export, and mutation locking. It rejects unknown keys, enforces file permission posture, and writes catalog changes back to the split config files. This subsystem is shared by gateway startup/reload and by CLI/MCP mutation commands.

10. The shared platform layer contains cross-cutting utilities that affect multiple boundaries: error-envelope shaping, secret redaction/masking, HTTP JSON helpers, request IDs, rate-limit windows, object-key and JSON-bound policies, env loading, numeric parsing, and type guards. These are the glue that keeps CLI, gateway, MCP, and observability behavior contract-consistent.

11. Runtime state and OS integration matter here: the gateway can be managed as a `systemd --user` service, and log inspection prefers journald/systemd output. The repo also includes local-only safeguards around loopback binding, unauthenticated access toggles, and inbound API-key enforcement, which are part of the gateway’s security boundary rather than a generic app concern.

12. Tests and scripts act as architectural contract enforcement. Unit tests cover platform and subsystem logic; shell integration tests exercise CLI, gateway, MCP, streaming, auth, logging, and observability contracts end to end. CI and repository scripts reinforce boundaries such as built output, secret leakage, docs links, and error-code coverage.

13. For an architecture diagram, the cleanest layout is: clients and agents on the left; CLI/MCP control plane in the center; gateway/data plane in the middle-right; proxy translation to external LLM providers on the far right; and a local SQLite observability store beneath the control plane and gateway, with config/catalog/secrets as the shared local state foundation.

Main entry points: [`src/subsystems/config/config.ts`](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/config.ts) (Config Core), [`src/subsystems/observability/service.ts`](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/service.ts) (Obs Service), [`src/subsystems/cli/app-cli-runtime.ts`](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/cli/app-cli-runtime.ts) (CLI Runtime), [`src/bootstrap.ts`](https://github.com/adamkessler/switchmaxxer/blob/main/src/bootstrap.ts) (Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_shared["Shared State"]
  node_config_core["Config Core<br/>config management<br/>[config.ts]"]
  node_catalog_core["Catalog<br/>[catalog.ts]"]
  node_secrets_core["Secrets<br/>[secrets.ts]"]
end

subgraph group_control["Control Plane"]
  node_src_index(("Entry<br/>[index.ts]"))
  node_src_bootstrap["Bootstrap<br/>startup wiring<br/>[bootstrap.ts]"]
  node_src_app_cli(("CLI App<br/>cli entrypoint<br/>[app-cli.ts]"))
  node_cli_runtime["CLI Runtime<br/>cli control plane<br/>[app-cli-runtime.ts]"]
  node_cli_commands["CLI Commands<br/>operator commands"]
  node_mcp_runtime["MCP Runtime<br/>agent control plane<br/>[mcp.ts]"]
  node_mcp_tools["MCP Tools<br/>tool surface<br/>[tools.ts]"]
end

subgraph group_gateway["Gateway"]
  node_gateway_runtime["Gateway Runtime<br/>HTTP data plane<br/>[runtime.ts]"]
  node_gateway_request["Request Handler<br/>gateway request flow"]
  node_gateway_auth["Auth & Limits<br/>security boundary<br/>[auth-rate-limit.ts]"]
end

subgraph group_observability["Observability"]
  node_obs_service[("Obs Service<br/>sqlite observability<br/>[service.ts]")]
  node_obs_store[("SQLite Store<br/>local store<br/>[store.ts]")]
  node_obs_optimize["Optimize<br/>recommendation and apply"]
  node_obs_prune["Prune<br/>retention control<br/>[prune-service.ts]"]
end

subgraph group_proxy["Proxy"]
  node_proxy_core["Proxy Core<br/>provider translation<br/>[proxy-core.ts]"]
  node_proxy_translate["Dialect Adapter<br/>shape translation"]
  node_proxy_transport["Upstream Transport<br/>provider boundary<br/>[http-transport.ts]"]
end

node_src_index -->|"starts"| node_src_bootstrap
node_src_bootstrap -->|"wires CLI"| node_cli_runtime
node_src_bootstrap -->|"wires gateway"| node_gateway_runtime
node_src_bootstrap -->|"wires MCP"| node_mcp_runtime
node_src_app_cli -->|"uses"| node_cli_runtime
node_cli_runtime -->|"dispatches"| node_cli_commands
node_mcp_runtime -->|"exposes"| node_mcp_tools
node_cli_runtime -->|"mutates"| node_config_core
node_mcp_runtime -->|"mutates"| node_config_core
node_config_core -->|"reads/writes"| node_catalog_core
node_config_core -->|"loads"| node_secrets_core
node_gateway_runtime -->|"loads/reloads"| node_config_core
node_gateway_runtime -->|"serves"| node_gateway_request
node_gateway_request -->|"enforces"| node_gateway_auth
node_gateway_request -->|"resolves routes"| node_catalog_core
node_gateway_request -->|"forwards"| node_proxy_core
node_proxy_core -->|"adapts"| node_proxy_translate
node_proxy_core -->|"sends upstream"| node_proxy_transport
node_proxy_transport -->|"auth uses"| node_secrets_core
node_gateway_runtime -->|"records"| node_obs_service
node_cli_runtime -->|"reads/writes"| node_obs_service
node_mcp_runtime -->|"reads/writes"| node_obs_service
node_obs_service -->|"persists"| node_obs_store
node_obs_optimize -->|"analyzes"| node_obs_service
node_obs_optimize -->|"applies"| node_config_core
node_obs_prune -->|"cleans"| node_obs_service

click node_src_index "https://github.com/adamkessler/switchmaxxer/blob/main/src/index.ts"
click node_src_bootstrap "https://github.com/adamkessler/switchmaxxer/blob/main/src/bootstrap.ts"
click node_src_app_cli "https://github.com/adamkessler/switchmaxxer/blob/main/src/app-cli.ts"
click node_cli_runtime "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/cli/app-cli-runtime.ts"
click node_cli_commands "https://github.com/adamkessler/switchmaxxer/tree/main/src/subsystems/cli/commands"
click node_mcp_runtime "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/mcp/mcp.ts"
click node_mcp_tools "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/mcp/tools.ts"
click node_config_core "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/config.ts"
click node_catalog_core "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/catalog.ts"
click node_secrets_core "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/secrets.ts"
click node_gateway_runtime "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/runtime.ts"
click node_gateway_request "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/runtime-request-handler.ts"
click node_gateway_auth "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/auth-rate-limit.ts"
click node_proxy_core "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/proxy-core.ts"
click node_proxy_translate "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/proxy-translation.ts"
click node_proxy_transport "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/http-transport.ts"
click node_obs_service "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/service.ts"
click node_obs_store "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/store.ts"
click node_obs_optimize "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/optimize-orchestrator.ts"
click node_obs_prune "https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/prune-service.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_config_core,node_catalog_core,node_secrets_core toneBlue
class node_src_index,node_src_bootstrap,node_src_app_cli,node_cli_runtime,node_cli_commands,node_mcp_runtime,node_mcp_tools toneAmber
class node_gateway_runtime,node_gateway_request,node_gateway_auth toneMint
class node_obs_service,node_obs_store,node_obs_optimize,node_obs_prune toneRose
class node_proxy_core,node_proxy_translate,node_proxy_transport toneIndigo
```

## Components

### Shared State

Split config, catalog, and local secrets used by all surfaces

- [Config Core](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/config.ts): config management · Validation, normalization, mutation locking, import/export, and read/write flows · `src/subsystems/config/config.ts`
- [Catalog](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/catalog.ts): catalog data · Models, service providers, and routes split into catalog.json · `src/subsystems/config/catalog.ts`
- [Secrets](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/config/secrets.ts): local secrets · Owner-only secrets file and environment-backed secret handling · `src/subsystems/config/secrets.ts`

### Control Plane

CLI and MCP operator surfaces plus config management

- [Entry](https://github.com/adamkessler/switchmaxxer/blob/main/src/index.ts): runtime entrypoint · Process bootstrap and top-level startup wiring · `src/index.ts`
- [Bootstrap](https://github.com/adamkessler/switchmaxxer/blob/main/src/bootstrap.ts): startup wiring · Shared application startup and surface selection · `src/bootstrap.ts`
- [CLI App](https://github.com/adamkessler/switchmaxxer/blob/main/src/app-cli.ts): cli entrypoint · CLI process entry and command wiring · `src/app-cli.ts`
- [CLI Runtime](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/cli/app-cli-runtime.ts): cli control plane · CLI adapters over shared command and mutation services · `src/subsystems/cli/app-cli-runtime.ts`
- [CLI Commands](https://github.com/adamkessler/switchmaxxer/tree/main/src/subsystems/cli/commands): operator commands · Gateway, config, invoke, routes, models, providers, optimize, prune, trace, bench, and ledger commands · `src/subsystems/cli/commands`
- [MCP Runtime](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/mcp/mcp.ts): agent control plane · MCP tools and session dispatch aligned with CLI contracts · `src/subsystems/mcp/mcp.ts`
- [MCP Tools](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/mcp/tools.ts): tool surface · Config, gateway, routes, observability, benchmark, and optimize tools · `src/subsystems/mcp/tools.ts`

### Gateway

Local HTTP data plane and runtime control

- [Gateway Runtime](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/runtime.ts): HTTP data plane · Local server lifecycle, request routing, runtime config, status, and reload handling · `src/subsystems/gateway/runtime.ts`
- [Request Handler](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/runtime-request-handler.ts): gateway request flow · OpenAI and Anthropic compatible inbound request handling and route dispatch · `src/subsystems/gateway/runtime-request-handler.ts`
- [Auth & Limits](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/gateway/auth-rate-limit.ts): security boundary · Loopback policy, inbound API-key enforcement, unauthenticated toggle, and rate limiting · `src/subsystems/gateway/auth-rate-limit.ts`

### Observability

SQLite-backed local store for traces, benchmarks, optimizations, and audits

- [Obs Service](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/service.ts): sqlite observability · Observations, traces, benchmarks, optimize runs, audits, snapshots, and ledger storage · `src/subsystems/observability/service.ts`
- [SQLite Store](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/store.ts): local store · SQLite-backed persistence layer and schema/runtime loading · `src/subsystems/observability/store.ts`
- [Optimize](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/optimize-orchestrator.ts): recommendation and apply · Cost and latency optimization, apply/restore, and snapshot-backed mutation flow · `src/subsystems/observability/optimize-orchestrator.ts`
- [Prune](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/observability/prune-service.ts): retention control · Retention and cleanup across observability records and ledger data · `src/subsystems/observability/prune-service.ts`

### Proxy

Provider translation and upstream boundary

- [Proxy Core](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/proxy-core.ts): provider translation · Outbound translation, forwarding, buffering, and upstream error classification · `src/subsystems/proxy/proxy-core.ts`
- [Dialect Adapter](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/proxy-translation.ts): shape translation · OpenAI-to-Anthropic and Anthropic-to-OpenAI request/response translation · `src/subsystems/proxy/proxy-translation.ts`
- [Upstream Transport](https://github.com/adamkessler/switchmaxxer/blob/main/src/subsystems/proxy/http-transport.ts): provider boundary · HTTP transport, upstream URL construction, and provider endpoint policy · `src/subsystems/proxy/http-transport.ts`

## Connections

- Entry → Bootstrap: starts · Process entry delegates to bootstrap
- Bootstrap → CLI Runtime: wires CLI · Bootstraps operator command surface
- Bootstrap → Gateway Runtime: wires gateway · Bootstraps long-lived data plane server
- Bootstrap → MCP Runtime: wires MCP · Bootstraps agent-facing control plane
- CLI App → CLI Runtime: uses · CLI entry runs through runtime adapters
- CLI Runtime → CLI Commands: dispatches · Commands are thin adapters over shared services
- MCP Runtime → MCP Tools: exposes · MCP presents tool equivalents of CLI capabilities
- CLI Runtime → Config Core: mutates · CLI config commands validate and persist changes
- MCP Runtime → Config Core: mutates · MCP config tools share the same mutation contracts
- Config Core → Catalog: reads/writes · Catalog state is the sibling config file
- Config Core → Secrets: loads · Secret references resolve from files or env
- Gateway Runtime → Config Core: loads/reloads · Gateway startup and reload depend on validated config
- Gateway Runtime → Request Handler: serves · Runtime exposes request handling pipeline
- Request Handler → Auth & Limits: enforces · Inbound policy and rate limiting happen before forwarding
- Request Handler → Catalog: resolves routes · Client route names map to catalog entries
- Request Handler → Proxy Core: forwards · Requests are translated and sent upstream
- Proxy Core → Dialect Adapter: adapts · Provider dialect translation occurs in the proxy layer
- Proxy Core → Upstream Transport: sends upstream · Outbound transport reaches external LLM APIs
- Upstream Transport → Secrets: auth uses · Provider credentials and secrets feed upstream requests
- Gateway Runtime → Obs Service: records · Gateway observations and traces are written to observability
- CLI Runtime → Obs Service: reads/writes · CLI reads history and runs maintenance or audit operations
- MCP Runtime → Obs Service: reads/writes · MCP tools mirror observability operations
- Obs Service → SQLite Store: persists · Service layer sits on SQLite store and schema
- Optimize → Obs Service: analyzes · Optimization consumes stored observations and benchmark data
- Optimize → Config Core: applies · Apply/restore actions become controlled config mutations
- Prune → Obs Service: cleans · Prune operations trim the shared local store
