Repository Public License
1<!--2ORIX OS Automation3File: docs/architecture/overview.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89## Layers1011```12┌──────────────────────────── ORIX OS Automation.app (SwiftUI + AppKit) ────────────────────────────┐13│ Dashboard · Agent Chat · Workflow Studio · Code Studio · Runs · Agents · Skills · Scheduler · │14│ Permissions · Settings · Onboarding · Menu-bar item · Command palette · Approval sheets │15└───────────────▲──────────────────────────────▲───────────────────────────────▲─────────────────────┘16 │ observes │ answers approvals │ edits17 ┌───────┴────────┐ ┌───────┴────────┐ ┌───────┴─────────┐18 │ ORIXPersistence│◀─ events ────│ AppServices │── documents ▶│ ORIXWorkflow │19 │ SQLite (WAL) │ │ (composition) │ │ Engine (IR) │20 └───────▲────────┘ └───┬───────┬────┘ └───────┬─────────┘21 │ │ │ │ tool + agent steps22 │ ┌─────────▼──┐ ┌─▼──────────────┐ │23 │ │ ORIXAgent │ │ ORIXScheduler │ │24 │ │ Runtime │ │ (queue, cron) │ │25 │ └─────┬──────┘ └───────┬────────┘ │26 │ model turns │ tool calls │ launches runs │27 ┌───────┴────────┐ ┌─────▼────────────────────────────────────────▼─────┐28 │ ORIXProvider │ │ ToolExecutor (ORIXToolRegistry) │29 │ Adapters │ │ schema → requirements → policy → approval → run → │30 │ (URLSession) │ │ redact → audit │31 └────────────────┘ └──┬──────────────┬─────────────────┬────────────────┘32 │ PolicyEngine │ Tools │ ProcessRunner33 │ (ORIXSecurity)│ files, shell, │ process groups,34 │ grants, tiers │ git, http, docs│ timeouts, Seatbelt35 │ AuditLog │ Apple, browser │36 └──────────────┴─────────────────┴────────────────37```3839## Separation that the code enforces4041| Concern | Lives in | Cannot do |42|---|---|---|43| Reasoning | `ORIXAgentRuntime` + provider adapters | Touch the machine. Its only door is `ToolInvoking`. |44| Permission | `ORIXSecurity.PolicyEngine` | Execute anything. It only answers allow / ask / deny. |45| Execution | `ORIXToolRegistry.ToolExecutor` + tools | Decide policy or approve itself. |46| Audit | `ORIXSecurity.AuditLog`, run events in the store | Be rewritten silently: the log is hash-chained. |47| UI | the app | Run a tool directly: it submits runs and answers approval requests. |4849`ORIXCore` holds the contracts between them (protocols and value types only), so each layer can be tested alone and50none can reach around another.5152## One model, three views5354A workflow is one `WorkflowDocument` (the IR). The code view edits its YAML/JSON text; the visual view applies edit55operations to the document; the agent view asks a model to produce or change the same document. Every view parses56or emits through `WorkflowCodec`, and `WorkflowValidator` judges the result. What a view cannot represent (comments57in YAML when the canvas rewrites the text) is reported before the rewrite.5859## Processes6061- **The app** owns the UI, answers approvals, and runs foreground work.62- **The background agent** is the same signed executable started by launchd with `--background-agent`63 (registered with `SMAppService`, opt-in). It runs the scheduler and headless workflows. It is the same binary on64 purpose: identical code signature means identical Keychain access without widening any access list, and no second65 executable to keep entitlement-minimal. It has no window and cannot answer approvals: anything not pre-granted66 parks as `WAITING_APPROVAL` and is surfaced by a notification and in the app.67- Both share one SQLite database (WAL). A lease row ensures a single active scheduler. Changes are announced with a68 Darwin notification so the other process refreshes.69- **Subprocesses** (scripts, git, python…) are children of whichever process runs the tool, each in its own process70 group, confined with a generated Seatbelt profile where applicable, killed as a group on timeout, cancel or71 emergency stop.7273## Data on disk7475`~/Library/Application Support/ORIX Automation/`: `orix.sqlite` (runs, events, workflows and versions, grants,76schedules, queue, agents, memory), `audit.jsonl` (hash-chained), `artifacts/<runID>/`, `skills/<id>/<version>/`,77`python-env/`. Provider keys and user secrets: login Keychain only (service `ai.spboucher.orix.automation`).7879## Decisions80811. **No third-party code.** YAML subset codec, SQLite wrapper, SSE parser, PDF rendering and the editor are written82 against system frameworks. Nothing to license, pin or audit beyond Apple's SDK.832. **SQLite, not SwiftData.** Two processes write the same store; explicit migrations, WAL, leases and84 corrupt-file quarantine need direct control.853. **Same-binary background agent** (see above) rather than a helper tool or an XPC service. There is no XPC surface86 to authenticate because there is no XPC: the processes cooperate through the database.874. **Seatbelt (`sandbox-exec`) for scripts.** Deprecated as a public tool but present and functional on macOS 27;88 it is the only supported way for a non-sandboxed parent to confine an arbitrary child. If Apple removes it,89 script tools must refuse to run unconfined unless the user explicitly accepts (tracked in the risk register).905. **OpenAI through Chat Completions.** One wire format shared with OpenRouter. The Responses API is future work.916. **Verification decides status.** A run is `SUCCEEDED` only from tool results and runtime-checked postconditions;92 the model's closing statement is stored as a claim.93