Zakaria
a46764fb1b
ci / Validate workspace (push) Has been cancelled
landing-page-ci / Validate landing page (push) Has been cancelled
landing-page-deploy / Deploy landing page (push) Has been cancelled
github-metrics / Generate repository metrics SVG (push) Has been cancelled
refresh-contributors-wall / Refresh contributors wall cache bust (push) Waiting to run
116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# Architecture Boundaries
|
|
|
|
## Purpose
|
|
|
|
This document defines the architectural boundaries for the local Open Design app. These boundaries are architectural constraints; some enforcement details can be implemented later through the relevant roadmap workstreams.
|
|
|
|
## Product Shape
|
|
|
|
Open Design is a local-first application. The near-term Electron version is a shell around the same `apps/web` and `apps/daemon` architecture.
|
|
|
|
Electron does not introduce a separate privileged application layer. The web layer and daemon keep the same responsibilities in browser and Electron modes.
|
|
|
|
## Web Boundary
|
|
|
|
`apps/web` owns UI, presentation state, and thin BFF/proxy behavior.
|
|
|
|
`apps/web` must not directly access local privileged capabilities:
|
|
|
|
- `.od` state
|
|
- SQLite storage
|
|
- workspace filesystem reads or writes
|
|
- agent CLI processes
|
|
- task process lifecycle
|
|
- local logs and artifacts
|
|
|
|
The web layer communicates with daemon-owned capabilities through API DTOs and streaming events.
|
|
|
|
## Daemon Boundary
|
|
|
|
`apps/daemon` is the sole local capability server. It owns privileged local runtime behavior:
|
|
|
|
- `.od` state
|
|
- SQLite storage, schema, migrations, and storage layout
|
|
- workspace filesystem access
|
|
- agent CLI invocation
|
|
- task lifecycle and process cleanup
|
|
- logs, artifacts, and diagnostic state
|
|
|
|
Daemon capabilities should be isolated behind internal modules such as `db`, `fs`, `agents`, `tasks`, `logs`, and `artifacts`.
|
|
|
|
## Shared Boundary
|
|
|
|
Shared code must be pure JavaScript or TypeScript that can run in both web and daemon contexts.
|
|
|
|
Shared code may contain:
|
|
|
|
- API DTO types
|
|
- runtime schemas such as Zod or TypeBox schemas
|
|
- domain constants
|
|
- task states
|
|
- SSE event names
|
|
- error codes
|
|
- pure helper functions
|
|
- path-related logical string helpers
|
|
|
|
Shared code must not depend on framework or environment-specific APIs such as Next.js, Express, Node filesystem/process APIs, browser-only APIs, SQLite, or daemon internals.
|
|
|
|
## API DTO Boundary
|
|
|
|
The web layer should understand API DTOs, not daemon implementation details.
|
|
|
|
API DTOs should prefer workspace-scoped logical or relative paths. Machine absolute paths should remain daemon-internal. Enforcement can be implemented later through a workspace path resolver and runtime validation layer.
|
|
|
|
SQLite schema names, table structure, migration details, and storage layout are daemon-private. The web layer sees API DTOs for display and interaction.
|
|
|
|
## Workspace Boundary
|
|
|
|
The current architecture can assume one active workspace. Workspace root selection should come from explicit user choice or an explicit startup parameter.
|
|
|
|
Daemon filesystem access should be scoped to the active workspace root. Path normalization and root containment checks should be implemented in the daemon path resolver and validation layer.
|
|
|
|
Precise implementation priority for workspace enforcement can be deferred, but the boundary direction is fixed: web does not construct privileged filesystem paths, and daemon owns path resolution.
|
|
|
|
## Agent Command Boundary
|
|
|
|
Users cannot provide free-form shell commands for daemon execution.
|
|
|
|
Agent invocations should use controlled command templates and argument construction. User-provided content may enter prompts, files, or configuration fields, while command structure remains daemon-controlled.
|
|
|
|
Plugin or custom-agent command extension is outside the current scope.
|
|
|
|
## Security Baseline
|
|
|
|
The app is local-first. Daemon should bind locally, and local API authentication can be deferred.
|
|
|
|
Daemon output should redact sensitive values by default, including tokens, API keys, environment secrets, and Authorization-like headers.
|
|
|
|
## Task Lifecycle Boundary
|
|
|
|
Daemon owns the full task lifecycle. The web layer may create, subscribe to, query, and request cancellation for tasks through API DTOs and events.
|
|
|
|
Tasks belong to a workspace and an agent. Terminal states are:
|
|
|
|
- `succeeded`
|
|
- `failed`
|
|
- `cancelled`
|
|
- `interrupted`
|
|
|
|
The web layer requests cancellation; daemon determines final task state and owns cleanup. Detailed concurrency, timeout, scheduling, and recovery policies can be defined in the process manager workstream.
|
|
|
|
## Deferred Policy Details
|
|
|
|
The following policy details can be finalized in later workstreams:
|
|
|
|
- multiple workspace support
|
|
- workspace registry location
|
|
- artifact, cache, and log directory layout
|
|
- Electron workspace picker behavior
|
|
- task concurrency limits
|
|
- timeout defaults
|
|
- queueing strategy
|
|
- restart recovery behavior
|
|
- process-tree cleanup strategy
|
|
|
|
These deferred choices should preserve the boundaries in this document.
|