first-commit

specs/current/architecture-boundaries.md

@@ -0,0 +1,115 @@
+# 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.