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

1.9 KiB Raw Blame History