# Architecture Overview This page is a high-level map of the Sesori monorepo. For the Bridge's layered code architecture, see [bridge/ARCHITECTURE.md](../bridge/ARCHITECTURE.md). For the runtime data flow, see [HOW_IT_WORKS.md](HOW_IT_WORKS.md). ## Repository structure ``` sesori_apps_monorepo/ ├── bridge/ # Dart workspace — Bridge CLI + plugin system │ app/ # Bridge CLI and plugin-agnostic orchestration │ sesori_bridge_foundation/ # Bridge-wide runtime acquisition primitives │ sesori_plugin_interface/ # Abstract plugin contract │ sesori_plugin_runtime/ # Managed backend runtime supervision │ sesori_plugin_opencode/ # OpenCode backend plugin │ sesori_plugin_codex/ # Codex backend plugin │ sesori_plugin_acp/ # Agent Client Protocol backend plugin │ sesori_plugin_antigravity/ # Google Antigravity ACP backend plugin │ sesori_plugin_cursor/ # Cursor ACP backend plugin │ sesori_plugin_copilot/ # GitHub Copilot ACP backend plugin │ sesori_plugin_grok/ # Grok Build ACP backend plugin │ sesori_plugin_deepseek/ # DeepSeek ACP backend plugin │ sesori_plugin_omp/ # Oh My Pi ACP backend plugin │ sesori_plugin_claude/ # Claude Code backend plugin │ sesori_plugin_hermes/ # Hermes ACP backend plugin │ sesori_plugin_pi/ # Pi backend plugin ├── client/ # Flutter workspace — mobile + desktop shells │ app/ # Mobile Flutter UI shell │ desktop/ # Desktop Flutter product shell │ module_app_ui/ # Flutter UI shared by the mobile and desktop shells │ module_core/ # Pure Dart business logic │ module_desktop_core/ # Pure Dart desktop supervision and state │ module_auth/ # Auth & token lifecycle │ module_persistence/ # Shared local persistence store │ module_prego/ # Prego design system — theme, fonts, icons, UI components │ design_catalog/ # Interactive catalog of design-system components ├── shared/ │ sesori_shared/ # Shared crypto & protocol types │ no_slop_linter/ # Custom Dart lint rules (dev tooling) └── docs/ # Deep-dive guides ``` `bridge/` and `client/` are independent Dart pub workspaces with separate dependency resolution. `sesori_shared` is referenced via path by both and carries the crypto and protocol types. `no_slop_linter` is a custom analyzer plugin that the `analysis_options.yaml` files load by path; no package depends on it. ## Dependency graph ```mermaid graph TD bridge_app[bridge/app] --> sesori_plugin_interface[bridge/sesori_plugin_interface] bridge_app --> sesori_bridge_foundation[bridge/sesori_bridge_foundation] bridge_app --> sesori_plugin_opencode[bridge/sesori_plugin_opencode] bridge_app --> sesori_plugin_codex[bridge/sesori_plugin_codex] bridge_app --> sesori_plugin_acp[bridge/sesori_plugin_acp] bridge_app --> sesori_plugin_antigravity[bridge/sesori_plugin_antigravity] bridge_app --> sesori_plugin_cursor[bridge/sesori_plugin_cursor] bridge_app --> sesori_plugin_copilot[bridge/sesori_plugin_copilot] bridge_app --> sesori_plugin_grok[bridge/sesori_plugin_grok] bridge_app --> sesori_plugin_deepseek[bridge/sesori_plugin_deepseek] bridge_app --> sesori_plugin_omp[bridge/sesori_plugin_omp] bridge_app --> sesori_plugin_claude[bridge/sesori_plugin_claude] bridge_app --> sesori_plugin_hermes[bridge/sesori_plugin_hermes] bridge_app --> sesori_plugin_pi[bridge/sesori_plugin_pi] bridge_app --> sesori_shared[shared/sesori_shared] sesori_bridge_foundation --> sesori_plugin_interface sesori_plugin_runtime[bridge/sesori_plugin_runtime] --> sesori_plugin_interface sesori_plugin_runtime --> sesori_bridge_foundation sesori_plugin_opencode --> sesori_plugin_interface sesori_plugin_opencode --> sesori_bridge_foundation sesori_plugin_opencode --> sesori_plugin_runtime sesori_plugin_opencode --> sesori_shared sesori_plugin_codex --> sesori_plugin_interface sesori_plugin_codex --> sesori_bridge_foundation sesori_plugin_codex --> sesori_plugin_runtime sesori_plugin_codex --> sesori_shared sesori_plugin_acp --> sesori_plugin_interface sesori_plugin_acp --> sesori_bridge_foundation sesori_plugin_acp --> sesori_shared sesori_plugin_antigravity --> sesori_plugin_interface sesori_plugin_antigravity --> sesori_bridge_foundation sesori_plugin_antigravity --> sesori_plugin_acp sesori_plugin_antigravity --> sesori_plugin_runtime sesori_plugin_antigravity --> sesori_shared sesori_plugin_cursor --> sesori_plugin_interface sesori_plugin_cursor --> sesori_bridge_foundation sesori_plugin_cursor --> sesori_plugin_acp sesori_plugin_cursor --> sesori_plugin_runtime sesori_plugin_cursor --> sesori_shared sesori_plugin_copilot --> sesori_plugin_interface sesori_plugin_copilot --> sesori_bridge_foundation sesori_plugin_copilot --> sesori_plugin_acp sesori_plugin_copilot --> sesori_plugin_runtime sesori_plugin_grok --> sesori_plugin_interface sesori_plugin_grok --> sesori_bridge_foundation sesori_plugin_grok --> sesori_plugin_acp sesori_plugin_deepseek --> sesori_plugin_interface sesori_plugin_deepseek --> sesori_bridge_foundation sesori_plugin_deepseek --> sesori_plugin_acp sesori_plugin_deepseek --> sesori_plugin_runtime sesori_plugin_omp --> sesori_plugin_interface sesori_plugin_omp --> sesori_bridge_foundation sesori_plugin_omp --> sesori_plugin_runtime sesori_plugin_omp --> sesori_plugin_acp sesori_plugin_claude --> sesori_plugin_interface sesori_plugin_claude --> sesori_bridge_foundation sesori_plugin_claude --> sesori_shared sesori_plugin_hermes --> sesori_plugin_interface sesori_plugin_hermes --> sesori_bridge_foundation sesori_plugin_hermes --> sesori_plugin_acp sesori_plugin_pi --> sesori_plugin_interface sesori_plugin_pi --> sesori_bridge_foundation sesori_plugin_pi --> sesori_plugin_runtime sesori_plugin_pi --> sesori_shared mobile_app[client/app] --> module_app_ui[client/module_app_ui] mobile_app --> module_core[client/module_core] mobile_app --> module_prego[client/module_prego] mobile_app --> module_auth[client/module_auth] mobile_app --> module_persistence[client/module_persistence] mobile_app --> sesori_shared desktop_app[client/desktop] --> module_app_ui desktop_app --> module_core desktop_app --> module_desktop_core[client/module_desktop_core] desktop_app --> module_prego desktop_app --> module_auth desktop_app --> module_persistence desktop_app --> sesori_shared module_app_ui --> module_core module_app_ui --> module_prego module_app_ui --> sesori_shared module_desktop_core --> module_core module_desktop_core --> sesori_shared module_core --> module_auth module_core --> module_persistence module_core --> sesori_shared module_auth --> module_persistence module_auth --> sesori_shared module_prego --> sesori_shared design_catalog[client/design_catalog] --> module_prego ``` `shared/no_slop_linter` is omitted — it is a dev-only analyzer plugin, not a runtime dependency. `client/`, `bridge/` and `shared/sesori_shared` enable it as an analyzer plugin by path in their `analysis_options.yaml`. ## Runtime data flow At runtime, the components form a simple pipeline: ```mermaid graph LR OC["AI Assistant
(localhost)"] -- "Plugin-owned local transport" --> B["Bridge CLI
(your machine)"] B -- "WSS · E2E encrypted" --> R["Relay Server
(cloud)"] R -- "WSS · E2E encrypted" --> M["Mobile App
(your phone)"] ``` See [HOW_IT_WORKS.md](HOW_IT_WORKS.md) for the full breakdown of each hop and the encryption handshake. ## Catalog ownership and the plugin boundary The bridge owns the durable catalog of projects, sessions, and their relationships. Plugins are execution harnesses and capability providers; they are not the normal source for project and session list reads. Normal list requests read only from the bridge-owned catalog and never enumerate enabled plugins, so read cost depends on the returned page rather than on plugin count or the health of the slowest backend. The catalog is authoritative for what Sesori knows and presents. A plugin remains authoritative for whether its backend can execute or resume an operation right now. Persisting a last-known session does not prove the backend can still open it; a temporarily unavailable plugin does not invalidate the durable entity. **Sesori owns** projects and sessions known to Sesori, project-to-session and parent-to-child relationships, plugin binding and backend-handle attribution, bridge-owned names and archive or deletion intent, worktree, base-branch and prompt-default metadata, unseen and activity state, and catalog provenance. **Plugins own** agent execution and backend runtime state, transport and process lifecycle, backend capabilities, models, agents, variants and commands, the actual current operability of a backend session, and transcript retrieval. ### Update semantics - Changes initiated through Sesori write through to the catalog immediately. A session created through Sesori appears at once; it never waits for a later backend enumeration. - Plugin events may update list metadata and lifecycle state for sessions already known to Sesori, but they must not discover unrelated external root sessions or projects. - Child sessions are the deliberate exception. An event may persist a child only when its parent or ancestor resolves to a known session from the same plugin; the child inherits that ancestry's project and plugin attribution. Nested children form a durable task hierarchy that root session lists exclude and that cascades when a parent is deleted through Sesori. An unresolved child may wait for its parent or use a targeted lookup under a known root; it must not trigger global plugin discovery. - Work created directly in a harness enters through an explicit per-plugin **import**, not a sync: `POST`, `DELETE` and `GET /plugin/import` start, cancel and report it, and progress is emitted as plugin-attributed SSE. Import is non-destructive, and absence from a later import means only that the entity was not observed — never that it was deleted. Real unavailability is learned when a targeted operation returns a typed not-found result, not from a transient transport failure. ### Identity A session separates its Sesori-owned id, the owning plugin id, and the opaque backend session handle, with uniqueness enforced per `(plugin_id, backend_session_id)`. Session controls resolve the durable binding and pass only the backend handle to the owning plugin. Released peers that omit plugin identity decode to OpenCode, because that was the only backend they could target; this legacy identity is distinct from the enabled order and must never mean "first enabled plugin". Projects remain one cross-plugin entity per directory with shared hide, name and base-branch metadata. The catalog is per-bridge and does not replace the separate multi-bridge addressing axis. ### Parallel runtime Every registered plugin is eligible unless its id appears in the `plugins.disabled` denylist in bridge settings. Eligible plugins are ordered by case-insensitive display name, tie-broken by id, and the current default for new clients is OpenCode when it is selectable and otherwise the first selectable plugin in that order. Plugin-specific CLI options are namespaced per plugin as `---`. The bridge starts, monitors, degrades and stops plugins independently, routes session controls through each stored binding, and preserves one shared project space across plugins. A plugin outage degrades execution for its bound sessions without removing their durable records. The client discovers the bridge-authored ordered plugin list, selects its default when routable, and scopes saved agent, model and variant choices by project and plugin. This direction deliberately makes direct harness usage a secondary workflow: external work appears after import, and imported metadata may be stale until another import or a live event updates it. ### Antigravity boundaries `sesori_plugin_antigravity` owns Google's runtime pair, release pin, isolated profile, personal OAuth validation, metadata recovery and provider normalization. Its descriptor composes the existing shared managed installer with an initialize-only candidate validator; it does not introduce another installer. Inspection is read-only, while installation owns disposable candidate state and validates before placement. Linux extractor preflight belongs to the explicit installation path, never inspection. Runtime/profile Storage → Repository → Service boundaries separate filesystem access, normalized outcomes and policy. Authentication uses the plugin's ACP and loopback clients through repositories/services; the shared lifecycle owns the attempt and neutral client challenge. Raw OAuth output is intercepted before NDJSON/logging. Actual runtime processes disable parent-environment inheritance; archive helpers retain the existing host command-execution policy. The connection-scoped interaction composer binds repositories/services to the real lazy/reconnected ACP client. Shared ACP code owns transport, pending interaction lifecycle and session residency; Google-specific fields are normalized inside the plugin before live/replay retention. Recovered `.meta` directory bindings remain fallbacks beneath bridge/live authority. Google history is never a second normal catalog database or a deletion target. Mobile and desktop share settings, login presentation and chooser widgets. They consume `Antigravity` metadata or the raw `antigravity`/plug fallback, not Google-specific branches or a new shared harness enum value. See the [operator guide](ANTIGRAVITY.md) and [capability matrix](HARNESS_CAPABILITIES.md) for supported behavior and the native/authenticated verification gaps. ## Design principles - **Multiple surfaces and multiple bridges are first-class.** The code is organized so that phone, desktop, and future web shells stay thin, while the shared business logic stays surface-neutral. - **Backend-specific behavior stays inside its plugin package.** Shared code and clients consume backend-neutral contracts and declared capabilities. - **Bridge capabilities remain usable headlessly.** The Bridge CLI is a pure Dart tool with no GUI dependency, which makes it suitable for remote machines, VMs, and automation. - **Local E2E and managed trusted modes are separate.** The same encryption path is used whether the app is on the same network or across the internet, and the relay never holds the keys. ## Workspace docs - [bridge/README.md](../bridge/README.md) — Bridge CLI, plugin system, codegen, and testing. - [bridge/ARCHITECTURE.md](../bridge/ARCHITECTURE.md) — Bridge layered architecture (Foundation → API → Repository → Service). - [client/README.md](../client/README.md) — Flutter client, module structure, and testing. - [shared/no_slop_linter/README.md](../shared/no_slop_linter/README.md) — custom lint rules and how they are wired in.