🏗️ Architecture

Tresor follows a clean layered structure with three core concerns: storage, engine, and API. The codebase is written in Go with no external web framework — it uses net/http ServeMux directly for all routing.

📁 Directory Structure

cmd/                        # CLI entry points (Cobra)
├── root.go                # Root command, --config flag
├── run.go                 # Daemon startup
├── rule.go                # Rule & alias subcommands
└── version.go             # Version display

internal/
├── config/                # YAML configuration loader with auto-detect
│   └── config.go
│
├── store/                 # SQLite data layer + upsert logic
│   ├── store.go          # Schema creation, migrations, busy timeout
│   ├── rule.go           # Rule CRUD + pattern matching
│   ├── downstream.go     # Downstream CRUD + model management
│   ├── alias.go          # Alias CRUD + group operations
│   └── write_config.go   # YAML write-back on mutation
│
├── engine/                # Core gateway handler + pipeline execution
│   ├── engine.go         # Gateway forwarding, model resolution, auth, auto-translation, retry on empty response
│   ├── pipeline.go       # Transformer orchestration, streaming
│   ├── retry.go          # Empty response detection + retry with exponential backoff
│   └── types.go          # Interfaces (RequestTransformer, etc.)
│
├── plugins/               # Plugin registry + built-in transformers
│   ├── registry.go       # Plugin registration and lookup
│   ├── custom_header.go  # Header injection plugin
│   ├── openai2anthropic.go # OpenAI → Anthropic format conversion
│   ├── anthropic2openai.go # Anthropic → OpenAI format conversion
│   ├── openai2responses.go # OpenAI Chat Completions → Responses API
│   ├── anthropic2responses.go # Anthropic Messages → Responses API
│   ├── responses2openai.go # Responses API → OpenAI Chat Completions
│   ├── responses2anthropic.go # Responses API → Anthropic Messages
│   ├── anthropic_image_fix.go # Image extraction from tool results
│   ├── anthropic_usage_fix.go # Anthropic usage block normalization (MiniMax-M3 etc.)
│   ├── openai2gemini.go   # OpenAI → Gemini format conversion
│   ├── anthropic2gemini.go # Anthropic → Gemini format conversion
│   ├── gemini2openai.go   # Gemini → OpenAI format conversion
│   ├── gemini2anthropic.go # Gemini → Anthropic format conversion
│   ├── gemini2responses.go # Gemini → Responses API conversion
│   ├── streaming.go      # SSE parsing and chunk transformation
│   └── streaming_test.go # Comprehensive streaming transform tests
│
├── api/                   # Admin REST API + embedded web UI
│   ├── router.go         # Route registration, method enforcement, auth endpoints
│   ├── rules.go          # Rule endpoints
│   ├── downstreams.go    # Downstream endpoints + plugins list + fetch-models
│   ├── aliases.go        # Alias endpoints + group operations
│   ├── config.go         # Runtime config endpoints (proxy mode, auth keys, password, default tab, retry on empty)
│   ├── icons.go          # Model icon serving (public endpoint)
│   ├── icons_admin.go    # Icon index refresh (admin endpoint)
│   └── embed.go          # Embedded web UI via //go:embed
│
├── middleware/            # Cookie-based session auth for admin API
│   └── auth.go
│
├── icons/                 # Model icon fetching, pattern matching, CDN caching
│   ├── fetcher.go        # Icon fetching and caching
│   ├── index.go          # CDN index management
│   ├── patterns.go       # Model-to-icon pattern matching
│   └── ratelimit.go      # Rate limiting for icon fetcher
│
├── inspect/              # Bounded in-memory store for captured request/response bodies
│   └── store.go          # Inspect store for Logs inspector
│
├── proxy/                 # Outbound proxy mode implementation
│   ├── proxy.go          # Mode resolution (auto/env/windows/none)
│   └── system_windows.go # Windows registry proxy reading
│
└── api/web/               # Embedded SPA
    ├── index.html
    ├── style.css
    └── app.js

e2e/                       # End-to-end integration tests
main.go                    # Binary entry point

🛠️ Technology Stack

Concern	Choice	Reason
Language	Go 1.26+	Fast compilation, cross-platform CLI, native concurrency
Router	net/http ServeMux	No external framework dependency
CLI Framework	cobra	De facto standard for Go CLI applications
Database	modernc.org/sqlite	Pure Go SQLite — no CGO dependency
Config	YAML	Human-readable, portable, version-controllable
Web UI	Embedded via //go:embed	No separate frontend deployment needed

