add developer portal planning documentation (M01-M12)

2026-01-18 17:20:51 +01:00
parent 9805bdf175
commit 5cfee2aa66
13 changed files with 6591 additions and 0 deletions
--- a/DEV_PORTAL_MILESTONES.md
+++ b/DEV_PORTAL_MILESTONES.md
@@ -0,0 +1,714 @@
+# Developer Portal & App Ecosystem Milestones
+
+Planning document for the Mosis app development, distribution, and monitoring ecosystem.
+
+---
+
+## Overview
+
+```
+Developer                          Mosis Platform                    User Device
+─────────────────────────────────────────────────────────────────────────────────
+Register Account ──────────────►  Developer Portal
+                                       │
+Create App Project ────────────►  App Registry
+                                       │
+Design UI (RML/RCSS/Lua) ──────►  Designer Tool (local)
+                                       │
+Test Locally ──────────────────►  Desktop Designer / Emulator
+                                       │
+Submit for Review ─────────────►  App Store Backend
+                                       │
+Publish ───────────────────────►  CDN / Distribution
+                                       │
+                                  Install ◄───────────────────  User Request
+                                       │
+                                  Run in Sandbox ◄────────────  Launch App
+                                       │
+                                  Telemetry/Crashes ──────────►  Analytics Backend
+```
+
+---
+
+## Decision Areas
+
+| Area | Options | Status |
+|------|---------|--------|
+| Web Stack | Node/Express, Go, Rust/Axum, .NET | TBD |
+| Database | PostgreSQL, SQLite, MongoDB | TBD |
+| Auth | OAuth2/OIDC, API keys, JWT | TBD |
+| CDN/Storage | S3, Cloudflare R2, self-hosted | TBD |
+| Telemetry | Custom, PostHog, Plausible | TBD |
+| Crash Reports | Sentry, custom, Crashlytics | TBD |
+| App Format | ZIP, custom package, signed | TBD |
+
+---
+
+## Milestone 1: App Package Format
+
+**Goal**: Define how apps are bundled, signed, and validated.
+
+### Questions to Answer
+
+1. What files comprise an app package?
+2. How is the manifest structured?
+3. How are apps signed for integrity?
+4. How are updates handled (full vs delta)?
+5. What metadata is required (name, version, permissions, icons)?
+
+### Considerations
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **ZIP archive** | Simple, standard tooling | No built-in signing |
+| **Custom format (.mosis)** | Can embed signature, metadata | Custom tooling needed |
+| **Signed ZIP** | Best of both, detached signature | Slightly more complex |
+
+### Proposed Structure
+
+```
+myapp.mosis/
+├── manifest.json        # App metadata, permissions, entry point
+├── signature.sig        # Detached signature (optional for dev)
+├── icon.png             # App icon (multiple sizes?)
+├── assets/
+│   ├── main.rml         # Entry point UI
+│   ├── styles.rcss      # Stylesheets
+│   └── scripts/
+│       └── app.lua      # Lua code
+└── locales/             # i18n (optional)
+    ├── en.json
+    └── es.json
+```
+
+### Manifest Schema (Draft)
+
+```json
+{
+  "id": "com.developer.appname",
+  "name": "My App",
+  "version": "1.0.0",
+  "version_code": 1,
+  "entry": "assets/main.rml",
+  "permissions": ["storage", "network"],
+  "min_mosis_version": "1.0.0",
+  "author": {
+    "name": "Developer Name",
+    "email": "dev@example.com"
+  },
+  "icons": {
+    "32": "icon-32.png",
+    "64": "icon-64.png",
+    "128": "icon-128.png"
+  }
+}
+```
+
+### Deliverables
+
+- [ ] Manifest JSON schema specification
+- [ ] Package format specification
+- [ ] Signing mechanism (key format, algorithm)
+- [ ] Package validation tool (CLI)
+- [ ] Package creation tool (CLI or integrated in designer)
+
+---
+
+## Milestone 2: Web Stack Selection
+
+**Goal**: Choose backend technologies for the developer portal and app store.
+
+### Options Analysis
+
+#### Option A: Node.js + Express/Fastify
+
+| Aspect | Details |
+|--------|---------|
+| Language | TypeScript |
+| Framework | Express, Fastify, or Hono |
+| Pros | Large ecosystem, easy hiring, fast development |
+| Cons | Single-threaded, callback complexity |
+| Hosting | Vercel, Railway, any VPS |
+
+#### Option B: Go
+
+| Aspect | Details |
+|--------|---------|
+| Language | Go |
+| Framework | Gin, Echo, or Chi |
+| Pros | Fast, low memory, single binary deployment |
+| Cons | Smaller ecosystem, verbose error handling |
+| Hosting | Any VPS, Cloud Run |
+
+#### Option C: Rust + Axum
+
+| Aspect | Details |
+|--------|---------|
+| Language | Rust |
+| Framework | Axum, Actix-web |
+| Pros | Maximum performance, memory safety |
+| Cons | Steep learning curve, slower development |
+| Hosting | Any VPS, Fly.io |
+
+#### Option D: .NET
+
+| Aspect | Details |
+|--------|---------|
+| Language | C# |
+| Framework | ASP.NET Core |
+| Pros | Enterprise-ready, great tooling, fast |
+| Cons | Heavier runtime, Microsoft ecosystem |
+| Hosting | Azure, any VPS |
+
+### Evaluation Criteria
+
+1. **Development speed** - How fast can we iterate?
+2. **Performance** - Can it handle scale?
+3. **Hosting cost** - Monthly infrastructure cost
+4. **Team familiarity** - Learning curve
+5. **Ecosystem** - Libraries for auth, storage, etc.
+
+### Deliverables
+
+- [ ] Prototype API in top 2 candidates
+- [ ] Benchmark comparison
+- [ ] Final selection with rationale
+
+---
+
+## Milestone 3: Database Selection
+
+**Goal**: Choose database for developer accounts, app metadata, analytics.
+
+### Options Analysis
+
+#### Option A: PostgreSQL
+
+| Aspect | Details |
+|--------|---------|
+| Type | Relational |
+| Pros | ACID, JSON support, mature, scalable |
+| Cons | Requires management, connection pooling |
+| Hosting | Supabase, Neon, RDS, self-hosted |
+
+#### Option B: SQLite + Litestream
+
+| Aspect | Details |
+|--------|---------|
+| Type | Embedded relational |
+| Pros | Zero ops, fast reads, simple backup |
+| Cons | Single-writer, limited concurrency |
+| Hosting | Embedded in app server |
+
+#### Option C: MongoDB
+
+| Aspect | Details |
+|--------|---------|
+| Type | Document |
+| Pros | Flexible schema, easy start |
+| Cons | Less ACID, can get expensive |
+| Hosting | Atlas, self-hosted |
+
+### Data Models Preview
+
+```
+developers
+├── id (UUID)
+├── email
+├── name
+├── api_keys[]
+├── created_at
+└── verified
+
+apps
+├── id (UUID)
+├── developer_id (FK)
+├── package_id (com.dev.app)
+├── name
+├── description
+├── versions[]
+├── status (draft/review/published/suspended)
+├── created_at
+└── updated_at
+
+app_versions
+├── id (UUID)
+├── app_id (FK)
+├── version_code
+├── version_name
+├── package_url
+├── signature
+├── release_notes
+├── status
+└── published_at
+
+telemetry_events
+├── id
+├── app_id
+├── device_id (anonymized)
+├── event_type
+├── event_data (JSON)
+├── timestamp
+└── mosis_version
+```
+
+### Deliverables
+
+- [ ] Schema design for all tables
+- [ ] Migration strategy
+- [ ] Backup/restore plan
+- [ ] Final selection with rationale
+
+---
+
+## Milestone 4: Authentication System
+
+**Goal**: Secure developer authentication and app signing.
+
+### Developer Authentication
+
+| Method | Use Case |
+|--------|----------|
+| OAuth2 (GitHub/Google) | Portal login |
+| Email + Password | Alternative login |
+| API Keys | CLI tools, CI/CD |
+| JWT | Session tokens |
+
+### App Signing
+
+| Approach | Details |
+|----------|---------|
+| **Developer keypair** | Dev signs with private key, we verify with public |
+| **Platform signing** | We sign after review (like iOS) |
+| **Both** | Dev signs, we countersign after review |
+
+### Key Management
+
+- Developer generates keypair locally
+- Public key uploaded to portal
+- Private key never leaves developer machine
+- Key rotation supported
+
+### Deliverables
+
+- [ ] OAuth2 integration (GitHub, Google)
+- [ ] API key generation and management
+- [ ] Developer keypair registration
+- [ ] App signature verification
+- [ ] JWT token handling
+
+---
+
+## Milestone 5: Developer Portal Frontend
+
+**Goal**: Web interface for developer account and app management.
+
+### Pages Required
+
+| Page | Features |
+|------|----------|
+| **Landing** | Sign up, sign in, overview |
+| **Dashboard** | App list, quick stats |
+| **App Details** | Versions, analytics, settings |
+| **Create App** | Wizard for new app |
+| **Submit Version** | Upload, release notes, submit |
+| **API Keys** | Generate, revoke keys |
+| **Profile** | Account settings, keys |
+| **Docs** | SDK docs, API reference |
+
+### Tech Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| Next.js | SSR, React, full-stack | Complexity |
+| SvelteKit | Fast, simple, SSR | Smaller ecosystem |
+| Astro + React | Static + islands | Newer |
+| Plain HTML + htmx | Simple, fast | Limited interactivity |
+
+### Deliverables
+
+- [ ] Framework selection
+- [ ] UI component library selection
+- [ ] Page wireframes
+- [ ] Implementation
+
+---
+
+## Milestone 6: App Store Backend API
+
+**Goal**: REST/GraphQL API for app submission, review, and distribution.
+
+### API Endpoints (Draft)
+
+```
+Auth
+├── POST   /auth/register
+├── POST   /auth/login
+├── POST   /auth/logout
+├── GET    /auth/me
+
+Apps
+├── GET    /apps                    # List developer's apps
+├── POST   /apps                    # Create new app
+├── GET    /apps/:id                # Get app details
+├── PATCH  /apps/:id                # Update app metadata
+├── DELETE /apps/:id                # Delete app (if no published versions)
+
+Versions
+├── GET    /apps/:id/versions       # List versions
+├── POST   /apps/:id/versions       # Upload new version
+├── GET    /apps/:id/versions/:vid  # Get version details
+├── POST   /apps/:id/versions/:vid/submit   # Submit for review
+├── POST   /apps/:id/versions/:vid/publish  # Publish (after review)
+
+Public (App Store)
+├── GET    /store/apps              # Browse/search apps
+├── GET    /store/apps/:id          # App store listing
+├── GET    /store/apps/:id/download # Download latest version
+
+API Keys
+├── GET    /keys                    # List API keys
+├── POST   /keys                    # Generate new key
+├── DELETE /keys/:id                # Revoke key
+
+Telemetry (device → server)
+├── POST   /telemetry/events        # Batch event upload
+├── POST   /telemetry/crash         # Crash report
+```
+
+### Deliverables
+
+- [ ] OpenAPI specification
+- [ ] Rate limiting strategy
+- [ ] Authentication middleware
+- [ ] Implementation
+
+---
+
+## Milestone 7: CDN & Storage
+
+**Goal**: Scalable storage for app packages and assets.
+
+### Requirements
+
+1. Store app packages (.mosis files)
+2. Serve downloads globally with low latency
+3. Handle icons and screenshots
+4. Version retention policy
+5. Bandwidth cost management
+
+### Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Cloudflare R2** | No egress fees, global | Newer service |
+| **AWS S3 + CloudFront** | Mature, reliable | Egress costs |
+| **Backblaze B2 + Cloudflare** | Cheap storage, free egress via CF | More setup |
+| **Self-hosted MinIO** | Full control | Ops burden |
+
+### Storage Structure
+
+```
+/packages/
+  /{app_id}/
+    /{version_code}/
+      package.mosis
+      signature.sig
+
+/assets/
+  /{app_id}/
+    icon-32.png
+    icon-64.png
+    icon-128.png
+    screenshots/
+      1.png
+      2.png
+```
+
+### Deliverables
+
+- [ ] Storage provider selection
+- [ ] CDN configuration
+- [ ] Upload flow (presigned URLs vs direct)
+- [ ] Download URL generation
+- [ ] Retention/cleanup policy
+
+---
+
+## Milestone 8: Telemetry System
+
+**Goal**: Collect app usage analytics and crash reports.
+
+### Event Types
+
+| Category | Events |
+|----------|--------|
+| **Lifecycle** | app_start, app_stop, app_crash |
+| **Performance** | frame_time, memory_usage, lua_errors |
+| **Usage** | screen_view, button_click (opt-in) |
+| **System** | mosis_version, device_info |
+
+### Privacy Considerations
+
+1. **No PII by default** - Device ID is hashed, no user data
+2. **Opt-in for detailed analytics** - User consent required
+3. **Data retention** - Auto-delete after X days
+4. **GDPR compliance** - Export/delete on request
+5. **Aggregation** - Store aggregates, drop raw after processing
+
+### Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| **Custom** | Full control, no vendor lock | Build everything |
+| **PostHog** | Self-hostable, feature-rich | Can be heavy |
+| **Plausible** | Privacy-focused, simple | Limited features |
+| **Segment + warehouse** | Flexible routing | Complex, costly |
+
+### Crash Report Schema
+
+```json
+{
+  "app_id": "com.dev.app",
+  "app_version": "1.0.0",
+  "mosis_version": "1.0.0",
+  "device_id": "hashed",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "crash_type": "lua_error",
+  "message": "attempt to index nil value",
+  "stack_trace": "...",
+  "context": {
+    "screen": "main.rml",
+    "memory_mb": 45,
+    "uptime_seconds": 120
+  }
+}
+```
+
+### Deliverables
+
+- [ ] Event schema specification
+- [ ] Collection endpoint
+- [ ] Storage strategy (time-series DB?)
+- [ ] Dashboard for developers
+- [ ] Privacy controls
+
+---
+
+## Milestone 9: App Review System
+
+**Goal**: Automated and manual review process for app submissions.
+
+### Automated Checks
+
+| Check | Description |
+|-------|-------------|
+| **Manifest validation** | Required fields, valid permissions |
+| **Package integrity** | Signature verification |
+| **Static analysis** | Dangerous Lua patterns |
+| **Asset validation** | Icons present, correct sizes |
+| **Size limits** | Package under max size |
+| **Duplicate detection** | Same app ID collision |
+
+### Manual Review (Optional)
+
+- Flag for manual review based on:
+  - New developer (first app)
+  - Dangerous permissions requested
+  - Automated check warnings
+  - User reports
+
+### Review States
+
+```
+draft → submitted → in_review → approved → published
+                  ↘ rejected (with feedback)
+```
+
+### Deliverables
+
+- [ ] Automated validation pipeline
+- [ ] Review queue UI
+- [ ] Rejection feedback system
+- [ ] Appeal process
+
+---
+
+## Milestone 10: Device-Side App Management
+
+**Goal**: Install, update, and manage apps on Mosis devices.
+
+### Components
+
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| App Manager | MosisService | Install/uninstall/update apps |
+| App Store Client | System app | Browse, search, install UI |
+| Update Checker | Background service | Check for updates |
+
+### Installation Flow
+
+```
+1. User taps "Install" in App Store
+2. Download package from CDN
+3. Verify signature
+4. Extract to app directory
+5. Register with LuaSandboxManager
+6. Add to home screen
+```
+
+### Update Flow
+
+```
+1. Background check for updates (daily?)
+2. Notify user of available updates
+3. Download new version
+4. Verify signature
+5. Replace app files (atomic swap)
+6. Restart app if running
+```
+
+### Storage Layout
+
+```
+/data/mosis/
+  /apps/
+    /com.dev.app/
+      /package/          # Extracted app files
+      /data/             # App data (VirtualFS)
+      /cache/            # App cache
+      /db/               # SQLite databases
+```
+
+### Deliverables
+
+- [ ] AppManager class in MosisService
+- [ ] App Store system app
+- [ ] Update checking service
+- [ ] Uninstall with data cleanup
+
+---
+
+## Milestone 11: Developer CLI Tool
+
+**Goal**: Command-line tool for app development workflow.
+
+### Commands
+
+```bash
+# Project management
+mosis init                    # Create new app project
+mosis validate                # Validate manifest and assets
+
+# Packaging
+mosis build                   # Create .mosis package
+mosis sign                    # Sign package with developer key
+
+# Testing
+mosis run                     # Run in local designer/emulator
+mosis test                    # Run automated tests
+
+# Publishing
+mosis login                   # Authenticate with portal
+mosis publish                 # Upload and submit for review
+mosis status                  # Check review status
+
+# Keys
+mosis keys generate           # Generate signing keypair
+mosis keys register           # Upload public key to portal
+```
+
+### Implementation Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| Node.js (oclif) | Easy to build, npm distribution | Requires Node |
+| Go | Single binary, fast | Slower development |
+| Rust (clap) | Single binary, fast | Slower development |
+
+### Deliverables
+
+- [ ] CLI framework selection
+- [ ] Core commands implementation
+- [ ] Distribution (npm, homebrew, direct download)
+- [ ] Documentation
+
+---
+
+## Milestone 12: Documentation Site
+
+**Goal**: Comprehensive docs for developers.
+
+### Sections
+
+| Section | Content |
+|---------|---------|
+| **Getting Started** | Quick start, first app tutorial |
+| **Guides** | UI design, Lua scripting, permissions |
+| **API Reference** | All Lua APIs, manifest schema |
+| **CLI Reference** | All commands and options |
+| **Best Practices** | Performance, security, UX |
+| **Troubleshooting** | Common issues, FAQ |
+
+### Tech Options
+
+| Option | Pros | Cons |
+|--------|------|------|
+| Docusaurus | React-based, versioning | Heavy |
+| VitePress | Vue-based, fast | Less features |
+| Astro Starlight | Fast, modern | Newer |
+| MkDocs | Python, simple | Less customizable |
+
+### Deliverables
+
+- [ ] Framework selection
+- [ ] Information architecture
+- [ ] Content writing
+- [ ] API docs generation from code
+- [ ] Search integration
+
+---
+
+## Summary
+
+| Phase | Milestones | Description |
+|-------|------------|-------------|
+| **Foundation** | 1-4 | Package format, web stack, database, auth |
+| **Portal** | 5-6 | Developer portal frontend and API |
+| **Distribution** | 7, 10 | CDN/storage, device-side app management |
+| **Quality** | 8-9 | Telemetry, crash reports, review system |
+| **Tooling** | 11-12 | CLI tool, documentation |
+
+### Recommended Order
+
+1. **Milestone 1** - Package format (needed by everything)
+2. **Milestone 2** - Web stack selection
+3. **Milestone 3** - Database selection
+4. **Milestone 4** - Authentication
+5. **Milestone 6** - Backend API
+6. **Milestone 5** - Portal frontend
+7. **Milestone 7** - CDN/storage
+8. **Milestone 10** - Device-side management
+9. **Milestone 11** - CLI tool
+10. **Milestone 9** - Review system
+11. **Milestone 8** - Telemetry
+12. **Milestone 12** - Documentation
+
+---
+
+## Open Questions
+
+1. **Monetization model?** - Free only, paid apps, subscriptions?
+2. **Enterprise/self-hosted?** - Can companies run private app stores?
+3. **App categories?** - Predefined or free-form tags?
+4. **Rating/reviews?** - User reviews for apps?
+5. **Analytics dashboard?** - What metrics do developers see?
+6. **Localization?** - Multi-language portal and apps?
+7. **Beta testing?** - TestFlight-like distribution?
+8. **Team accounts?** - Multiple developers per app?
+
+---
+
+## Next Steps
+
+Begin with Milestone 1 (App Package Format) to establish the foundation, then proceed with technology selections in Milestones 2-4 before building the portal.