move docs to docs/ folder, merge architecture files, update references
This commit is contained in:
367
docs/DEV_PORTAL_M02_WEB_STACK.md
Normal file
367
docs/DEV_PORTAL_M02_WEB_STACK.md
Normal file
@@ -0,0 +1,367 @@
|
||||
# Milestone 2: Web Stack Selection
|
||||
|
||||
**Status**: Decided
|
||||
**Goal**: Choose backend technologies for the developer portal and app store API.
|
||||
|
||||
## Decision
|
||||
|
||||
**Go** with the following stack:
|
||||
|
||||
```
|
||||
Language: Go 1.22+
|
||||
Framework: Chi (lightweight, idiomatic)
|
||||
Database: SQLite via modernc.org/sqlite (pure Go, no CGO)
|
||||
Migrations: golang-migrate
|
||||
Validation: go-playground/validator
|
||||
Auth: Custom JWT + OAuth2
|
||||
Deployment: Single Docker container on Synology NAS
|
||||
```
|
||||
|
||||
### Rationale
|
||||
|
||||
1. **NAS-friendly** - Tiny Docker image (~15MB), low RAM (~30-50MB)
|
||||
2. **Cross-compilation** - Easy build for ARM64 or AMD64 Synology models
|
||||
3. **Pure Go SQLite** - `modernc.org/sqlite` requires no CGO, cross-compiles easily
|
||||
4. **Single container** - Go binary + SQLite + Litestream in one image
|
||||
5. **Standard library** - HTTP, JSON, crypto all built-in
|
||||
|
||||
### Target Deployment
|
||||
|
||||
```
|
||||
Synology NAS (Docker)
|
||||
├── mosis-portal container (~15MB image)
|
||||
│ ├── Go binary
|
||||
│ ├── SQLite database (WAL mode)
|
||||
│ └── Litestream backup
|
||||
└── Volumes
|
||||
├── /volume1/mosis/data/portal.db
|
||||
├── /volume1/mosis/backups/
|
||||
└── /volume1/mosis/packages/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The web stack powers the developer portal, app store API, and telemetry ingestion. This decision affects development speed, hosting costs, and long-term maintenance.
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional
|
||||
|
||||
- REST API for developer portal
|
||||
- File upload handling (app packages)
|
||||
- Authentication (OAuth2, API keys)
|
||||
- Database integration
|
||||
- Background jobs (review queue, notifications)
|
||||
- WebSocket support (optional, for real-time updates)
|
||||
|
||||
### Non-Functional
|
||||
|
||||
- Handle 1000+ developers initially
|
||||
- Scale to 10,000+ apps
|
||||
- 99.9% uptime target
|
||||
- < 200ms API response time (p95)
|
||||
- Secure by default
|
||||
|
||||
---
|
||||
|
||||
## Options Analysis
|
||||
|
||||
### Option A: Node.js + TypeScript
|
||||
|
||||
#### Stack
|
||||
```
|
||||
Runtime: Node.js 20 LTS
|
||||
Language: TypeScript
|
||||
Framework: Fastify or Hono
|
||||
ORM: Prisma or Drizzle
|
||||
Validation: Zod
|
||||
Auth: Lucia or custom JWT
|
||||
```
|
||||
|
||||
#### Pros
|
||||
| Advantage | Details |
|
||||
|-----------|---------|
|
||||
| Fast development | Large ecosystem, familiar syntax |
|
||||
| Type safety | TypeScript catches errors early |
|
||||
| Easy hiring | Many JS/TS developers |
|
||||
| Ecosystem | npm has libraries for everything |
|
||||
| Hosting | Vercel, Railway, Render, any VPS |
|
||||
|
||||
#### Cons
|
||||
| Disadvantage | Details |
|
||||
|--------------|---------|
|
||||
| Single-threaded | Need clustering for CPU tasks |
|
||||
| Memory usage | Higher than compiled languages |
|
||||
| Callback complexity | Async can get messy |
|
||||
|
||||
#### Example Structure
|
||||
```
|
||||
src/
|
||||
├── index.ts
|
||||
├── routes/
|
||||
│ ├── auth.ts
|
||||
│ ├── apps.ts
|
||||
│ └── telemetry.ts
|
||||
├── services/
|
||||
│ ├── auth.service.ts
|
||||
│ └── storage.service.ts
|
||||
├── db/
|
||||
│ ├── schema.ts
|
||||
│ └── client.ts
|
||||
└── utils/
|
||||
```
|
||||
|
||||
#### Hosting Cost Estimate
|
||||
| Service | Cost/month |
|
||||
|---------|------------|
|
||||
| Railway (starter) | $5-20 |
|
||||
| Vercel Pro | $20 |
|
||||
| VPS (4GB) | $20-40 |
|
||||
|
||||
---
|
||||
|
||||
### Option B: Go
|
||||
|
||||
#### Stack
|
||||
```
|
||||
Language: Go 1.22+
|
||||
Framework: Chi, Echo, or Gin
|
||||
ORM: sqlc or GORM
|
||||
Validation: go-playground/validator
|
||||
Auth: Custom JWT
|
||||
```
|
||||
|
||||
#### Pros
|
||||
| Advantage | Details |
|
||||
|-----------|---------|
|
||||
| Performance | Fast, low memory |
|
||||
| Single binary | Easy deployment |
|
||||
| Concurrency | Goroutines handle load well |
|
||||
| Standard library | HTTP, JSON, crypto built-in |
|
||||
|
||||
#### Cons
|
||||
| Disadvantage | Details |
|
||||
|--------------|---------|
|
||||
| Verbose | Error handling boilerplate |
|
||||
| Smaller ecosystem | Fewer ready-made solutions |
|
||||
| Learning curve | Different paradigm |
|
||||
|
||||
#### Example Structure
|
||||
```
|
||||
cmd/
|
||||
├── server/
|
||||
│ └── main.go
|
||||
internal/
|
||||
├── api/
|
||||
│ ├── handlers/
|
||||
│ ├── middleware/
|
||||
│ └── routes.go
|
||||
├── domain/
|
||||
│ ├── app.go
|
||||
│ └── developer.go
|
||||
├── repository/
|
||||
│ └── postgres/
|
||||
└── service/
|
||||
```
|
||||
|
||||
#### Hosting Cost Estimate
|
||||
| Service | Cost/month |
|
||||
|---------|------------|
|
||||
| Fly.io (shared) | $5-15 |
|
||||
| Cloud Run | Pay per use |
|
||||
| VPS (2GB) | $10-20 |
|
||||
|
||||
---
|
||||
|
||||
### Option C: Rust + Axum
|
||||
|
||||
#### Stack
|
||||
```
|
||||
Language: Rust
|
||||
Framework: Axum
|
||||
ORM: sqlx or SeaORM
|
||||
Validation: validator crate
|
||||
Auth: Custom JWT
|
||||
```
|
||||
|
||||
#### Pros
|
||||
| Advantage | Details |
|
||||
|-----------|---------|
|
||||
| Maximum performance | Fastest option |
|
||||
| Memory safety | No runtime errors |
|
||||
| Single binary | Easy deployment |
|
||||
| Long-term reliability | Compiler catches bugs |
|
||||
|
||||
#### Cons
|
||||
| Disadvantage | Details |
|
||||
|--------------|---------|
|
||||
| Steep learning curve | Borrow checker takes time |
|
||||
| Slower development | More code to write |
|
||||
| Smaller ecosystem | Fewer web libraries |
|
||||
| Compile times | Can be slow |
|
||||
|
||||
#### Example Structure
|
||||
```
|
||||
src/
|
||||
├── main.rs
|
||||
├── api/
|
||||
│ ├── mod.rs
|
||||
│ ├── handlers/
|
||||
│ └── middleware/
|
||||
├── domain/
|
||||
├── repository/
|
||||
└── service/
|
||||
```
|
||||
|
||||
#### Hosting Cost Estimate
|
||||
| Service | Cost/month |
|
||||
|---------|------------|
|
||||
| Fly.io | $5-10 |
|
||||
| Shuttle | Free tier available |
|
||||
| VPS (1GB) | $5-10 |
|
||||
|
||||
---
|
||||
|
||||
### Option D: .NET (ASP.NET Core)
|
||||
|
||||
#### Stack
|
||||
```
|
||||
Language: C#
|
||||
Framework: ASP.NET Core 8
|
||||
ORM: Entity Framework Core
|
||||
Validation: FluentValidation
|
||||
Auth: ASP.NET Identity
|
||||
```
|
||||
|
||||
#### Pros
|
||||
| Advantage | Details |
|
||||
|-----------|---------|
|
||||
| Enterprise-ready | Battle-tested at scale |
|
||||
| Great tooling | Visual Studio, debugging |
|
||||
| Performance | Very fast (Kestrel) |
|
||||
| Full-featured | Auth, validation, DI built-in |
|
||||
|
||||
#### Cons
|
||||
| Disadvantage | Details |
|
||||
|--------------|---------|
|
||||
| Heavier runtime | Larger container images |
|
||||
| Microsoft ecosystem | May feel locked in |
|
||||
| Verbose | More boilerplate |
|
||||
|
||||
#### Hosting Cost Estimate
|
||||
| Service | Cost/month |
|
||||
|---------|------------|
|
||||
| Azure App Service | $15-50 |
|
||||
| VPS (4GB) | $20-40 |
|
||||
|
||||
---
|
||||
|
||||
## Evaluation Matrix
|
||||
|
||||
| Criteria | Weight | Node.js | Go | Rust | .NET |
|
||||
|----------|--------|---------|-----|------|------|
|
||||
| Dev speed | 25% | 9 | 7 | 5 | 7 |
|
||||
| Performance | 20% | 6 | 9 | 10 | 8 |
|
||||
| Hosting cost | 15% | 7 | 9 | 9 | 6 |
|
||||
| Ecosystem | 15% | 9 | 7 | 6 | 8 |
|
||||
| Team familiarity | 15% | ? | ? | ? | ? |
|
||||
| Long-term maintenance | 10% | 7 | 8 | 9 | 8 |
|
||||
| **Weighted Score** | | **7.4** | **7.8** | **7.2** | **7.3** |
|
||||
|
||||
*Team familiarity needs to be filled in based on actual experience*
|
||||
|
||||
---
|
||||
|
||||
## Framework Comparison
|
||||
|
||||
### Node.js Frameworks
|
||||
|
||||
| Framework | Req/sec | Features | Learning Curve |
|
||||
|-----------|---------|----------|----------------|
|
||||
| Express | 15k | Minimal, flexible | Easy |
|
||||
| Fastify | 45k | Fast, schema validation | Medium |
|
||||
| Hono | 50k | Ultra-light, edge-ready | Easy |
|
||||
| NestJS | 20k | Full-featured, Angular-like | Steep |
|
||||
|
||||
### Go Frameworks
|
||||
|
||||
| Framework | Req/sec | Features | Learning Curve |
|
||||
|-----------|---------|----------|----------------|
|
||||
| net/http | 60k | Standard library | Medium |
|
||||
| Chi | 55k | Lightweight router | Easy |
|
||||
| Gin | 50k | Popular, middleware | Easy |
|
||||
| Echo | 55k | Similar to Gin | Easy |
|
||||
|
||||
---
|
||||
|
||||
## Prototype Plan
|
||||
|
||||
### Phase 1: Build minimal API in top 2 choices
|
||||
|
||||
Endpoints to implement:
|
||||
```
|
||||
POST /auth/register
|
||||
POST /auth/login
|
||||
GET /apps
|
||||
POST /apps
|
||||
POST /apps/:id/versions
|
||||
```
|
||||
|
||||
### Phase 2: Benchmark
|
||||
|
||||
- Requests per second
|
||||
- Memory usage under load
|
||||
- Development time tracking
|
||||
- Code complexity comparison
|
||||
|
||||
### Phase 3: Decision
|
||||
|
||||
Based on:
|
||||
- Benchmark results
|
||||
- Developer experience during prototype
|
||||
- Hosting cost analysis
|
||||
|
||||
---
|
||||
|
||||
## Recommendation
|
||||
|
||||
**Primary: Go with Chi/Echo**
|
||||
- Best balance of performance and simplicity
|
||||
- Low hosting costs
|
||||
- Single binary deployment
|
||||
- Good enough ecosystem for our needs
|
||||
|
||||
**Fallback: Node.js with Hono/Fastify**
|
||||
- If Go feels too slow to develop in
|
||||
- Larger ecosystem for edge cases
|
||||
- More developers familiar with it
|
||||
|
||||
---
|
||||
|
||||
## Deliverables
|
||||
|
||||
- [x] Final selection with rationale
|
||||
- [ ] Project structure template
|
||||
- [ ] Development environment setup guide
|
||||
- [ ] Base Go project scaffolding
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. Do we need GraphQL or is REST sufficient?
|
||||
2. Do we need real-time features (WebSocket)?
|
||||
3. What's the team's current language experience?
|
||||
4. Any preference for specific cloud providers?
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [TechEmpower Benchmarks](https://www.techempower.com/benchmarks/)
|
||||
- [Go vs Node.js comparison](https://blog.logrocket.com/node-js-vs-golang/)
|
||||
- [Fastify benchmarks](https://fastify.dev/benchmarks/)
|
||||
Reference in New Issue
Block a user