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