# dexter-lab-ctrl/pocket-lab-lite architecture

> Architecture diagram of the GitHub repository dexter-lab-ctrl/pocket-lab-lite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dexter-lab-ctrl/pocket-lab-lite
- Repository: https://github.com/dexter-lab-ctrl/pocket-lab-lite

## Overview

#### 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: [`pocket-lab-final-structure/runtime/api_fastapi/main.py`](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/main.py) (FastAPI control API), [`pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py`](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py) (Domain services), [`pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py`](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py) (NATS / JetStream), [`pocket-lab-final-structure/runtime/api_fastapi/db/connection.py`](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/db/connection.py) (SQLite system of record)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["PWA Client"]
  node_react_bootstrap["React PWA bootstrap<br/>Vite entry<br/>[main.jsx]"]
  node_lite_shell["Lite app shell<br/>React shell<br/>[LiteApp.jsx]"]
  node_client_data["API, query &amp; offline state<br/>client state<br/>[liteApi.js]"]
  node_recovery_machine["Recovery flow machine<br/>state machine"]
end

subgraph group_api["Control Plane"]
  node_fastapi["FastAPI control API<br/>FastAPI app<br/>[main.py]"]
  node_domain_routers["Domain routers<br/>API routers"]
  node_domain_services["Domain services<br/>service layer"]
end

subgraph group_execution["Execution &amp; State"]
  node_workflow_engine{{"Commands &amp; workflows<br/>execution orchestration<br/>[workflow_engine.py]"}}
  node_nats["NATS / JetStream<br/>durable event bus<br/>[nats_bus.py]"]
  node_event_contract["Async event contract<br/>AsyncAPI contract"]
  node_worker["Backend worker<br/>worker runtime"]
  node_sqlite[("SQLite system of record<br/>local database<br/>[connection.py]")]
  node_projections["Read-model projections<br/>projection pipeline"]
  node_backup_recovery["Backup &amp; guarded recovery<br/>recovery service"]
end

subgraph group_runtime["Host Runtime"]
  node_agent_supervisor["Device supervisor<br/>agent supervisor"]
  node_node_agent["Node agent<br/>device executor"]
  node_termux_stack["Termux local stack<br/>deployment topology"]
  node_bootstrap["Production bootstrap<br/>installer<br/>[bootstrap.sh]"]
end

subgraph group_delivery["Contracts &amp; Delivery"]
  node_api_contract["OpenAPI authority<br/>API contract"]
  node_architecture_docs["Architecture &amp; generated docs<br/>architecture evidence"]
  node_release["Release packaging<br/>release workflow"]
end

node_react_bootstrap -->|"mounts"| node_lite_shell
node_lite_shell -->|"uses"| node_client_data
node_lite_shell -->|"drives recovery"| node_recovery_machine
node_client_data -->|"HTTP and live events"| node_fastapi
node_fastapi -->|"composes"| node_domain_routers
node_domain_routers -->|"delegates"| node_domain_services
node_domain_services -->|"requests execution"| node_workflow_engine
node_domain_services -->|"coordinates restore"| node_backup_recovery
node_domain_services -->|"reads and writes"| node_sqlite
node_workflow_engine -->|"dispatches durable commands"| node_nats
node_event_contract -.->|"governs messages"| node_nats
node_nats -->|"consumed by"| node_worker
node_worker -->|"invokes device work"| node_agent_supervisor
node_agent_supervisor -->|"supervises"| node_node_agent
node_worker -->|"persists execution state"| node_sqlite
node_sqlite -->|"state source"| node_projections
node_projections -->|"prepared reads"| node_fastapi
node_backup_recovery -->|"backs up and restores"| node_sqlite
node_bootstrap -->|"installs"| node_termux_stack
node_termux_stack -->|"hosts"| node_fastapi
node_termux_stack -->|"hosts locally"| node_nats
node_api_contract -.->|"constrains API"| node_fastapi
node_architecture_docs -.->|"generates evidence for"| node_api_contract
node_release -->|"packages for installation"| node_bootstrap

