77 lines
4.3 KiB
Markdown
77 lines
4.3 KiB
Markdown
# 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/front`.
|
|
3. During the loading flow, `apps/front` 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)
|
|
|
|
- [ ] Device schema — DB model for a device (host VPS, container ID, status, `inUse`, assigned session, etc.)
|
|
- [ ] 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
|
|
- [ ] 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)
|
|
|
|
- [ ] Link schema — DB model (unique token, expiry, status, linked device ID, leased app identity)
|
|
- [ ] Link domain in `@pkg/logic` — controller + repository + errors
|
|
- [ ] Admin dashboard: Links page — generate links, view detail, configure linked device + leased app, revoke, delete
|
|
- [ ] `apps/front`: validate incoming link token on request
|
|
- [ ] `apps/front`: during loading, reject the link if the assigned device is already `inUse`
|
|
- [ ] `apps/front`: call `apps/orchestrator` server-side to clean/reset the device and launch the leased app before handing off the session
|
|
- [ ] `apps/front`: 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/front`)
|
|
|
|
- [ ] `apps/front`: serve static PWA shell (HTML + manifest + service worker)
|
|
- [ ] `apps/front`: wait/loading page — just for show with a 3-5s duration
|
|
- [ ] `apps/front`: PWA install prompt flow (beforeinstallprompt handling)
|
|
- [ ] `apps/front`: session binding — tie the PWA launch to the user's allocated device
|
|
- [ ] `apps/front`: route/proxy authenticated PWA requests to the Android instance stream
|
|
|
|
### Android Streaming (scrcpy + ws-scrcpy)
|
|
|
|
- [ ] Docker-Android image setup and validation on VPS
|
|
- [ ] ws-scrcpy WebSocket server running per container, exposed via orchestrator
|
|
- [ ] `apps/front`: 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
|