Ryth Azhur
6eca514777
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>
78 lines
2.5 KiB
Markdown
78 lines
2.5 KiB
Markdown
# 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.
|