Krono

A deterministic environment for testing trading bots under real execution constraints

Krono is built around a simple idea:

trading systems usually fail not in signal generation, but at the boundary between strategy logic and execution reality.

It is designed to make that boundary explicit, testable, and observable through deterministic replay, controlled sessions, runtime separation, and live inspection.

Rather than focusing only on what a strategy predicts, Krono focuses on how a bot behaves once timing, execution rules, replay conditions, and operational constraints become part of the system.

flowchart LR
    subgraph Strategy["User Strategy Domain"]
        Bot["Strategy Logic / Bot Code<br/>(Signals & Decisions)"]
    end

    subgraph Boundary["Runtime Boundary"]
        Pulse["Pulse Runtime<br/>(Execution Adapter & Telemetry)"]
    end

    subgraph Source["External Source"]
        ExternalAPI["External Market API<br/>(Historical & Reconcile Data)"]
    end

    subgraph Simulation["Simulation Plane"]
        direction TB
        Engine["Krono Engine (Rust)<br/>Sessions, Replay, Orders & Runs"]
        EngineDB[("Engine PostgreSQL<br/>Users, Sessions, Runs, Usage")]
    end

    subgraph Market["Market Data Plane"]
        direction TB
        MD["Market Data Service<br/>Datasets, aggTrades & Klines"]
        MarketDB[("Market Data PostgreSQL<br/>Historical Market Storage")]
    end

    subgraph Control["Control & Analysis Plane"]
        direction TB
        UI["Control Surface<br/>(Next.js Operator UI)"]
        Chart["Chart Service / Chart UI<br/>Candles & Market Views"]
    end

    Bot <==>|Strategy callbacks & decisions| Pulse
    Pulse <==>|Streams, signed commands & telemetry| Engine
    ExternalAPI -->|Market data imports| MD
    MD -->|Ordered market data| Engine
    Engine <--> EngineDB
    MD <--> MarketDB
    UI <==>|Control APIs & live telemetry| Engine
    MD -->|Candles and snapshots| Chart

    classDef default fill:#111113,stroke:#3f3f46,stroke-width:1px,color:#e4e4e7;
    classDef highlight fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
    classDef boundary fill:none,stroke:#10b981,stroke-width:2px,stroke-dasharray: 5 5;
    
    class Pulse highlight;
    class Boundary boundary;

Loading

---

Why Krono Exists

Traditional backtesting often hides the part that matters most in practice.

A strategy may look convincing in isolation and still break down because of:

• timing drift between market data and decisions
• unrealistic execution assumptions
• inconsistent replay conditions across runs
• weak traceability from results back to orders and events
• poor visibility into runtime health and degraded behavior

Krono was built to make those failure points visible, controllable, and auditable.

---

What Krono Is

Krono is a trading systems environment centered on deterministic simulation.

It combines:

• replay of preloaded historical market datasets under explicit session rules
• execution-aware bot interaction through a runtime boundary
• live telemetry and run-linked observability
• comparative analysis across runs, bots, configurations, and contexts

The goal is not to replay charts for visual convenience.
The goal is to evaluate trading systems where execution behavior, runtime conditions, and replay control actually matter.

---

Tech Stack

Krono is built as a multi-service system with explicit boundaries between simulation, runtime control, market data, charting, and the operator UI.

Area	Stack	Role
Simulation Engine & Core API	Rust, Axum, Tokio, PostgreSQL, WebSockets, OpenAPI	Deterministic replay, session lifecycle, bot binding, execution-aware runs, authentication, admin controls, and usage enforcement
Market Data Services	Rust, Axum, Tokio, PostgreSQL, WebSockets	Historical dataset access, candle and aggTrade query surfaces, chart feeds, and bot trade overlays
Control Surface	Next.js, React, TypeScript, Tailwind CSS, TanStack Query, Recharts, Radix/shadcn-style components	Internal product UI for sessions, bots, live telemetry, analytics, admin workflows, and run comparison
Auth, Admin & Limits	JWT, Argon2, RBAC, workspace ownership, configurable plan limits	SaaS-style user isolation, superadmin workflows, usage tracking, and quota enforcement
Local Infrastructure	Docker Compose, environment-based configuration, migrations, seeded demo data	Reproducible local development across independent services

The stack is split by responsibility:

