How dexter-lab-ctrl/pocket-lab-lite works
Purpose and Entry Points
Pocket Lab Lite is an edge-first, self-hostable control plane for Android/Termux and low-power hosts. It manages local devices, apps, recovery, security, releases, and operational workflows through a PWA and local API. Runtime entry points are the React bootstrap at src/main.jsx, FastAPI application at pocket-lab-final-structure/runtime/api_fastapi/main.py, worker at pocket-lab-final-structure/runtime/workers/pocketlab_worker.py, and device supervisor at pocket-lab-final-structure/runtime/agents/pocketlab_agent_supervisor.py. Production installation begins through pocket-lab-final-structure/pocket-lab-bootstrap-production-scripts-patched/scripts/bootstrap.sh.
UI and Client-State Boundary
The Vite/React PWA is the sole browser-facing client; its Lite application shell and screen registry are src/lite/LiteApp.jsx and src/lite/liteScreenRegistry.js. It calls FastAPI through src/lib/liteApi.js, maintains query/offline behavior in src/lib/liteQueryClient.js and src/lib/liteOfflineDb.js, and uses explicit state machines for destructive or multi-step flows, e.g. src/machines/liteRecoveryFlowMachine.js. The UI does not connect to NATS, execute commands, or hold server secrets; it consumes API reads, mutation results, and live events.
Control API and Domain Services
FastAPI is the control-plane boundary and exposes domain routers under pocket-lab-final-structure/runtime/api_fastapi/routers/, notably lite.py, fleet.py, security.py, release.py, and websocket.py. Its composition and dependency setup live in pocket-lab-final-structure/runtime/api_fastapi/main.py and deps.py. Service-layer code owns domain behavior rather than routers: app lifecycle (services/lite_app_lifecycle.py), recovery transactions (services/lite_restore_transaction.py), security persistence/execution (services/lite_security_store.py), and release orchestration (services/release_orchestrator.py).
Evented Execution, Workers, and Device Control
Requests that require execution are admitted, converted into commands/workflows, and dispatched asynchronously rather than performed in the HTTP request path. Core mechanisms are services/action_queue.py, services/workflow_engine.py, and services/domain_commands.py. NATS/JetStream provides durable messaging through services/nats_bus.py, governed by the event contract contracts/asyncapi/pocketlab-nats-jetstream.yaml. The worker consumes and performs backend work at runtime/workers/pocketlab_worker.py; node agents and supervisors own device execution, heartbeats, restart, and recovery at runtime/agents/pocketlab_node_agent.py and runtime/agents/pocketlab_agent_supervisor.py.
Durable State, Projections, and Recovery
SQLite is the local system of record, with connection/migration ownership in runtime/api_fastapi/db/connection.py and db/migrations.py. Ordered SQL migrations in runtime/api_fastapi/db/schema/ establish command, workflow, device, release, security, and projection tables. Event/workflow state is turned into API-optimized prepared reads by services/projection_scheduler.py and services/workflow_projection_process.py; this separates execution truth from read models. Backup, restore preview, guarded restore, and post-restore reconciliation are implemented around services/lite_backup.py, services/lite_restore_planner.py, and services/lite_database_recovery.py.
Deployment and External Integrations
The target runtime is Android/Termux, optionally running Ubuntu under proot; PM2 supervises processes, Caddy supplies same-origin routing, and SQLite/NATS run locally. Runtime topology is captured in contracts/generated/runtime/termux-platform.json, contracts/generated/runtime/caddy-routing.json, and contracts/generated/runtime/nats-topology.json. Tailscale provides private remote access; PhotoPrism is a managed media application. Bootstrap scripts install and configure these dependencies, including scripts/install-proot-ubuntu.sh, scripts/install-tailscale.sh, and scripts/lite/install-photoprism-proot.sh.
Contracts, Architecture Evidence, and Release Boundary
This repository also produces the contracts and generated operational documentation used to constrain the runtime. OpenAPI authority is contracts/openapi.json; shared event/telemetry schemas are in contracts/schemas/. Architecture source is maintained in architecture/structurizr/workspace.dsl, while generation scripts produce documentation, contract projections, and runtime evidence from source artifacts (scripts/docs/lite/generate_contracts.py, scripts/docs/lite/generate_docs.py, scripts/docs/runtime/generate_termux_runtime_docs.py). Release packaging deliberately excludes development tooling, state, traces, and secrets, with release orchestration defined through Taskfile.yml and tasks/Taskfile.release.yml.
Main entry points: main.py FastAPI control API · lite_app_lifecycle.py Domain services · nats_bus.py NATS / JetStream · connection.py SQLite system of record
Components 21
PWA Client
- React PWA bootstrap
src/main.jsx - Lite app shell · Owns screen registry and browser workflows.
src/lite/LiteApp.jsx - API, query & offline state · API client, query cache, and offline database.
src/lib/liteApi.js - Recovery flow machine
src/machines/liteRecoveryFlowMachine.js
Control Plane
- FastAPI control API · HTTP and WebSocket boundary for the PWA.
pocket-lab-final-structure/runtime/api_fastapi/main.py - Domain routers · Lite, fleet, security, release, and WebSocket endpoints.
- Domain services · Lifecycle, restore, security, and release behavior.
pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py
Execution & State
- Commands & workflows · Admits actions and creates asynchronous work.
pocket-lab-final-structure/runtime/api_fastapi/services/workflow_engine.py - NATS / JetStream
pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py - Async event contract
- Backend worker · Consumes commands and performs backend work.
pocket-lab-final-structure/runtime/workers/pocketlab_worker.py - SQLite system of record · Stores command, workflow, device, release, security, and projection state.
pocket-lab-final-structure/runtime/api_fastapi/db/connection.py - Read-model projections · Builds API-optimized reads from event and workflow state.
pocket-lab-final-structure/runtime/api_fastapi/services/projection_scheduler.py - Backup & guarded recovery · Plans restores and reconciles state after recovery.
pocket-lab-final-structure/runtime/api_fastapi/services/lite_restore_planner.py
Host Runtime
- Device supervisor · Supervises node agents, restarts, and recovery.
pocket-lab-final-structure/runtime/agents/pocketlab_agent_supervisor.py - Node agent · Executes device commands and emits heartbeats.
pocket-lab-final-structure/runtime/agents/pocketlab_node_agent.py - Termux local stack · PM2, Caddy, SQLite, and NATS on Android/Termux or proot Ubuntu.
- Production bootstrap · Installs and configures the self-hosted runtime.
pocket-lab-final-structure/pocket-lab-bootstrap-production-scripts-patched/scripts/bootstrap.sh
Contracts & Delivery
- OpenAPI authority
- Architecture & generated docs · Source architecture drives contract and runtime documentation generation.
- Release packaging · Packages runtime while excluding tooling, state, traces, and secrets.
Connections 24
- React PWA bootstrap → Lite app shell: mounts
- Lite app shell → API, query & offline state: uses
- Lite app shell → Recovery flow machine: drives recovery
- API, query & offline state → FastAPI control API: HTTP and live events
- FastAPI control API → Domain routers: composes
- Domain routers → Domain services: delegates
- Domain services → Commands & workflows: requests execution
- Domain services → Backup & guarded recovery: coordinates restore
- Domain services → SQLite system of record: reads and writes
- Commands & workflows → NATS / JetStream: dispatches durable commands
- Async event contract → NATS / JetStream: governs messages
- NATS / JetStream → Backend worker: consumed by
- Backend worker → Device supervisor: invokes device work
- Device supervisor → Node agent: supervises
- Backend worker → SQLite system of record: persists execution state
- SQLite system of record → Read-model projections: state source
- Read-model projections → FastAPI control API: prepared reads
- Backup & guarded recovery → SQLite system of record: backs up and restores
- Production bootstrap → Termux local stack: installs
- Termux local stack → FastAPI control API: hosts
- Termux local stack → NATS / JetStream: hosts locally
- OpenAPI authority → FastAPI control API: constrains API
- Architecture & generated docs → OpenAPI authority: generates evidence for
- Release packaging → Production bootstrap: packages for installation