# ADR-003: SSR Strategy - Go Templates with Embedded Browser Scripts

## Status
Accepted

## Context
Document pages must be readable quickly and safely while still supporting
editing, authentication, comments, offline caching, and real-time updates.

## Decision
Go `html/template` renders complete HTML pages. The server embeds and serves
small framework-free browser scripts for progressive enhancement.

### Implementation Details

1. **Server Rendering**:
   - Go handlers query document and account data
   - Goldmark parses Markdown to HTML server-side
   - `html/template` renders complete pages
   - Pages are readable before JavaScript executes

2. **Browser Enhancement**:
   - Embedded scripts handle editing, comments, authentication, offline cache,
     service-worker behavior, and WebSocket updates
   - Native browser APIs are preferred over a client framework
   - There is no separate SPA route or frontend build pipeline

## Consequences

### Positive
- Fast first contentful paint
- Auto-escaped templates
- One deployable application artifact
- Small browser payloads and no Node build dependency
- Interactive features stay close to their HTTP endpoints

### Negative
- Browser modules need direct DOM event handling
- Shared UI abstractions require deliberate maintenance
- More complex browser interactions need focused integration tests

## Alternatives Considered

### Separate Hydrated SPA
- **Pros**: Component framework and client-side routing
- **Cons**: Duplicates UI paths and introduces a second toolchain
- **Rejected**: The server-rendered UI already supports the required behavior

### Embedded JS Runtime
- **Pros**: Isomorphic rendering
- **Cons**: Larger binary and additional security surface
- **Rejected**: Go templates are simpler

## References
- Go `html/template`: https://pkg.go.dev/html/template