MosisService/docs/DEVELOPER-PORTAL.md

Developer Portal

The Developer Portal is a web application for app developers to publish and manage their Mosis apps. Planning documents are in DEV_PORTAL_M01-M12.md files.

Architecture Decisions

Component	Technology	Rationale
Backend	Go 1.22+	Simple, fast, single binary deployment
Router	Chi	Lightweight, idiomatic Go HTTP routing
Database	SQLite + Litestream	Zero-ops, continuous backup to NAS storage
Frontend	htmx + Go templates	Server-rendered, minimal JS, fast
Storage	Synology NAS filesystem	Self-hosted, local volume mounts
Auth	OAuth2 (GitHub/Google) + JWT	golang-jwt for tokens, Ed25519 for signing
CLI	Go + Cobra	Cross-platform single binary
Docs	Hugo + Docsy	Static site served from /docs/

Deployment Target

Self-hosted on Synology NAS via Docker:

/volume1/mosis/
├── data/
│   ├── portal.db       # Main SQLite database
│   └── telemetry.db    # Separate telemetry database
├── packages/           # Uploaded app packages
│   └── {dev_id}/{app_id}/{version}/
├── backups/            # Litestream replicas
└── docs/               # Hugo static site output

Milestone Documents

File	Topic	Status
DEV_PORTAL_M01_OVERVIEW.md	Project overview	Decided
DEV_PORTAL_M02_WEB_STACK.md	Go + Chi + htmx	Decided
DEV_PORTAL_M03_DATABASE.md	SQLite + Litestream	Decided
DEV_PORTAL_M04_AUTH.md	OAuth2 + JWT + Ed25519	Decided
DEV_PORTAL_M05_FRONTEND.md	htmx + Go templates	Decided
DEV_PORTAL_M06_API.md	REST API design	Decided
DEV_PORTAL_M07_STORAGE.md	NAS filesystem	Decided
DEV_PORTAL_M08_TELEMETRY.md	SQLite + background workers	Decided
DEV_PORTAL_M09_REVIEW.md	Go validation workers	Decided
DEV_PORTAL_M10_DEVICE.md	C++ AppManager	Decided
DEV_PORTAL_M11_CLI.md	Go + Cobra CLI	Decided
DEV_PORTAL_M12_DOCS.md	Hugo + Docsy	Decided

Key Design Principles

1. Single container - Portal runs as one Docker container on NAS
2. No external services - SQLite, local filesystem, Pagefind search
3. Pure Go - modernc.org/sqlite (no CGO required)
4. Server-rendered - htmx for interactivity, no SPA framework
5. Background workers - Go goroutines for aggregation/cleanup jobs