2.0 KiB
2.0 KiB
ADR-001: Go Backend with Preact Frontend
Status
Accepted
Context
We need to choose a backend language/framework and frontend technology for a documentation platform with these requirements:
- Ultra-fast performance
- Minimal external dependencies
- No vendor lock-in
- Battle-tested security
- Server-side rendering for non-interactive pages
- Offline-capable web client
Decision
Backend: Go 1.22+ with standard library plus minimal, well-audited packages
Frontend: Preact 10 with TypeScript, Vite build system
Consequences
Positive
- Go's standard library is comprehensive and security-audited
- Single static binary deployment — no runtime dependencies
- Preact is 10KB (vs 40KB+ React) with identical API
- Go's
html/templateprovides safe SSR with auto-escaping - TypeScript gives type safety without runtime overhead
- Both ecosystems have excellent supply-chain security (Go modules with checksums, npm audit)
Negative
- Go template syntax is less expressive than JSX
- WebSocket sync logic must be implemented manually (no framework like Socket.io)
- Preact ecosystem smaller than React (mitigated by using mostly native APIs)
Alternatives Considered
Rust + Axum
- Pros: Memory safety guarantees, excellent performance
- Cons: Longer compile times, smaller talent pool, steeper learning curve for team
- Rejected: Go's pragmatic balance of safety and velocity better fits project timeline
Deno Fresh
- Pros: Island architecture, native TypeScript, no build step
- Cons: Newer ecosystem, fewer audited libraries, Deno runtime less battle-tested than Go
- Rejected: Go's maturity and deployment simplicity preferred
Next.js / React Server Components
- Pros: Mature ecosystem, built-in SSR
- Cons: Heavy bundle size, complex build system, RSC lock-in, many dependencies
- Rejected: Violates "minimal dependencies" and "no vendor lock-in" principles
References
- Go Security Policy: https://go.dev/security
- Preact Size Comparison: https://bundlephobia.com/package/preact@10.19.3