# AFI Architecture

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

## Package layout

Tree organized by role.

```
backends/         server protocol adapters
    mizan-django/    Django adapter
    mizan-fastapi/   FastAPI adapter (AFI-common scope)
    mizan-ts/        TypeScript adapter (proves the protocol is language-agnostic)
frontends/        client kernel + per-framework adapters
    mizan-base/      framework-agnostic 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
cores/            shared language-level primitives
    mizan-python/    @client decorator, registry, MWT, HMAC cache keys
protocol/         protocol-level tooling
    mizan-generate/  codegen — schema in, typed client out
workers/          runtime workers / bridges
    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-base`) 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.

## KDL is the IR

The Mizan IR is **KDL** — the LLVM-IR-equivalent of the system. Every
backend adapter produces KDL describing its registered functions,
contexts, types, and invalidation graph. Every codegen target consumes
KDL. KDL is the contract; everything else (REST envelopes, OpenAPI
documents, framework idioms) is sediment around it.

The IR must be validated against multiple adapters before it is
considered stable. Single-adapter validation hides assumptions —
divergence between adapters is what the IR exists to prevent.

Forward-direction primitives:

- `cores/mizan-python` builds the IR from registered functions
  (`build_ir()` walks `mizan_core.registry`, emits KDL)
- A `mizan-schema` package (forthcoming) holds the canonical KDL
  grammar / type system definition that every adapter targets
- Codegen reads KDL directly — no OpenAPI envelope, no
  `openapi-typescript`, no per-backend converter divergence
- Edge manifest, MWT claims, and other protocol artifacts all derive
  from the same KDL

**Current implementation is transitional.** Today the codegen consumes
OpenAPI 3.0 (`x-mizan-functions` + `x-mizan-contexts` extensions over
Pydantic→JSON-Schema), produced via Django Ninja or FastAPI's native
generator. That layered indirection is what introduces adapter
divergence (see the AFI conformance suite). KDL-as-IR collapses 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.