55 lines
1.9 KiB
Markdown
55 lines
1.9 KiB
Markdown
# 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
|