making strides in the device and link domain setup

README.md

@@ -1,7 +1,72 @@
 # Illusory IOTAM
 
-This is the source code for a SaaS project with purposes to basically offer the users the ability to use specific Android applications, but instead of the apps running on their own phone, they run on our hosted Docker-Android instances.
+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.
 
-Right now the project is in alpha testing phase, so it is subject to change (greenfield project)
+Currently in alpha. Greenfield. Subject to change.
 
 ---
+
+## How It Works
+
+1. Admin generates a unique link and assigns it to a user (or a slot).
+2. User opens that link in their browser — served by `apps/front`.
+3. User waits while a Docker-Android device is allocated to their session.
+4. User is prompted to install the PWA.
+5. User opens the PWA — they are routed into a live stream of their assigned Android instance.
+6. 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, 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 — mark a device as in-use for a user session
+- [ ] Device release logic — free up a device when a session ends
+- [ ] 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)
+- [ ] Link domain in `@pkg/logic` — controller + repository + errors
+- [ ] Admin dashboard: Links page — generate links, view detail, configure linked device, revoke, delete
+- [ ] `apps/front`: validate incoming link token on request
+- [ ] `apps/front`: return appropriate error page for invalid/expired/revoked links
+
+### PWA & User Session Flow (`apps/front`)
+
+- [ ] `apps/front`: serve static PWA shell (HTML + manifest + service worker)
+- [ ] `apps/front`: wait/loading page — poll for device allocation status
+- [ ] `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