docs: add project planning documents
This commit is contained in:
53
docs/adrs/adr-001-tech-stack.md
Normal file
53
docs/adrs/adr-001-tech-stack.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user