Architecture: How Ratelord Works

Ratelord is a local-first, predictive control plane that sits between your agents and external APIs. The architecture is organized around a single authoritative daemon, immutable event sourcing, and a negotiation protocol that safely allocates resources.

Daemon Authority

The `ratelord-d` daemon is the only process capable of writing state or making decisions. All other clients are read-only observers.

• Single source of truth: Every policy evaluation, grant, and denial is authored by the daemon.
• Read-only clients: CLI, TUI, Web UI, and SDKs only display what the daemon reports.
• Intent-based: Agents describe the action they want to perform; the daemon evaluates risk before allowing it.

Event Sourcing & Replayability

The architecture is backed by an append-only event log. Every observation, decision, and policy change becomes an event, which can always be replayed to rebuild the system state.

1. Event log: Immutable history of every provider poll, intent negotiation, and policy evaluation.
2. Replay: Restarting the daemon replays the log to reconstruct the current constraint graph.
3. Projections: Materialized views derived from the log keep queries fast (e.g., current usage, pool health).

Prediction & Risk Modeling

Ratelord thinks in time, not just counts. Forecasts and burn rates help agents avoid imminent exhaustion.

• Time-to-Exhaustion (TTE): Estimates how long before a pool hits zero at the current burn rate.
• Probability scores: Tracks the risk of exceeding a limit before the next reset window.
• Forecast-aware decisions: The daemon can counter, shape, or deny intents when the risk is too high.

Intent Negotiation Workflow

Agents never grab capacity; they negotiate it through a deterministic protocol.

1. Propose: Agent submits the desired action (`POST /v1/intent`).
2. Evaluate: The daemon checks pools, forecasts, policies, and priorities.
3. Decide: Responds with `approve`, `deny_with_reason`, or `approve_with_modifications` (e.g., wait or throttle).

Primary Components

Ratelord Daemon

• Polls providers (GitHub, OpenAI, etc.) for limit data.
• Enforces policies and writes every event to the log.
• Serves the HTTP API that agents and clients call.

Storage

Local deployments default to SQLite (with WAL mode). For HA, Redis can back shared state across federated leaders and followers.

Clients & UIs

• HTTP API: Programmatic access via `/v1` endpoints.
• TUI: Terminal UI for operators to inspect intents and forecasts.
• Web UI: Dashboards that render the constraint graph, timelines, and health metrics.