# 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.