# kronex-stock-exchange/kronex-engine architecture

> Architecture diagram of the GitHub repository kronex-stock-exchange/kronex-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kronex-stock-exchange/kronex-engine
- Repository: https://github.com/kronex-stock-exchange/kronex-engine

## Overview

Kronex Engine consumes exchange requests from RabbitMQ, applies them to an in-memory ledger and price-time-priority order books, and records results for independent database projection and event publication. The graph also shows the documented admin/transfer paths, snapshot persistence, and recovery. Some subsystem links come from the README because their implementation was not excerpted; unsampled internal call details are not inferred.

Main entry points: [`internal/core/engine.go`](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/engine.go) (Main Engine), [`internal/core/handle.go`](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/handle.go) (Request Routing), [`internal/core/order.go`](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/order.go) (Order Matching), [`internal/messaging/rabbitmq.go`](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/messaging/rabbitmq.go) (Queue Adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Request Processing"]
  node_messaging["Queue Adapter<br/>[rabbitmq.go]"]
  node_engine["Main Engine<br/>[engine.go]"]
  node_request_routes["Request Routing<br/>[handle.go]"]
  node_order_validation["Order Validation"]
  node_order_matching["Order Matching<br/>[order.go]"]
  node_admin["Admin Requests<br/>[handle_admin.go]"]
  node_transfers["Transfers<br/>[transfer.go]"]
  node_dedup["Request Dedup<br/>[dedup.go]"]
end

subgraph group_state["Ledger State"]
  node_ledger["Memory Ledger<br/>[ledger.go]"]
  node_orderbook["Order Books<br/>[orderbook.go]"]
  node_accounts["Account State<br/>[account.go]"]
  node_stock_balances["Stock Balances<br/>[stockbalance.go]"]
end

subgraph group_durability["Durability"]
  node_wal[("Write-Ahead Logs<br/>[wal.go]")]
  node_snapshot["Snapshot Store<br/>[snapshot.go]"]
end

subgraph group_outputs["Result Delivery"]
  node_db_projector["DB Projector<br/>[db_projector.go]"]
  node_event_publisher["Event Publisher<br/>[event_publisher.go]"]
  node_publisher_handler["Publisher Coordinator<br/>[handler.go]"]
  node_event_store["Event Store<br/>[event.go]"]
end

node_api(("API Server"))
node_rabbitmq["RabbitMQ"]
node_mysql[("MySQL")]

node_api -->|"enqueues requests"| node_rabbitmq
node_rabbitmq -->|"delivers requests"| node_messaging
node_messaging -->|"supplies deliveries"| node_engine
node_engine -->|"routes requests"| node_request_routes
node_engine -->|"deduplicates requests"| node_dedup
node_request_routes -->|"validates orders"| node_order_validation
node_request_routes -->|"handles orders"| node_order_matching
node_request_routes -->|"handles admin"| node_admin
node_request_routes -->|"handles transfers"| node_transfers
node_engine -->|"records input and output"| node_wal
node_engine -->|"restores and replays state"| node_ledger
node_order_matching -->|"matches against"| node_orderbook
node_order_matching -->|"updates balances"| node_accounts
node_order_matching -->|"updates holdings"| node_stock_balances
node_engine -->|"saves and loads snapshots"| node_snapshot
node_snapshot -->|"persists snapshots"| node_mysql
node_wal -->|"provides output records"| node_db_projector
node_wal -->|"provides output records"| node_event_publisher
node_engine -->|"starts publisher"| node_publisher_handler
node_publisher_handler -->|"runs independently"| node_db_projector
node_publisher_handler -->|"runs independently"| node_event_publisher
node_db_projector -->|"applies events"| node_event_store
node_event_store -->|"updates query tables"| node_mysql
node_event_publisher -->|"publishes event batches"| node_messaging
node_messaging -->|"publishes events"| node_rabbitmq

click node_messaging "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/messaging/rabbitmq.go"
click node_engine "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/engine.go"
click node_request_routes "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/handle.go"
click node_order_validation "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/order_validation.go"
click node_order_matching "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/order.go"
click node_admin "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/handle_admin.go"
click node_transfers "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/transfer.go"
click node_dedup "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/dedup.go"
click node_ledger "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/ledger.go"
click node_orderbook "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/orderbook.go"
click node_accounts "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/account.go"
click node_stock_balances "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/stockbalance.go"
click node_wal "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/wal/wal.go"
click node_snapshot "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/storage/snapshot.go"
click node_db_projector "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/db_projector.go"
click node_event_publisher "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/event_publisher.go"
click node_publisher_handler "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/handler.go"
click node_event_store "https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/storage/event.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_messaging,node_engine,node_request_routes,node_order_validation,node_order_matching,node_admin,node_transfers,node_dedup toneBlue
class node_ledger,node_orderbook,node_accounts,node_stock_balances,node_mysql toneAmber
class node_wal,node_snapshot,node_api toneMint
class node_db_projector,node_event_publisher,node_publisher_handler,node_event_store toneRose
class node_rabbitmq toneIndigo
```

## Components

### Request Processing

- [Queue Adapter](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/messaging/rabbitmq.go): `internal/messaging/rabbitmq.go`
- [Main Engine](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/engine.go): `internal/core/engine.go`
- [Request Routing](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/handle.go): `internal/core/handle.go`
- [Order Validation](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/order_validation.go): `internal/core/order_validation.go`
- [Order Matching](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/order.go): `internal/core/order.go`
- [Admin Requests](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/handle_admin.go): `internal/core/handle_admin.go`
- [Transfers](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/transfer.go): `internal/core/transfer.go`
- [Request Dedup](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/core/dedup.go): `internal/core/dedup.go`

### Ledger State

- [Memory Ledger](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/ledger.go): `internal/ledger/ledger.go`
- [Order Books](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/orderbook.go): `internal/ledger/orderbook.go`
- [Account State](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/account.go): `internal/ledger/account.go`
- [Stock Balances](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/ledger/stockbalance.go): `internal/ledger/stockbalance.go`

### Durability

- [Write-Ahead Logs](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/wal/wal.go): `internal/wal/wal.go`
- [Snapshot Store](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/storage/snapshot.go): `internal/storage/snapshot.go`

### Result Delivery

- [DB Projector](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/db_projector.go): `internal/publisher/db_projector.go`
- [Event Publisher](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/event_publisher.go): `internal/publisher/event_publisher.go`
- [Publisher Coordinator](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/publisher/handler.go): `internal/publisher/handler.go`
- [Event Store](https://github.com/kronex-stock-exchange/kronex-engine/blob/main/internal/storage/event.go): `internal/storage/event.go`

### Other components

- **API Server**
- **RabbitMQ**
- **MySQL**

## Connections

- API Server → RabbitMQ: enqueues requests
- RabbitMQ → Queue Adapter: delivers requests (evidence: `internal/messaging/rabbitmq.go`)
- Queue Adapter → Main Engine: supplies deliveries
- Main Engine → Request Routing: routes requests (evidence: `internal/core/handle.go`)
- Main Engine → Request Dedup: deduplicates requests
- Request Routing → Order Validation: validates orders
- Request Routing → Order Matching: handles orders
- Request Routing → Admin Requests: handles admin
- Request Routing → Transfers: handles transfers
- Main Engine → Write-Ahead Logs: records input and output
- Main Engine → Memory Ledger: restores and replays state
- Order Matching → Order Books: matches against (evidence: `internal/core/order.go`)
- Order Matching → Account State: updates balances (evidence: `internal/core/order.go`)
- Order Matching → Stock Balances: updates holdings (evidence: `internal/core/order.go`)
- Main Engine → Snapshot Store: saves and loads snapshots
- Snapshot Store → MySQL: persists snapshots
- Write-Ahead Logs → DB Projector: provides output records
- Write-Ahead Logs → Event Publisher: provides output records
- Main Engine → Publisher Coordinator: starts publisher
- Publisher Coordinator → DB Projector: runs independently (evidence: `internal/publisher/handler.go`)
- Publisher Coordinator → Event Publisher: runs independently (evidence: `internal/publisher/handler.go`)
- DB Projector → Event Store: applies events (evidence: `internal/publisher/db_projector.go`)
- Event Store → MySQL: updates query tables (evidence: `internal/storage/event.go`)
- Event Publisher → Queue Adapter: publishes event batches (evidence: `internal/publisher/event_publisher.go`)
- Queue Adapter → RabbitMQ: publishes events (evidence: `internal/messaging/rabbitmq.go`)
