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

Latest change fc42a695fc258e2e68d465fc233baaaa56b9c7f0 - OLI-157: configurable SecurityPolicy middleware ([security] in akurai.toml) 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.

## Security headers

`akurai serve` applies the legacy minimal headers by default. Adding a
`[security]` table to `akurai.toml` switches to the strict `SecurityPolicy`:

```toml
[security]
csp = "default-src 'self'; img-src 'self' data:"  # default: self-only
frame_ancestors = "'none'"      # also sets X-Frame-Options (DENY / SAMEORIGIN)
hsts = "max-age=31536000; includeSubDomains"
referrer_policy = "no-referrer"
permissions_policy = "camera=(), microphone=(), geolocation=()"
nosniff = true
```

Omit a key for the strict default; set a string key to `""` to disable that
header. Library users push `akurai_http::SecurityPolicy` onto a `MiddlewareStack`.