AkurAI-Framework / site/content/docs/architecture.md

Latest change 2fbdb9ef20bb6f998f6b466eca5a508facd20968 - template: add raw blocks and fix release changelog flow by Ólafur Búi Ólafsson

# Architecture

The framework is a Cargo workspace of small, single-responsibility crates. The
shipped binary links **zero external crates** — everything is built on `std`.

## The crates

- **akurai-http** — a hand-written HTTP/1.1 server: request parser, response
  builder, a thread pool, and the accept loop.
- **akurai-json** — a JSON value type, parser, and serializer. Integers and
  floats stay distinct so record IDs round-trip exactly.
- **akurai-template** — the server-side template engine: `{{ }}` interpolation,
  `{% if %}`, `{% for %}`, `{% include %}`, `{% raw %}`, rendered against a
  JSON context.
- **akurai-markdown** — a Markdown→HTML renderer that powers these docs and the
  changelog.
- **akurai-storage** — the database foundation: a single-file pager and a
  copy-on-write B+tree. Durability comes from atomic commits, not luck.
- **akurai** — the CLI binary that wires it all together.

## Request flow

```
TCP → parse request → route:
   /api/*          → JSON endpoints (health, _meta, records)
   /docs, /changelog → Markdown rendered into a layout template
   *.css, *.js …   → static files
   everything else → a template, rendered against backend/page.json
```

## Durability

The storage engine never overwrites live data. A write produces new pages and a
new tree root; the commit is an atomic swap of a double-buffered, checksummed
meta page followed by an `fsync`. A crash mid-write always leaves the last
fully-committed state intact — the same model proven by LMDB and redb.

## TLS

`std` cannot do TLS, and the framework will not pull in a crate for it. Terminate
TLS at the edge (nginx, Caddy) and let the server speak plain HTTP on localhost —
the standard, correct topology for this scale.