🏗️ 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
│   ├── pipeline.go       # Transformer orchestration, streaming
│   └── 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
│   ├── anthropic_image_fix.go # Image extraction from tool results
│   └── streaming.go      # SSE parsing and chunk transformation
│
├── 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)
│   └── embed.go          # Embedded web UI via //go:embed
│
├── middleware/            # Bearer-token auth for admin API
│   └── auth.go
│
├── 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)
└────────┬────────┘
         │
┌────────▼────────┐
│ 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. Response      │  ← Execute response transformers sequentially
│    Pipeline      │     Non-streaming: full body transform
│                   │     Streaming (SSE): event-by-event transform
└────────┬────────┘
         │
┌────────▼────────┐
│ 9. Return to     │  ← Final response to client
│    Client        │
└──────────────────┘

📡 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

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

🏠 Default Seeds

When no downstreams, rules, or aliases are defined in YAML, Tresor seeds three default downstreams:

ID	Name	Base URL	Models
openai-gpt4o	OpenAI GPT-4o	https://api.openai.com/v1	gpt-4o, gpt-4o-mini, gpt-3.5-turbo
anthropic-sonnet	Anthropic Claude Sonnet	https://api.anthropic.com	claude-sonnet-4-20250514
anthropic-haiku	Anthropic Claude Haiku	https://api.anthropic.com	claude-haiku-4.5

Along with default alias groups for gpt-4o and claude-sonnet.

🌐 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 the configured admin_password Bearer token. See the individual documentation pages for downstream, rule, alias, and config endpoints.

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)
PUT	/api/config	Update runtime settings live (pushes changes to running engine + auth middleware, writes back to YAML)