MosisService/docs/DEV_PORTAL_MILESTONES.md

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)

{
  "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

{
  "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

# 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.