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>
93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# 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
|