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>
This commit is contained in:
50
docs/SSR_ARCHITECTURE.md
Normal file
50
docs/SSR_ARCHITECTURE.md
Normal file
@@ -0,0 +1,50 @@
|
||||
# SSR Architecture
|
||||
|
||||
*Decided 2026-04-07.*
|
||||
|
||||
Mizan's SSR adapter is a **Django template backend**. It plugs into
|
||||
Django's existing `TEMPLATES` setting, replacing the template
|
||||
rendering engine.
|
||||
|
||||
```python
|
||||
TEMPLATES = [
|
||||
{
|
||||
'BACKEND': 'mizan.ssr.MizanTemplates',
|
||||
...
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
Then `render(request, 'ProfilePage', context)` calls the Bun
|
||||
subprocess bridge instead of rendering a Django/Jinja2 template.
|
||||
**The component name IS the template name.**
|
||||
|
||||
## AFI boundary
|
||||
|
||||
| Side | Responsibility |
|
||||
|---|---|
|
||||
| Backend adapter | Implements `mizan.ssr()` — executes context functions, gathers data |
|
||||
| Frontend adapter | Implements `renderToHTML()` — takes component + props, produces HTML |
|
||||
| Bun subprocess | Hosts the frontend adapter |
|
||||
| stdin/stdout JSON-RPC | Transport between the two |
|
||||
|
||||
## Why template backend
|
||||
|
||||
- Django's template system is swappable by design (batteries
|
||||
included, but replaceable).
|
||||
- Django developers already use `render(request, template, context)`
|
||||
— no new API to learn.
|
||||
- URL routing, views, middleware, auth — all unchanged.
|
||||
- The template tag `{% mizan_render %}` is a convenience for
|
||||
developers who *also* use Django templates (e.g., a base.html shell
|
||||
with Mizan components inside).
|
||||
|
||||
## Implementation surface
|
||||
|
||||
The SSR bridge module implements Django's template backend interface:
|
||||
|
||||
- `BaseEngine` subclass
|
||||
- `Template` class with `.render(context, request)`
|
||||
|
||||
Everything Django expects from a template backend, but the actual
|
||||
rendering routes to Bun.
|
||||
Reference in New Issue
Block a user