Ryth Azhur
9d2781b52c
The fe39fcb commit captured the file moves (git mv stages those automatically)
but didn't catch the content edits I made afterward — npm package rename
(@mizan/runtime → @mizan/base), path updates in Makefile/Dockerfile/examples,
and doc updates were all left unstaged at commit time.
This commit lands those:
- npm rename: 3 frontend package.jsons (base/vue/svelte) + mizan-base/src/index.ts + 4 codegen templates
- path updates: Makefile, Dockerfile.test, two Gitea workflows, four example/harness configs
- doc updates: CLAUDE.md, ROADMAP.md, ISSUES.md, docs/AFI_ARCHITECTURE.md
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2.3 KiB
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-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 forthcoming)
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.
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.