Architecture
System components, data boundaries, work states, and release plans in diagrams.
These diagrams describe the implemented boundaries and the stated release targets. A target is not evidence that a component is deployed. Diagram source is stored beside this document and rendered by the documentation CI job.
Components
The native shell supervises a local Python service. The browser interface and MCP clients use the authenticated routes. Local task state stays on the worker. The account service uses Auth0. The existing relay forwards requests in memory.
Sign-in
The hosted callback exchanges the code with Auth0 and validates the ID token against issuer keys before creating the existing Brainlyy application session. The profile subject must match the token subject. The native Account menu uses the system browser with a separate public client's code/PKCE flow, exact loopback callback and verified ID/userinfo subjects. The plane separately validates the API access token and issues a hashed, revocable account session that authorizes metadata only. That credential cannot authorize web, gateway, relay or remote Work routes. The desktop release supplies its public service origin; explicit self-host settings and saved-token origin binding are preserved. See Authentication for operator registration requirements and local fixture evidence. Live native Auth0 and packaged browser/menu qualification remains a release requirement. The diagram below distinguishes the existing hosted browser path from the native account flow.
Pairing and remote access
The worker dials outward and the relay checks account-to-machine access. The local Work API continues to refuse relay requests. A separate typed channel supports remote source reports under a folder grant approved on the computer. Pairing alone does not enable this authority. The worker saves accepted tasks in its own database; browser sessions are rechecked before forwarding commands and delivering responses.
Data boundaries
Source files, local evidence and saved reports remain on the owning computer by default. Existing relayed content may be processed in plaintext by the gateway. This is not end-to-end encryption. Hosted operational metadata and opt-in cloud inference must not be described as local-only storage.
Existing local model tools inspect the selected model before sending a prompt. Known cloud routing and missing local metadata cause refusal. This is a check against a trusted runner's report, not a sandbox around that runner. Source reports still use quoted text and do not call a model. See model request limits for the exact supported boundary.
Durable work
Only one lease can complete a claimed task. Cancellation or a replacement lease fences out the old worker. Recovery currently applies to read-only source report generation. Future external effects require separate reconciliation rules.
Maintained results
A source digest change makes dependent results stale. The repair is a separate proposal. Exact approval and a fresh source check precede atomic replacement.
Managed graph
The managed work view reads stored relationships between source versions, saved checks, runs, reports, revisions and proposals. It has the same local access boundary as Work. Source observations and a database snapshot are not an atomic filesystem snapshot. Removed access hides protected metadata before delivery. Bounds and omitted records remain visible in the interface.
The graph opens existing result and proposal reviews. It cannot approve a change from cached graph metadata. Code-index relationships remain a separate view until a run explicitly records a dependency. See managed graphs for the full requirements and limits.
Source-linked briefs
The local worker captures approved excerpts, uses the selected local model and checks each quotation with a separate deterministic checker. Durable task stages retain the model identity and checkpoints. Current access and the worker lease are checked before publication. Findings link to their saved source versions in the Work network. A matching quote does not prove a conclusion true.
See source-linked briefs for consent, recovery and exact limits.
Release and recovery target
The final release requires signed installers and updates, verified migrations, backups and rollback. The diagram below is a release target. It is not the current update implementation.
Maintenance rules
Change the diagram source and its explanation in the same change as the related behaviour. Keep the API table in maintained work aligned with the routes. The renderer must succeed before documentation is published. Do not edit generated SVG files by hand.