How Wardian is built

Wardian is one Rust program and a few pages of plain JavaScript. The Rust side is built in the hexagonal style, also called ports and adapters: the rules sit in the middle and know nothing about disks, networks or browsers. Everything that talks to the outside sits at the edge, behind a small interface called a port.

Think of a wall socket. The lamp does not care which power station feeds it; it only knows the socket. A Wardian use case only knows the port, and an adapter plugs a real disk, a real Splunk or a fake one into it. That is why most of Wardian is tested without a network.

The layers#

src/
  main.rs, config.rs      the composition root: reads settings, builds everything, starts it
  domain/                 the rules, pure: no files, no network, no clock
  ports/                  the interfaces between the layers
  usecases/               what Wardian does, through the ports
  adapters/primary/       what drives Wardian: the web server, the command line
  adapters/secondary/     what Wardian drives: the disk, Drive, Splunk, Claude, SQLite
static/                   the pages and scripts the browser runs
templates/                the starter packages for `wardian new`

Dependencies point inward only. Adapters depend on ports. Use cases depend on ports and the domain. The domain may use the standard library, but not std::fs, std::net, std::process, std::env or std::io, and no other crate but serde and serde_json (ADR-2610071200). hexa analyze checks these rules on every run (below).

src/main.rs is the composition root: the one place that knows every adapter. It reads config.rs, builds each adapter, hands them to the use cases as ports, and then runs either the command line or the web server. config.rs is the one place that reads environment variables.

What each module does#

Domain#

Ports#

Use cases#

Primary adapters#

Secondary adapters#

Only the two inference adapters name Claude models. A hexa rule refuses a model name anywhere else.

src/tests.rs runs the use cases against real adapters, so it belongs to the composition root. The pure rules are tested next to their code in domain/.

How a request flows#

Take an app in a suite that runs a Splunk search.

1. The app calls splunk.search(…). The shim in its frame posts a capop message to the kernel.
2. The kernel checks that the app's contract lists splunk, and asks you for permission the first time. Then it posts to /api/splunk/search with the package, the app and "background": true.
3. adapters/primary/http.rs decides whether the request is from an admin, reads the JSON body, and calls Catalog::check_host_cap. That reads suite.json and grants.json again on the server.
4. It asks the Jobs port to start the search. usecases/jobs.rs runs it on its own thread and answers {job: id} at once.
5. On that thread, usecases/splunk.rs runs the search through the SplunkApi port, which adapters/secondary/splunk_rest.rs implements.
6. The kernel asks /api/jobs/<id> how it is going, every second and then every two, and gives the app the result when the job is done.

Every route works the same way: http.rs knows only the ports in ports/service.rs, the use cases implement them, and the use cases reach the outside only through the other ports.

The kernel and the frame shim#

The browser side has two parts that matter for security:

• static/kernel.html is the page that runs a suite, at /run/<suite>/. It is Wardian's own code. It reads suite.json, makes one sandboxed frame per app, checks every message against the contract, passes messages and calls on, grants capabilities, asks for permissions, and shows faults. Kernel.apps(), Kernel.trace(), Kernel.faults() and Kernel.started() are its debug calls.
• static/shim.js runs inside each app's frame, before app.js. It defines Kernel.register and ctx, and turns each ctx call into a postMessage to the kernel. It compares the contract in app.js with the one from suite.json, and does not start the app if they differ. Its own checks only fail fast with a clear message: the kernel enforces the contract either way.

The server builds each frame as one document (domain/suite.rs, frame): styles, the view, the scripts, the shim and app.js, all inlined, under the frame policy that blocks the network. See Security model.

The other files in static/:

Embedded assets#

Wardian needs no files beside itself. src/adapters/secondary/embedded_assets.rs builds these into the program with include_str! and include_bytes!:

• the component library (static/ui/) and its gallery;
• the frame shim: static/snapshot.js, static/shim.js and static/ui/progress.js;
• the templates for wardian new (templates/);
• SPEC.md and the example suite Claude reads before it builds an app;
• the JSON Schemas (schemas/);
• every page of this documentation site (the DOCS list).

http.rs also builds in Wardian's own pages and scripts (index.html, kernel.html, the logo, channels.js, state.js, sdk.js, snapshot.js). A change to any of these files needs a rebuild.

How the docs are built#

Each docs page is a Markdown file: docs/site/*.md, plus GUIDE.md, SPEC.md and CHANGELOG.md as they are. The DOCS list in embedded_assets.rs names each page's group, address, title and file, in menu order.

src/usecases/docs.rs renders a page when the browser asks for /docs/<name>. It gives every ## and ### heading an anchor, builds the menu and a search index of every heading, and links each page to its file on GitHub. wardian docs FOLDER writes the same pages as static HTML, with the schemas and the component gallery; the website keeps them in website/. So the program and the website show one text. Contributing says how to add a page.

hexa gates#

hexa is the tool that grades Wardian's structure. Its settings are in .hexa/:

It has two gates:

• hexa analyze . --grade A grades the layers, the import rules and the ADR rules. Wardian must score A.
• hexa adr gates runs the command in each decision's Gate section, so a decision whose test fails is caught. It builds into target/verify, never into the copy of Wardian you run.

tests/run-all.sh runs both when hexa is installed. Decisions lists every gate.

This page is docs/site/architecture.md in the repository. Something wrong or missing? Change that file.