🔄 Request Flow

Client Request
      │
      ▼
┌──────────────────┐
│ 1. Auth Check     │  ← Validate proxy_api_keys if configured
└────────┬─────────┘
         │
┌────────▼────────┐
│ 2. Model Extract │  ← Parse model name from request body
└────────┬────────┘
         │
┌────────▼────────┐
│ 3. Model Resolve │  ← The forwarding gate:
│                   │     • Active exact alias? → use alias downstream, rewrite model
│                   │     • Active regex alias? → pattern match, use downstream, rewrite
│                   │     • No alias? → find downstream by output_model_ids
│                   │     • Neither? → return 404 "unknown model"
└────────┬────────┘
         │
┌────────▼────────┐
│ 4. Rule Match    │  ← Collect ALL matching enabled rules (path+model)
│                   │     Priority: exact path+model > exact path > wildcard *
│                   │     Filter by: match_format, match_downstream_format,
│                   │     match_downstreams. Rules never override downstream.
│                   │     Pipelines from all matching rules are concatenated.
└────────┬────────┘
         │
┌────────▼────────┐
│ 5. Auto-         │  ← If request format != downstream api_formats,
│    Translation   │     automatically insert format converter (prepended/
│                   │     appended around rule pipelines)
│                   │     Supports: OpenAI Chat Completions, Anthropic Messages,
│                   │     OpenAI Responses API
└────────┬────────┘
         │
┌────────▼────────┐
│ 6. Request       │  ← Execute request transformers sequentially
│    Pipeline      │     (body + headers may change)
└────────┬────────┘
         │
┌────────▼────────┐
│ 7. Forward       │  ← Send transformed request to downstream server
│    to Downstream │     Strip client auth, inject downstream API key
└────────┬────────┘
         │
┌────────▼────────┐
│ 8. Retry on     │  ← (if retry_on_empty is enabled)
│    Empty        │     If downstream returns HTTP 200 but produces no
│    Response     │     content (empty choices, thinking-only output,
│                 │     etc.), retry up to 3 times with exponential
│                 │     backoff. Retries are transparent to the client.
└────────┬────────┘
         │
┌────────▼────────┐
│ 9. Response      │  ← Execute response transformers sequentially
│    Pipeline      │     Non-streaming: full body transform
│                   │     Streaming (SSE): event-by-event transform
└────────┬────────┘
         │
┌────────▼────────┐
│ 10. Return to    │  ← Final response to client
│    Client        │
└──────────────────┘

Retry

When retry_on_empty: true is set in the config, the gateway automatically retries downstream requests that return HTTP 200 OK but produce no useful content. This protects against scenarios where:

• The downstream LLM server accepts the request but produces no text output (transient server-side issues)
• A model generates only "thinking" or "reasoning" blocks without actual text content
• The response is garbled or empty for other reasons

How it works:

• Only retries on HTTP 200 with empty content. Non-200 responses (4xx, 5xx) are never retried — LLM client SDKs handle their own retry logic for HTTP errors.
• Maximum 3 retries with exponential backoff (500ms, 1s, 2s base) and 0–25% random jitter.
• Streaming responses: A bufferedWriter holds all SSE events until content is confirmed. When the first content-producing line is detected (text, tool calls, etc.), the buffer flushes to the client. If no content arrives, the stream is discarded and retried.
• Non-streaming responses: The full body is read, response transformers are applied, then the format-specific empty check runs. Empty bodies are discarded and retried.
• Empty detection per format:
  • OpenAI Chat Completions: Empty choices, or no text/tool_calls/refusal in both message and delta fields
  • Anthropic Messages: Empty content array, or blocks containing only thinking (no text, no tool_use)
  • OpenAI Responses: Empty output array, or message items with no output_text
  • Google Gemini: Empty candidates, or parts with no text/functionCall (parts with thought:true excluded)
• Transparent to client: The client sees nothing during retries. Only the final successful response is delivered.
• Exhaustion: If all retries are exhausted, the gateway returns HTTP 502 with error "empty response after retries exhausted".
• Client disconnection during retry aborts the loop immediately.

📡 Aggregated Model List

Tresor exposes /v1/models and /models endpoints that aggregate all known model IDs from downstream output_model_ids and alias input/output model IDs. Regex aliases are excluded from the input model ID list since they represent patterns rather than concrete model names. The response is formatted as an OpenAI-style model list, so OpenAI-compatible clients can discover available models through Tresor.

💾 Data Layer

🗄️ SQLite Schema

