Documentation

The conventions that turn araara's libraries into a framework — taught as a tutorial that builds one small application file by file: a helpdesk with real logins, roles, a live htmx UI and a JSON API, all from the same business logic. Every code block is the actual source of the file named above it.

araara is a backend: it serves HTTP, and what each route returns is your choice — server-rendered HTML, JSON, both, or whatever a given project needs. Nothing is mandatory or implicit. For server-rendered UIs, araara proposes a small kit — htmx, pure-html and ocsigen-i18n — that produces typed HTML and updates it in the browser without a build step; if you would rather compile OCaml to JavaScript or point a JS/TS framework at a JSON API, that works too. This guide introduces the kit, then covers each piece, then the alternatives.

hcs is the HTTP layer of an araara application, so its throughput is araara's throughput. These are local, single-machine numbers from the HttpArena harness — hcs (OCaml/Eio) measured side by side with reference Go, Rust, and PHP servers under identical conditions. They are a snapshot, not the official leaderboard, and the caveats matter; read them before drawing conclusions.

hcs is the transport layer of an araara application: an HTTP/1.1 and HTTP/2 server and client on Eio, with WebSocket, Server-Sent Events, a radix-trie router, composable plugs and pipelines, sessions and auth, static files, multipart uploads, pub/sub and a typed request context. 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.

repodb is the data layer of the stack: typed schemas and fields, changesets that validate input before it touches the database, a composable query DSL, transactions and Multi, associations with batched preloading, a connection pool, read/write splitting, typed errors, and a raw-SQL escape hatch for the cases the DSL cannot express — all dialect-aware across 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.

simdjsont binds simdjson — the SIMD-accelerated parser — and puts a typed codec layer on top: validate, extract by JSON pointer, decode into your own types, encode back, 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.

hive is the worker runtime of the stack: workers are Eio fibers with GADT-typed mailboxes and pure message handlers, organised under supervisors with restart strategies, plus timers, one-shot tasks, a typed registry, groups and an injectable pubsub capability — local by default, 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.

swim implements the SWIM protocol — scalable, weakly-consistent, infection-style process group membership — on Eio. Nodes discover each other, detect failures with probes and indirect checks, and gossip Alive/Suspect/Dead state, with optional AES-GCM on the wire and user 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.

crdt is a full OCaml implementation of JSON CRDTs, wire-compatible with the json-joy ecosystem: any JSON structure becomes a document that independent replicas can edit concurrently and merge deterministically. The snippets below come from two programs under examples/ — one runs two replicas to convergence, the other tours the codec formats — both in the test suite.