Architecture and data flow
Screph is a Windows-first PySide6 workbench. The canonical project is central: Capture supplies sources, Selector owns markup, CV produces reviewable results, and downstream components receive selected context.
Components
Local and online execution
The canonical project, Selector and local CV, voice and LLM paths stay on the user's computer. User content is transferred by a selected function: support sends a message and attachments, diagnostics sends an explicitly confirmed ZIP, server speech sends WAV audio and a cloud LLM receives allowed context. The Logging page offers a manifest for review; the startup crash prompt does not show it. Separately, a desktop with a stored token refreshes the profile every 30 seconds; an installed build may fetch update metadata and six embedded-help pages. Activating OpenAI/LiteLLM Speech settings checks a catalogue or sends a synthetic silent probe. Model catalogues/archives and URL streams contact their hosts but do not upload the canonical project. A SCREPH_TELEMETRY configuration flag exists, but the current runtime initializes no automatic telemetry exporter.
Local processes and loopback
A separate process separates lifecycle and failures, but does not create a sandbox by itself. Unless stated otherwise below, a child component runs as the current Windows user and can use that user's files, network and devices.
| Component | Boundary | What matters to the user |
|---|---|---|
| Screph Code / Pro Agent | Separate processes, JSON-RPC over stdin/stdout and session/context files | Same OS-user permissions; review and diff are workflow controls, not an OS sandbox |
| Support helper | screph-support-chat.v1 over stdin/stdout; the helper performs HTTPS | Secret-shaped environment variables are filtered, but the selected request's auth context is passed explicitly; no loopback port is opened |
| Monaco | 127.0.0.1, ephemeral port | The local static-asset server closes with the widget; it is not a cloud API |
| Codex bridge log | POST /codex-bridge-log on an ephemeral loopback port | An unauthenticated local endpoint accepts JSON up to 256 KiB and writes its fields to the Screph log |
| Automation Manager UI / workflow | The UI normally lives in the desktop process; the selected workflow runs as a Python child with stdout/EVT and a control file | The child inherits the environment and user permissions; Stop controls the direct child, not necessarily its entire process tree |
| OAuth callback | 127.0.0.1:8443/8765 | A legacy mechanism disabled by default; the current device flow does not open this listener |
| Temporal worker | multiprocessing pipe/shared memory | An internal/prototype transport; normal CV execution must not be described as an isolated worker |
Trust boundary
Automatic live-preview recalculation is not saved, and a candidate does not become canonical geometry or semantics without explicit review/apply. Manual Apply in the main CV panel may attach a visual result to an image series but does not accept the candidate as markup. Downstream boundaries differ: Automation Runtime requires a separate run action, while sending a request to the current Screph Code Builder grants agent-mode write access inside the selected workspace. This path has no universal per-file confirmation.
Mode readiness
- General, GUI Automation: end-to-end workflows are ready.
- Industrial, UAV: selectable foundation/domain workspaces; not a production control/export path.
- Ground Robotics: an internal deferred scaffold.
Detailed engineering documents
State reports, the capability matrix, technical architecture and decisions live with the source code and are updated against implementation evidence.
Open engineering documentation on GitHub →