How adamkessler/switchmaxxer works
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: config.ts Config Core · service.ts Obs Service · app-cli-runtime.ts CLI Runtime · bootstrap.ts Bootstrap
Components 20
Shared State
Split config, catalog, and local secrets used by all surfaces
- Config Core · Validation, normalization, mutation locking, import/export, and read/write flows
src/subsystems/config/config.ts - Catalog · Models, service providers, and routes split into catalog.json
src/subsystems/config/catalog.ts - 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 · Process bootstrap and top-level startup wiring
src/index.ts - Bootstrap · Shared application startup and surface selection
src/bootstrap.ts - CLI App · CLI process entry and command wiring
src/app-cli.ts - CLI Runtime · CLI adapters over shared command and mutation services
src/subsystems/cli/app-cli-runtime.ts - CLI Commands · Gateway, config, invoke, routes, models, providers, optimize, prune, trace, bench, and ledger commands
src/subsystems/cli/commands - MCP Runtime · MCP tools and session dispatch aligned with CLI contracts
src/subsystems/mcp/mcp.ts - MCP Tools · Config, gateway, routes, observability, benchmark, and optimize tools
src/subsystems/mcp/tools.ts
Gateway
Local HTTP data plane and runtime control
- Gateway Runtime · Local server lifecycle, request routing, runtime config, status, and reload handling
src/subsystems/gateway/runtime.ts - Request Handler · OpenAI and Anthropic compatible inbound request handling and route dispatch
src/subsystems/gateway/runtime-request-handler.ts - Auth & Limits · 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 · Observations, traces, benchmarks, optimize runs, audits, snapshots, and ledger storage
src/subsystems/observability/service.ts - SQLite Store · SQLite-backed persistence layer and schema/runtime loading
src/subsystems/observability/store.ts - Optimize · Cost and latency optimization, apply/restore, and snapshot-backed mutation flow
src/subsystems/observability/optimize-orchestrator.ts - Prune · Retention and cleanup across observability records and ledger data
src/subsystems/observability/prune-service.ts
Proxy
Provider translation and upstream boundary
- Proxy Core · Outbound translation, forwarding, buffering, and upstream error classification
src/subsystems/proxy/proxy-core.ts - Dialect Adapter · OpenAI-to-Anthropic and Anthropic-to-OpenAI request/response translation
src/subsystems/proxy/proxy-translation.ts - Upstream Transport · HTTP transport, upstream URL construction, and provider endpoint policy
src/subsystems/proxy/http-transport.ts
Connections 26
- 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