# ADR-001: Go Server with Embedded Web Assets

## Status
Accepted

## Context
We need a documentation platform with fast page delivery, minimal external
dependencies, secure server-side rendering, and a straightforward deployment
artifact.

## Decision
Use Go 1.24+ with the standard library plus minimal, audited packages. The Go
binary serves HTML templates and embeds its CSS, images, and small browser
scripts. There is no separate SPA, Node dependency tree, or frontend build
pipeline.

Browser scripts progressively add editing, offline caching, WebSocket updates,
comments, and authentication interactions to server-rendered pages.

## Consequences

### Positive
- One application binary and one build toolchain
- Go `html/template` provides auto-escaped server rendering
- Embedded assets deploy with the server binary
- Fewer supply-chain dependencies and fewer moving parts in CI
- Pages remain readable before browser scripts execute

### Negative
- Template syntax is less expressive than JSX
- Browser behavior uses small framework-free modules
- WebSocket and offline behavior must be maintained directly

## Alternatives Considered

### Separate Preact SPA
- **Pros**: Component model, client-side routing, TypeScript ecosystem
- **Cons**: Adds Node tooling, package dependencies, a second build pipeline,
  and duplicate UI surfaces
- **Rejected**: The Go-served UI already covers the application surface

### Rust + Axum
- **Pros**: Memory safety guarantees, excellent performance
- **Cons**: Longer compile times and steeper learning curve
- **Rejected**: Go better fits the project deployment model

### Next.js / React Server Components
- **Pros**: Mature ecosystem, built-in SSR
- **Cons**: Heavy build system and more runtime complexity
- **Rejected**: Violates the minimal dependency goal

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