MosisService/docs/DEV_PORTAL_M02_WEB_STACK.md

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

• 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
• Go vs Node.js comparison
• Fastify benchmarks