# AFI Architecture

Mizan is an **Application Framework Interface (AFI)** — the
server-client unification layer.

## Package layout

Two layers per side. Independent packages, single shared protocol.

**Backend protocol adapters** — implement the wire protocol on a
server stack:

| Package | Role |
|---|---|
| `mizan-django` | Django adapter |
| `mizan-ts` | TypeScript adapter (proves the protocol is language-agnostic) |

**Frontend kernel + framework adapters** — the kernel is the
imperative client primitive set; each framework adapter wraps the
kernel in its own idiomatic constructs:

| Package | Role |
|---|---|
| `mizan-runtime` | Framework-agnostic client kernel — owns data, status, error; adapters subscribe |
| `mizan-react` | React contexts + hooks over the kernel |
| `mizan-vue` | Vue composables over the kernel |
| `mizan-svelte` | Svelte stores/runes over the kernel |

**SSR worker:**

| Package | Role |
|---|---|
| `mizan-ssr` | Bun subprocess used by the Django template backend |

## Two orthogonal products

- **RPC** — typed client generation via codegen
- **SSR** — server rendering via the Bun bridge

Independent and composable. Either ships standalone; together they
compose.

## Kernel model

The client kernel (`mizan-runtime`) is the one hard thing. Per-
framework adapters are thin idiomatic wrappers around it. Codegen
emits typed bindings against the framework adapter's surface, not
against the raw kernel — so a React developer gets `useEcho()` and
`<MizanContext>`, a Vue developer gets `useEcho()` composables, a
Svelte developer gets readable stores. Same kernel underneath.

## Schema is load-bearing

The backend exports a JSON schema describing every `@client`-decorated
function and context (`x-mizan-functions`, `x-mizan-contexts`). The
schema IS the contract: codegen reads it, the edge manifest derives
from it, MWT auth gates against it.

## Launch surface

Python (Django) + React. Vue and Svelte ship as v1 alongside React.
TypeScript backend (`mizan-ts`) proves the protocol is portable.

## Why the AFI shape

Quadratic ecosystem growth (N server adapters × M client adapters)
collapses to linear (one adapter per stack) when both sides
communicate through a shared protocol.

## Invariants

- All cross-package communication goes through the protocol. No
  direct cross-package dependencies.
- New adapters land as new packages, not as modifications to existing
  ones.
- Framework adapters wrap the kernel in framework idioms — they
  don't bypass it. Codegen targets the adapter, not the raw kernel.