54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# 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/template` provides 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
|