cairnquire/.project/adrs/adr-003-ssr-strategy.md

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