click node_react_bootstrap "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/main.jsx"
click node_lite_shell "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/lite/LiteApp.jsx"
click node_client_data "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/lib/liteApi.js"
click node_recovery_machine "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/machines/liteRecoveryFlowMachine.js"
click node_fastapi "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/main.py"
click node_domain_services "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py"
click node_workflow_engine "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/workflow_engine.py"
click node_nats "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py"
click node_worker "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/workers/pocketlab_worker.py"
click node_agent_supervisor "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/agents/pocketlab_agent_supervisor.py"
click node_node_agent "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/agents/pocketlab_node_agent.py"
click node_sqlite "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/db/connection.py"
click node_projections "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/projection_scheduler.py"
click node_backup_recovery "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/lite_restore_planner.py"
click node_bootstrap "https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/pocket-lab-bootstrap-production-scripts-patched/scripts/bootstrap.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_bootstrap,node_lite_shell,node_client_data,node_recovery_machine toneBlue
class node_fastapi,node_domain_routers,node_domain_services toneAmber
class node_workflow_engine,node_nats,node_event_contract,node_worker,node_sqlite,node_projections,node_backup_recovery toneMint
class node_agent_supervisor,node_node_agent,node_termux_stack,node_bootstrap toneRose
class node_api_contract,node_architecture_docs,node_release toneIndigo
```

## Components

### PWA Client

- [React PWA bootstrap](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/main.jsx): Vite entry · `src/main.jsx`
- [Lite app shell](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/lite/LiteApp.jsx): React shell · Owns screen registry and browser workflows. · `src/lite/LiteApp.jsx`
- [API, query & offline state](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/lib/liteApi.js): client state · API client, query cache, and offline database. · `src/lib/liteApi.js`
- [Recovery flow machine](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/src/machines/liteRecoveryFlowMachine.js): state machine · `src/machines/liteRecoveryFlowMachine.js`

### Control Plane

- [FastAPI control API](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/main.py): FastAPI app · HTTP and WebSocket boundary for the PWA. · `pocket-lab-final-structure/runtime/api_fastapi/main.py`
- **Domain routers**: API routers · Lite, fleet, security, release, and WebSocket endpoints.
- [Domain services](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py): service layer · Lifecycle, restore, security, and release behavior. · `pocket-lab-final-structure/runtime/api_fastapi/services/lite_app_lifecycle.py`

### Execution & State

- [Commands & workflows](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/workflow_engine.py): execution orchestration · Admits actions and creates asynchronous work. · `pocket-lab-final-structure/runtime/api_fastapi/services/workflow_engine.py`
- [NATS / JetStream](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py): durable event bus · `pocket-lab-final-structure/runtime/api_fastapi/services/nats_bus.py`
- **Async event contract**: AsyncAPI contract
- [Backend worker](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/workers/pocketlab_worker.py): worker runtime · Consumes commands and performs backend work. · `pocket-lab-final-structure/runtime/workers/pocketlab_worker.py`
- [SQLite system of record](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/db/connection.py): local database · Stores command, workflow, device, release, security, and projection state. · `pocket-lab-final-structure/runtime/api_fastapi/db/connection.py`
- [Read-model projections](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/projection_scheduler.py): projection pipeline · Builds API-optimized reads from event and workflow state. · `pocket-lab-final-structure/runtime/api_fastapi/services/projection_scheduler.py`
- [Backup & guarded recovery](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/api_fastapi/services/lite_restore_planner.py): recovery service · Plans restores and reconciles state after recovery. · `pocket-lab-final-structure/runtime/api_fastapi/services/lite_restore_planner.py`

### Host Runtime

- [Device supervisor](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/agents/pocketlab_agent_supervisor.py): agent supervisor · Supervises node agents, restarts, and recovery. · `pocket-lab-final-structure/runtime/agents/pocketlab_agent_supervisor.py`
- [Node agent](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/runtime/agents/pocketlab_node_agent.py): device executor · Executes device commands and emits heartbeats. · `pocket-lab-final-structure/runtime/agents/pocketlab_node_agent.py`
- **Termux local stack**: deployment topology · PM2, Caddy, SQLite, and NATS on Android/Termux or proot Ubuntu.
- [Production bootstrap](https://github.com/dexter-lab-ctrl/pocket-lab-lite/blob/main/pocket-lab-final-structure/pocket-lab-bootstrap-production-scripts-patched/scripts/bootstrap.sh): installer · Installs and configures the self-hosted runtime. · `pocket-lab-final-structure/pocket-lab-bootstrap-production-scripts-patched/scripts/bootstrap.sh`

### Contracts & Delivery

- **OpenAPI authority**: API contract
- **Architecture & generated docs**: architecture evidence · Source architecture drives contract and runtime documentation generation.
- **Release packaging**: release workflow · Packages runtime while excluding tooling, state, traces, and secrets.

## Connections

- 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
