Architecture

Overview

Coldrune is a single Rust binary with an embedded SQLite database. No external services are required for core operation.

┌──────────────────────────────────────────────────┐
│                 Coldrune Binary                   │
│                                                   │
│  ┌───────────┐  ┌──────────┐  ┌───────────────┐  │
│  │  HTTP API  │  │ Maintena │  │ Backup Worker │  │
│  │   (Axum)   │  │  Worker  │  │  (optional)   │  │
│  └─────┬──────┘  └────┬─────┘  └──────┬────────┘  │
│        │              │               │            │
│        └──────────────┼───────────────┘            │
│                       │                            │
│              ┌────────┴────────┐                   │
��              │  SQLite (WAL)   │                   │
│              └─────────────────┘                   │
└──────────────────────────────────────────────────┘
         │                            │
    ┌────┴─────┐               ┌─────┴──────┐
    │  SMTP    │               │  S3 Storage │
    │ (email)  │               │  (backups)  │
    └──────────┘               └────────────┘

Data model

Organization (tenant boundary)
  ├── Members (user + role)
  ├── Service Accounts (API keys)
  ├── ACL Rules (access patterns)
  ├── Audit Logs (immutable trail)
  └── Projects
        └── Environments (dev, staging, prod, ...)
              └── Secrets (encrypted key-value pairs)

All entities use UUIDs as primary keys. Soft deletes via removed_at timestamp.

Request flow

1. Request hits reverse proxy (nginx/Caddy) — TLS terminated, rate limited, X-Real-Ip set
2. Axum receives the request on 127.0.0.1:7100
3. Auth middleware extracts the caller:
   • Authorization: Bearer <token> → session lookup → AuthUser
   • X-API-Key: cr_sa_... → hash lookup → ServiceAccount
   • Both wrapped in a Caller enum for handlers that accept either
4. Route handler validates input, checks org membership + role
5. For secret operations: ACL check against project/env patterns
6. Handler executes the operation
7. Audit log entry written (fire-and-forget — failures don’t block the response)
8. JSON response returned

Background workers

Maintenance worker

Runs every hour, unconditionally:

• Deletes expired sessions (older than 30 days)
• Deletes used/expired magic links (older than 1 hour, preserving the lockout window)

Backup worker

Runs on a configurable interval (BACKUP_SCHEDULE_HOURS). Disabled when set to 0 or when S3 is not configured.

• Creates an encrypted database snapshot
• Uploads to S3
• Runs retention cleanup (daily + weekly policy)

Database

SQLite in WAL (Write-Ahead Logging) mode for concurrent read access.

Key characteristics:

• File permissions set to 0600 (owner-only) on Unix
• PRAGMA foreign_keys = ON enforced per connection
• All foreign keys use ON UPDATE RESTRICT ON DELETE RESTRICT
• Migrations embedded at compile time, run on startup
• Partial unique indexes enable name reuse after soft deletion

API error format

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human readable description"
  }
}

Error codes use SCREAMING_SNAKE_CASE. Internal details are never leaked to clients.

Two modes

The coldrune binary operates in two modes:

• Server mode (coldrune server start) — runs the HTTP API, accesses the database directly
• Client mode (coldrune <command>) — a pure HTTP client that talks to the server’s REST API

The CLI never touches the database. All operations go through the HTTP API. Exception: coldrune server rotate-key accesses the database directly for offline key rotation.