Skip to content
Luotsi Luotsi

Architecture

Luotsi is a host-first .NET CLI for Android automation. It drives real devices through adb, keeps device work behind typed host abstractions, and turns useful runs into structured output plus replayable artifacts.

Architecture diagrams

Section titled “Architecture diagrams”
Top-level Luotsi architecture showing command flow, JSON envelopes, JSONL sessions, adb device control, lab governance, scenarios, telemetry, artifacts, packaging, replay, and live view internals.
Top-level runtime architecture: one-shot commands, long-lived JSONL sessions, adb-backed device control, and artifact roots that remain useful after the device session ends.
Luotsi live view sequence diagram separating video packets, host-routed control input, JSONL event artifacts, read-only observer sessions, and replay metadata.
Live view sequence and data flow: adb bootstrap, helper capture, private H.264 packet stream, libav decode, SDL3 rendering, host-routed input, read-only sharing, and replayable session artifacts.

Runtime shape

Section titled “Runtime shape”
  1. The operator, agent, or CI job invokes Luotsi on the host machine.
  2. AppExecutionShell routes through the command family router and command dispatchers.
  3. One-shot commands return one final envelope; long-running inspect and view sessions stream JSONL-capable timelines.
  4. Lab/device selection, scenario execution, discovery, inspect, replay, artifact packaging, and view sessions share the same host/runtime boundaries.
  5. Artifact roots preserve the evidence needed to reopen failures without the original device.

Product boundaries

Section titled “Product boundaries”
  • Command runtime: parsing, help, envelopes, failure responses, and session output modes.
  • Lab-aware device selection: inventory, leases, queued claims, quarantines, health, and run --claim-device.
  • Android host runtime: adb-backed IDeviceHost actions for taps, text, lifecycle, screenshots, hierarchy, files, telemetry, and logs.
  • Scenario lifecycle: authoring, validation, planning, execution, reports, governance, and CI policy.
  • Authoring and exploration: inspect, discover, Journey intake, and replay-generated scenario drafts.
  • Artifacts and replay: run-summary packets, capsules, timelines, scrub views, graphs, clusters, packages, redaction, unpack, and intake.
  • Live view: helper bootstrap, localhost packet stream, libav decode, SDL3 rendering, sharing, recording, and diagnostics.

Why the design is conservative

Section titled “Why the design is conservative”

Luotsi keeps production behavior explicit:

  • adb remains the device transport instead of a hidden device server.
  • Device work flows through typed host abstractions used by commands, scenarios, telemetry, inspect, and view.
  • Generated scenarios stay review-oriented until validated and accepted.
  • Artifact capture is part of the product contract, not an optional debug setting.
  • Shared-lab runs should claim a concrete device before execution when provenance is available.

Read more

Section titled “Read more”