mirror of
https://github.com/priyanshujain/sanderling.git
synced 2026-10-02 19:17:10 +00:00
pj
e62319e916
* chore(prose): remove em-dashes from config files * chore(prose): remove em-dashes from android sdk config * docs(spec-api): remove em-dash from README * fix(doctor): reword sidecar-jar error without em-dash * test(sidecar): reword assertion message without em-dash * docs: add CLAUDE.md with project conventions * build: add docs target for pandoc site * docs(site): add pandoc template and stylesheet * docs(site): add pandoc build script * docs(site): add landing pages * docs(manual): add getting-started * docs(manual): add writing-specs * docs(manual): add runs * docs(manual): add cli reference * docs(dev): add design principles * docs(dev): add architecture * ci: deploy docs site to github pages * docs: rewrite README as entry point to docs site
70 lines
2.7 KiB
Markdown
70 lines
2.7 KiB
Markdown
---
|
|
title: Architecture
|
|
---
|
|
|
|
# Architecture
|
|
|
|
Three processes, two transports.
|
|
|
|
```mermaid
|
|
flowchart TB
|
|
subgraph Go["uatu (Go)"]
|
|
Bundler[Bundler<br/>esbuild] --> Verifier[Verifier<br/>goja + LTL]
|
|
Verifier <--> Runner[Runner]
|
|
Runner --> Trace[Trace writer<br/>JSONL + PNG]
|
|
Runner <--> Driver[Driver iface]
|
|
end
|
|
|
|
subgraph Sidecar["Maestro Sidecar (JVM)"]
|
|
Maestro[maestro-client]
|
|
end
|
|
|
|
subgraph Device["Emulator"]
|
|
subgraph App["Android app (debug)"]
|
|
SDK[uatu-sdk<br/>pause / hierarchy<br/>logs / coverage]
|
|
end
|
|
end
|
|
|
|
Driver -- gRPC --> Maestro
|
|
Maestro -- UIAutomator --> App
|
|
Runner -- Unix socket --> SDK
|
|
Trace --> Runs[(runs/)]
|
|
```
|
|
|
|
## Processes
|
|
|
|
**uatu (Go).** The top-level binary. Bundles the spec with esbuild, evaluates it in goja, runs the main loop, dispatches actions through the driver, writes the trace.
|
|
|
|
**Maestro sidecar (JVM).** A Kotlin process that wraps `maestro-client` and exposes a gRPC surface matching the `driver.Driver` interface. Handles UI input, screenshots, the system accessibility tree, and OS-level alerts.
|
|
|
|
**In-app SDK.** A Kotlin (or Swift for iOS) library linked into the app under test. Exposes a Unix socket to the runner. Provides pause and resume, view-hierarchy dumps, coverage reads, log capture, and user-registered state extractors.
|
|
|
|
## Transports
|
|
|
|
| Channel | Transport | Purpose |
|
|
|---|---|---|
|
|
| Go to Maestro sidecar | gRPC (localhost TCP) | UI input, screenshots, system alerts |
|
|
| Go to in-app SDK | Unix domain socket | Pause / resume, hierarchy, coverage, logs, extractors |
|
|
|
|
The split exists for one reason: only real UI events need the cost of crossing process and OS-API boundaries. Introspection is cheap, frequent, and lives on a fast local socket directly to the app.
|
|
|
|
## Per-step cycle
|
|
|
|
The heart of the system is:
|
|
|
|
```
|
|
pause ─► capture state ─► evaluate properties ─► pick action ─► resume ─► dispatch
|
|
```
|
|
|
|
1. The runner asks the driver to wait until the UI is idle.
|
|
2. The runner sends `PAUSE` to the SDK over the agent socket. The SDK freezes the main runloop at a safe point.
|
|
3. The SDK sends back a `STATE` message: view hierarchy, coverage delta, logs since last step, exception list, snapshot values.
|
|
4. The runner feeds state into goja. Extractors re-read; properties re-evaluate; the action generator returns a weighted tree.
|
|
5. The runner writes the trace entry for this step.
|
|
6. The runner picks an action by weight.
|
|
7. The runner sends `RESUME` to the SDK, then dispatches the action through the driver (gRPC to sidecar, which talks to Maestro, which talks to UIAutomator or XCTest).
|
|
8. Loop.
|
|
|
|
The cycle runs hundreds of times per minute. Every step produces one row in `trace.jsonl` and one screenshot.
|
|
|