Documentation

The conventions that turn araara's libraries into a framework. We learn them by building one small app file by file — a helpdesk with real logins, roles, a live htmx UI and a JSON API, all sharing the same business logic. Every code block is the real source of the file named above it.

araara is a backend. Each route returns whatever your project needs — server-rendered HTML, JSON, or both — and nothing is mandatory. For server-rendered UIs, araara suggests a small kit of htmx, TyXML and ocsigen-i18n that produces typed HTML and updates it in the browser with no build step. Prefer to compile OCaml to JavaScript, or point a JS framework at a JSON API? That works too. This guide walks through the kit, then the alternatives.

A step-by-step walk through the trading-floor example, a live multi-trader stock exchange built end to end in OCaml. A matching engine runs on the server, a thousand simulated traders supply liquidity, and a brote client renders the whole dashboard over one WebSocket. It is event-sourced — the engine's state is rebuilt from an ordered log of events — and we build it up one layer at a time, from the pure domain to the browser and then to a cluster.

How hcs — the HTTP layer every araara app runs on — compares to reference Go, Rust and PHP servers, measured on one machine under identical conditions. These tests compare servers in narrow, synthetic situations; they are not a prediction of how your own application will perform. Read the caveats first.

hcs is the HTTP layer of an araara application — an HTTP/1.1 and HTTP/2 server and client built on Eio. It also speaks WebSocket and Server-Sent Events. Every snippet below is cut from a complete program under the site repository's examples/ directory, and the runnable ones execute in the test suite.

brote lets you write a rich browser client entirely in OCaml, for the screens where server-rendered HTML is not enough. The UI updates itself as your data changes, and the same OCaml types describe both the server and the client, so the two ends cannot disagree. Every snippet below is cut from the brote repository and its trading-floor example.

araara's database layer — typed schemas, changesets that validate input before it reaches the database, and a composable query DSL in place of raw SQL, with one set of models running unchanged on SQLite, PostgreSQL and MariaDB. Every snippet below is cut from a complete program under the site repository's examples/ directory, and the runnable ones execute in the test suite against an in-memory database.

araara's JSON library — it wraps the SIMD-accelerated simdjson parser and adds a typed codec layer, so you validate, decode into your own OCaml types, encode back, extract by JSON pointer and stream NDJSON, with a zero-copy path for hot loops. Every snippet below is cut from two programs under examples/ that run in the test suite.

araara's worker runtime — background workers with typed mailboxes, supervisors that restart them on failure, timers and one-off tasks, plus pubsub, a registry and groups, local by default and cluster-aware when you opt in. Every snippet below is cut from a complete program under the site repository's examples/ directory, and all three programs run in this site's test suite.

Cluster membership for OCaml — swim implements the SWIM protocol on Eio: nodes discover each other, detect failures with probes and indirect checks, and gossip Alive/Suspect/Dead state, with optional AES-GCM encryption on the wire and your own messaging on top. Every snippet below is cut from a program under examples/ that starts a real cluster on loopback and runs in the test suite.

Replicated JSON documents in OCaml — edit the same JSON on many machines at once and merge it back with no conflicts, wire-compatible with the json-joy ecosystem. The snippets below come from two programs under examples/ — one runs two copies to convergence, the other tours the codec formats — both in the test suite.