Mini-Bonsi Terminal

The Mini-Bonsi Terminal is a high-performance miniature Limit Order Book (LOB) matching engine, complete with an interactive REPL and a custom domain-specific language (DSL) for placing trading rules.

Originally built as a monolithic OCaml prototype, it has now evolved into a modern, decoupled Client-Server architecture:

1. The Backend (bonsi-engine): A headless OCaml gRPC microservice that handles advanced functional ADT patterns, concurrent Lwt streams, and formal Menhir/OCamllex language parsing.
2. The Frontend (bonsi-tui): A sleek, modern TypeScript dashboard powered by Bun and OpenTUI (a custom React Reconciler for terminal UIs).

Setup Instructions (macOS)

1. Install OCaml & Opam

The easiest way to install OCaml on a Mac is via Homebrew by installing opam (the OCaml package manager).

# Install opam
brew install opam

# Initialize opam (this might take a few minutes)
opam init

# Follow the prompts to update your shell environment, or run:
eval $(opam env)

2. Install Project Dependencies

Once opam is initialized, install the required packages for the OCaml backend:

brew install pkgconf protobuf
opam install -y dune lwt lwt_ppx menhir grpc-lwt ocaml-protoc-plugin h2-lwt-unix

You will also need to install the Bun runtime to serve the OpenTUI frontend:

curl -fsSL https://bun.sh/install | bash

3. IDE Setup (VS Code / Antigravity)

For the best experience writing and reading OCaml code:

1. Open VS Code or Antigravity.
2. Go to the Extensions tab (Cmd+Shift+X).
3. Search for and install the OCaml Platform extension. This provides excellent syntax highlighting, type inference on hover, and auto-completion.

How to Run

The Mini-Bonsi Terminal uses a decoupled architecture. You need to run the OCaml matching engine and the TypeScript OpenTUI dashboard in two separate terminal windows.

Terminal 1: OCaml Backend

The backend runs an HTTP/2 gRPC server that streams market data.

cd bonsi-engine
eval $(opam env)
dune build
dune exec -- ./bin/main.exe

(The server will start silently on port 50051)

Terminal 2: OpenTUI Dashboard

The dashboard connects to the engine and provides a rich terminal UI.

cd bonsi-tui
bun run src/index.tsx

Inside the dashboard REPL, you can interactively type DSL rules (e.g., ON AAPL > 100 DO BUY 10 AAPL) to submit them to the engine over gRPC! To exit the application, press Ctrl-C.

Running Tests

To execute the inline unit tests for the core engine's limit order matching logic, run:

dune runtest

Documentation

For a detailed breakdown of the architecture, implementation phases, and exactly how the engine and DSL work under the hood, please check out the ocaml-engine-learning-docs directory!