Ratelord
GitHub
HomeDocumentation

System Architecture

Ratelord is designed as a modular, event-sourced system that sits between your agents and the external APIs they consume.

Core Components

1. The Daemon

The heart of Ratelord is a lightweight, zero-ops daemon written in Go. It acts as the single source of truth for all constraint states. It is responsible for:

  • Ingesting Intents: Receiving resource requests from agents.
  • Policy Enforcement: Checking requests against defined constraints.
  • State Management: Maintaining the current state of all budgets and rate limits.
  • Forecasting: Predicting when resources will be exhausted or replenished.

2. Storage Layer

Ratelord uses an event-sourced architecture.

  • Event Log: An append-only log of all state changes (IntentCreated, BudgetAllocated, LimitHit).
  • Snapshots: Periodic snapshots of the state to ensure fast startup times.
  • SQLite (Default): For local development and single-node deployments, embedded SQLite is used for zero-conf persistence.

3. Providers

Providers are adapters that interface with external services to fetch real-time usage data.

  • GitHub Provider: Tracks API rate limits, secondary rate limits, and graphQL node limits.
  • Mock Provider: Used for testing and simulation.

4. Clients

Ratelord exposes its functionality through multiple interfaces:

  • HTTP API: For programmatic access by agents.
  • TUI (Terminal UI): For operators to monitor the system in real-time.
  • Web UI: For dashboard-style visualization and configuration.