# Architecture

TinyRustLM is split into small, explicit boundaries. The website should explain those boundaries because they are the product.

## Source-backed workspace

| Component | Role |
| --- | --- |
| `tinyrustlm/app/` | Static browser UI with handwritten HTML, CSS, and JavaScript. |
| `tinyrustlm/runtime/` | No-crate Rust runtime compiled to WASM. |
| `tinyrustlm/tools/slm_pack/` | No-crate Rust utility for model files, manifests, receipts, operators, and browser bundles. |
| `tinyrustlm/tools/local_server/` | No-crate local static server for loopback app hosting. |
| `tinyrustlm/tools/browser_harness/` | No-crate Rust contract checker for app and route assumptions. |
| `tinyrustlm/docs/` | Durable architecture, browser runtime, testing, performance, tokenizer, quantization, and format notes. |
| `.uai/` | Hot project handoff and routing memory. |
| `wiki/runtime-mirust/` | LLM Wiki source namespace for durable memory publication. |

## Runtime boundary

The runtime owns the parts that must be trustworthy:

- `.slm` parsing and validation;
- checksum checks before tensor decoding;
- tokenizer behavior;
- f32, q8_0, and q4_0 storage and dispatch;
- tensor routing and tied-output fallback;
- KV cache and scratch buffers;
- sampler and output limits;
- diagnostics;
- context reset;
- model free;
- ADP1, ASP1, and ALR1 adapter validation and apply.

JavaScript does not parse `.slm`, own tensor math, or make quality claims. JavaScript hosts the browser state, fetches local files, copies bytes into WASM memory, calls Rust exports, and renders diagnostics.

## Browser app boundary

The browser app is intentionally static. It presents model selection, prompt controls, output, transcript state, Step Token, Adapter Sidecar, Model Provenance, Module Plan, Assembly Evidence, and developer diagnostics. It fetches only local or same-origin project artifacts.

The browser-side rules are strict:

- selected model bytes must match declared byte counts;
- manifests must fit text-sidecar budgets;
- generated module plans must be verified before model bytes;
- adapter manifests and adapter bytes must be verified before WASM transfer;
- generated adapter stacks must validate in Rust before apply;
- transcript Clear is different from runtime Reset.

## Packer boundary

`tinyrustlm-slm-pack` is the offline tool lane. It produces or validates model artifacts, adapter artifacts, receipts, manifests, candidates, promotions, population records, parent-pool recipes, selector registries, and browser-routable bundles.

This design keeps model-breeding work out of the live runtime until it has normal `.slm` validation, manifests, evidence sidecars, admission records, and browser route proof.

## Proof memory

The `.uai` and `wiki/runtime-mirust/` files are not decorative. They are part of the project handoff system. They route future agents to source boundaries, testing rules, report synthesis, long-term pointers, and next prompts without dumping every report body into hot memory.