• Rust services handle latency-sensitive simulation, replay, streaming, and core business workflows.
• The frontend is a product-grade operator interface, not just a demo dashboard.
• PostgreSQL is used as the source of truth for sessions, users, plans, usage, datasets, and operational state.
• Service boundaries are explicit so simulation, market data, charting, and UI concerns can evolve independently.

---

What You Can Do With It

With Krono, you can:

• create sessions from preloaded historical datasets
• define replay windows and session behavior
• launch, pause, resume, and stop simulation sessions
• connect bots through a clean runtime layer instead of embedding exchange plumbing into strategy code
• run multiple bot instances under different configurations or deployment contexts
• inspect orders, trades, run history, and session state
• observe live telemetry while a session is active
• compare runs across bots, configs, and operational contexts

---

Core Pieces

Component	Role
Krono Engine	Deterministic simulation core for sessions, replay, execution behavior, runs, and bot state
Pulse	Runtime layer that separates strategy logic from execution infrastructure
Control Surface	UI for sessions, bots, lifecycle control, telemetry, and run inspection
Chart / Analysis Layer	Visual analysis of market behavior
Market Data Service	Admin-managed historical datasets and market query surfaces shared across simulation and charting

This separation keeps simulation, runtime, control, and observability explicit instead of collapsing everything into one opaque application.

---

Pulse: the Runtime Boundary

A key part of the environment is Pulse, the open-source runtime layer for running bots reliably.

Pulse introduces a strict separation:

• You write the strategy
• Pulse handles the runtime concerns

That includes connectivity, retries, event delivery, execution plumbing, and runtime health monitoring.

This boundary matters because it keeps strategy code focused on decisions while making execution infrastructure portable across simulation and future live-oriented environments.

flowchart LR
    subgraph User["User Responsibility"]
        Strategy["Trading Strategy<br/>(Math, Signals & Position Sizing)"]
    end

    subgraph Boundary["Pulse Runtime Boundary"]
        Pulse["Pulse Adapter<br/>(Plumbing, Retries & Telemetry)"]
    end

    subgraph Infra["Execution Infrastructure"]
        Engine["Krono Engine / Exchange<br/>(Order Matching & Sessions)"]
    end

    Strategy <-->|"Clean API callbacks<br/>e.g. on_market_data()"| Pulse
    Pulse <-->|"Raw WebSockets, signed<br/>payloads & health pings"| Engine

    classDef default fill:#111113,stroke:#3f3f46,stroke-width:1px,color:#e4e4e7;
    classDef highlight fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#f8fafc;
    classDef boundary fill:none,stroke:#10b981,stroke-width:2px,stroke-dasharray:5 5;

    class Pulse highlight;
    class Boundary boundary;

Loading

---

Why This Project Is Interesting

Krono sits at the intersection of several hard problems:

• deterministic replay under accelerated time
• execution realism without overclaiming exchange-perfect behavior
• explicit session and run lifecycle design
• runtime separation between strategy logic and infrastructure
• latency-aware simulation behavior
• observability tied to concrete runs, orders, and operational context

That makes Krono as much a systems design project as a trading project.

---

Runs, Telemetry, and Comparison

Krono is designed to make simulation outcomes inspectable, not just visible as a final PnL number.

The environment supports:

• live runtime telemetry from connected bot runtimes
• session-level operational signals and flow-control state
• run-linked trade analytics
• comparison across bot configurations and deployment contexts
• traceability from outcomes back to execution behavior

This makes it easier to answer not only what happened, but also why it happened under those runtime conditions.

---

System Access & Open Source

Krono's core simulation engine, control surface, and market data services are proprietary and closed-source.

However, the runtime boundary is fully open-source. If you want to see how bots interface with the engine, handle telemetry, and manage execution state, you can explore the Pulse runtime here:

• Pulse Runtime

---

Documentation

Public-safe technical docs live under /docs. They complement this README with more detail on:

• architecture and system boundaries
• control surface workflows
• sessions and runs
• bot management
• execution model
• observability and analytics
• Pulse integration
• auth, admin, and usage limits
• integration boundaries

---

Direction

Krono is being built as more than a replay engine.

The broader direction includes:

• deeper run analytics and comparative workflows
• stronger operator tooling around Pulse-based runtimes
• research-oriented services around market inspection and configuration support

Those directions build on the same core goal: making the boundary between trading logic and execution reality easier to test, observe, and reason about.

---

Get in Touch

While the main environment is currently private, I am available to discuss the system design, architecture decisions, or arrange a private walkthrough.