# Illusory IOTAM

A SaaS platform that lets users run specific Android applications on hosted Docker-Android instances — instead of on their own device. Users get a unique link, install a PWA, and are streamed a live Android session from the cloud.

Currently in alpha. Greenfield. Subject to change.

---

## How It Works

1. Admin generates a unique link and assigns it to a specific Android app on a specific device.
2. User opens that link in their browser — served by `apps/frontend`.
3. During the loading flow, `apps/frontend` validates the link and asks `apps/orchestrator` to reset the assigned Android session and launch the leased app.
4. If that device is already in use by another end user, the link fails instead of taking over the session.
5. User is prompted to install the PWA.
6. User opens the PWA — they are routed into a live stream of their assigned Android app session.
7. Admin manages the entire fleet from `apps/main` (the dashboard), which communicates with `apps/orchestrator` running on each VPS to control Docker-Android containers.

---

## Implementation Checklist

### Foundation

- [x] Monorepo setup (Turborepo + pnpm)
- [x] Shared packages: `@pkg/logic`, `@pkg/db`, `@pkg/logger`, `@pkg/result`, `@pkg/keystore`, `@pkg/settings`
- [x] PostgreSQL with Drizzle ORM
- [x] Redis (Valkey) via `@pkg/keystore`
- [x] OpenTelemetry end-to-end (logs, traces, metrics → SigNoz)
- [x] Auth system (Better Auth — email/password, magic link, 2FA/TOTP, sessions)
- [x] User management (roles, bans, account operations)
- [x] Notifications system (priority, archiving, bulk ops)
- [x] Admin dashboard shell (`apps/main` — SvelteKit)
- [x] Background task tracking schema (task table)

### Device Management (Orchestrator + Admin)

- [x] Device schema — DB model for a device (host VPS, container ID, status, `inUse`, assigned session, etc.)
- [x] Device domain in `@pkg/logic` — controller + repository + errors
- [ ] Orchestrator command interface — secured Hono routes the admin dashboard calls:
    - [ ] `POST /devices/:id/start` — start a Docker-Android container
    - [ ] `POST /devices/:id/stop` — stop a container
    - [ ] `POST /devices/:id/restart` — restart a container
    - [ ] `GET /devices` — list all devices and their current status
    - [ ] `GET /devices/:id` — page to view the device in more detail (info, live stream feed with ws-scrcpy)
- [ ] Device allocation logic — atomically mark a device as `inUse` when a validated link starts a session
- [ ] Device release logic — clear `inUse` when a session ends or fails during setup
- [x] Admin dashboard: Devices page — list fleet, show status, trigger start/stop/restart
- [ ] Internal API key auth between `apps/main` and `apps/orchestrator`

### Link Management (Admin + Front App)

- [x] Link schema — DB model (unique token, expiry, status, linked device ID, leased app identity)
- [x] Link domain in `@pkg/logic` — controller + repository + errors
- [x] Admin dashboard: Links page — generate links, view detail, configure linked device + leased app, revoke, delete
- [ ] `apps/frontend`: validate incoming link token on request
- [ ] `apps/frontend`: during loading, reject the link if the assigned device is already `inUse`
- [ ] `apps/frontend`: call `apps/orchestrator` server-side to clean/reset the device and launch the leased app before handing off the session
- [ ] `apps/frontend`: return appropriate error page for invalid/expired/revoked links
- [ ] Front: keep on checking for link status change, if it gets revoked, we cutoff the connection

### PWA & User Session Flow (`apps/frontend`)

- [ ] `apps/frontend`: serve static PWA shell (HTML + manifest + service worker)
- [ ] `apps/frontend`: wait/loading page — just for show with a 3-5s duration
- [ ] `apps/frontend`: PWA install prompt flow (beforeinstallprompt handling)
- [ ] `apps/frontend`: session binding — tie the PWA launch to the user's allocated device
- [ ] `apps/frontend`: route/proxy authenticated PWA requests to the Android instance stream

### Android Streaming (scrcpy + ws-scrcpy)

- [x] Docker-Android image setup and validation on VPS
- [x] ws-scrcpy WebSocket server running per container, exposed via orchestrator
- [ ] `apps/frontend`: scrcpy client embedded in PWA — renders the Android stream in browser
- [ ] Input forwarding (touch/keyboard events → scrcpy → Android container)
- [ ] Session timeout + stream teardown on inactivity
