Files

Ryth Azhur 6eca514777 Restore documentation layer — match current substrate

ROADMAP: done items moved out of "Next" (codegen rewrite, SSR bridge,
edge manifest, X-Mizan-Invalidate, return-type branching, affects_params,
kernel extraction, two-stage codegen, mizan-ts). Real "Next" in:
framework-adapter wrapper layer (MizanContext + useMizan + DjangoError
on top of the kernel) for React/Vue/Svelte; A1–A4 from ISSUES.md.

CLAUDE: 4-package layout replaced with the actual 7-package layered
architecture (backend protocol adapters + frontend kernel + framework
adapters + SSR worker). "STALE codegen" section rewritten to describe
what's emitted vs. the wrapper layer that isn't yet.

docs/ now tracked (6 files). AFI_ARCHITECTURE rewritten — replaced
the speculative `mizan-ast`/`mizan-csr`/`mizan-rpc`/`mizan-schema`
package names with the real layout, dropped KDL-schema language for
the actual schema-export format. The other 5 docs/ files were already
current and are tracked as-is.

ARCHITECTURE-REWORK.md deleted — same expert review is re-tracked in
the fresher ISSUES.md, two parallel trackers was sediment.

README.md deleted — drift was beyond surgical fixes (`mizan_clients.py`
convention, `<DjangoContext>` provider, removed `@compose` and
`context='local'`, wrong codegen output filenames, 3-package structure
vs. 7). Rewrite waits for the wrapper-layer codegen to land so
user-facing examples reflect reality.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-05 20:10:12 -04:00

2.5 KiB

Raw Blame History

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.

2.5 KiB Raw Blame History Unescape Escape