mizan/ROADMAP.md

Mizan Roadmap

v1 — Django + Multi-Framework (React, Vue, Svelte)

Done

• @client decorator — context=, affects=, auth=, websocket=, private=, route=, methods=, rev=, cache=
• ReactContext class — type-safe context/affects references with linting
• Named contexts — functions sharing a context name grouped into one provider and one fetch
• Context bundling endpoint — GET /api/mizan/ctx/<name>/ returns all functions in one response
• Server-driven invalidation (JSON body) — mutation responses carry {"result": ..., "invalidate": [...]}
• X-Mizan-Invalidate header — second invalidation transport for view-path responses (redirects, HTML)
• Return-type branching — data return → RPC path; HttpResponse return → view path
• Scoped invalidation — affects_params lambda; runtime supports {context, params} form
• Auth guards — auth=True, auth='staff', auth='superuser', auth=callable
• JWT + session auth — auto-detected, CSRF handled
• MWT — Mizan Web Token for Edge cache keying (separate secret from JWT/cache)
• Shapes — Pydantic + django-readers for typed query projections
• WebSocket channels — real-time bidirectional communication
• HMAC cache keying — origin-side cache with cross-language HMAC conformance (Python + TypeScript pin)
• Edge manifest — python manage.py export_edge_manifest; both RPC and view-path functions
• SSR bridge — Django template backend → persistent Bun subprocess via JSON-RPC
• mizan-base kernel — framework-agnostic imperative client primitives (data/status/error owned by kernel)
• Two-stage codegen — Stage 1 emits framework-agnostic protocol layer; Stage 2 emits per-framework hooks (React, Vue, Svelte)
• mizan-ts — TypeScript backend adapter; proves the protocol is language-agnostic

---

Next (in progress)

• React adapter wrapper layer — codegen emits MizanContext provider, useMizan hook, DjangoError class on top of the mizan-base kernel. Equivalent wrapper layers for Vue and Svelte adapters. The harness in examples/django-react-site is blocked on this.
• Legacy MizanProvider removal (A1) — mizan-react/src/context.tsx (~750 lines) replaced by codegen-emitted wrappers. Blocks v1 mizan-react publishing.
• Forms migration to kernel (A3) — mizan-react/src/forms.ts (~1163 lines) currently consumes legacy MizanProvider. Rewrite to use mizanCall from the kernel. Blocks A1.
• Allauth extraction (A2) — legacy/allauth/ becomes mizan-django-allauth package consuming Mizan's public API.
• Vue/Svelte e2e validation (A4) — example apps exercising a live backend end-to-end, like examples/django-react-site does for React.
• Test coverage gaps — T1–T12 in ISSUES.md (kernel state machine, view-path purge, SSR thread safety, retry logic, cross-language HMAC pin, etc.)

---

Quality

• H5 — Mutation hooks expose no loading/error state
• H7 — Redis SCAN blocks request path at scale
• H8 — Svelte codegen uses Svelte 4 stores; should use Svelte 5 runes
• H9 — Svelte destroy() not auto-called (memory leak)
• H12 — Forms triggerValidation captures stale data
• Medium issues (M1–M18) per developer judgment

---

Mizan Cloud (closed-source)

Mizan Edge

Cloudflare Workers for automatic edge caching.

• Reads the edge manifest to configure cache rules
• Context GETs cached at edge, keyed by context name + params
• Reads X-Mizan-Invalidate header from mutation responses to purge caches
• Reads JSON invalidate key from RPC responses for the same purpose
• Resolves URL patterns from manifest to purge view pages
• Zero configuration — the manifest IS the cache policy

Mizan Render

SSR at the edge via Cloudflare Workers.

• The Bun SSR bridge, running on Cloudflare instead of colocated with Django
• Context data fetched from Django (or edge cache), rendered at the edge
• HTML response streamed to the user from the nearest PoP

Mizan Deploy

One-command deployment for Django + React apps.

• Container orchestration (AWS/Azure)
• Edge + Render auto-configured
• mizan deploy from the CLI
• The Vercel experience for Django

---

Reference

Wire protocol shapes (context fetch, mutation call, invalidation transports) are documented in CLAUDE.md. Architectural details for specific subsystems live in docs/:

• docs/AFI_ARCHITECTURE.md — package architecture, kernel model, adapter strategy
• docs/CACHE_KEYING.md — HMAC cache key derivation
• docs/MWT_SPEC.md — Mizan Web Token format
• docs/SSR_ARCHITECTURE.md — Django template backend, Bun bridge
• docs/PSR_VS_EDGE.md — protocol-level rendering vs. paid Edge layer
• docs/PRODUCT_ARCHITECTURE.md — product surface and pricing tiers