The database uses WAL mode with a 5000ms busy timeout. Four tables:

downstreams — Provider endpoints

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
name	TEXT NOT NULL	Display name
base_url	TEXT NOT NULL	API base URL
api_key	TEXT NOT NULL	Authentication key
api_formats	TEXT (JSON)	API format(s) this downstream speaks
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

output_model_ids — Model-to-downstream mapping

Column	Type	Description
downstream_id	TEXT REFERENCES downstreams	Foreign key
model_id	TEXT	Model identifier

(Composite unique on both columns)

rules — Conditional transform pipelines with format-aware matching

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
name	TEXT NOT NULL	Display name
pattern_path	TEXT NOT NULL	URL path to match
pattern_model	TEXT	Optional model filter
match_format	TEXT (JSON)	Input request formats to match
match_downstream_format	TEXT (JSON)	Downstream API formats to match
match_downstreams	TEXT (JSON)	Downstream IDs to match
pipeline_config	TEXT (JSON)	Ordered plugin list
is_enabled	INTEGER	Toggle (0/1)
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

aliases — Model name mappings

Column	Type	Description
id	TEXT PRIMARY KEY	Unique identifier
input_model_id	TEXT NOT NULL	Client-facing model name (group key)
downstream_id	TEXT NOT NULL REFERENCES downstreams	Target provider
output_model_id	TEXT NOT NULL	Actual model to forward as
is_active	INTEGER DEFAULT 0	Active flag (one per group)
is_regex	INTEGER DEFAULT 0	Treat input_model_id as a regex pattern
group_order	INTEGER DEFAULT 0	Display order for group reordering
created_at	DATETIME	Creation timestamp
updated_at	DATETIME	Last update timestamp

sessions — Active admin sessions (multi-session support)

Column	Type	Description
token	TEXT PRIMARY KEY	Session token (UUID)
created_at	DATETIME	Session creation timestamp

Indexes on foreign keys and query patterns ensure efficient lookups. Regex patterns are cached (via sync.Map) to avoid recompilation on every request.

🔄 Upsert Semantics

On startup, YAML data is merged into the database:

• Downstreams: Matched by ID — updated if exists, inserted if new. api_formats carried over.
• Rules: Matched by ID — updated if exists, inserted if new. match_format, match_downstream_format, match_downstreams serialized as JSON arrays.
• Aliases: Special logic — runtime-active aliases not in YAML are preserved (protects hot-switched state); stale YAML aliases not matching DB are deleted; new YAML aliases are created
• Model IDs: All YAML models replace existing ones for each downstream

Rows that exist only in the database (created via web UI or API) are preserved.

💥 Cascade Delete

Deleting a downstream:

• Removes the downstream ID from match_downstreams arrays on all referencing rules
• Deletes all aliases pointing to that downstream

🌐 Admin API

Public Endpoints (no auth required)

Method	Path	Purpose
GET	/api/health	Health check
GET	/api/auth/status	Check whether auth is enabled
POST	/api/auth/login	Verify password, obtain session
GET	/api/version	Binary version and build time

Protected Endpoints

All other /api/* endpoints require authentication. The admin API uses cookie-based session authentication with multi-session support: after logging in via POST /api/auth/login, a session cookie (tresor_token, Path=/api/, HttpOnly, SameSite=Lax, 365-day expiry) is issued. Multiple simultaneous sessions are supported — logging in from a second browser doesn't invalidate the first. Logging out from one browser only clears that session; others remain active. Authenticated requests send the cookie (for browser/SSE) or use it as a Bearer header. CLI commands use the raw admin_password as Bearer token (backwards compat). Session tokens persist across daemon restarts (stored in SQLite). Login is rate-limited (5 attempts per 60s per IP). Changing the admin password clears all active sessions.

Key alias endpoints include POST /api/aliases/reorder for drag-and-drop group reordering, which accepts {"order": ["gpt-4o", "claude-sonnet"]}.

Log Endpoints

Method	Path	Purpose
GET	/api/logs	Get recent log entries (newest first, filtered by log level)
GET	/api/logs/stream	SSE stream of log entries (sends initial batch + live updates)
GET	/api/log_level	Get current log level
PUT/POST	/api/log_level	Update log level

Runtime Configuration Endpoint

Method	Path	Purpose
GET	/api/config	Get current runtime settings (proxy mode, proxy keys, password status, default tab, log level, retry on empty)
PUT	/api/config	Update runtime settings live (pushes changes to running engine + auth middleware, writes back to YAML)