ARCHITECTURE_PRINCIPLES.md

Architecture Principles

The principles below document approved Phase 0A direction. They do not implement the architecture.

AP-001 - Domain concepts remain explicit

Workspace, Run, Job, and Attempt have separate responsibilities, identifiers, states, and history.

AP-002 - Isolation is a boundary, not a UI convention

Workspace isolation must be enforced by scoped services, repositories, storage ownership, constraints, files, and tests. A tab or selected screen does not establish isolation.

AP-003 - Editable configuration and execution are separate

Workspaces remain editable; Runs execute immutable snapshots. Historical runs are not rewritten by later edits.

AP-004 - Persistence is authoritative

Durable job state resides in persistent storage. In-memory queues, thread state, and UI state are projections or execution aids.

AP-005 - Global coordination serves isolated workspaces

Each workspace has logical work and policy boundaries, while global execution capacity, physical account health, quotas, and provider limits are coordinated centrally.

AP-006 - Physical workers do not belong to UI tabs

A bounded global engine and provider-specific executors serve multiple workspace-scoped logical queues. UI views do not own thread pools.

AP-007 - Provider variability is explicit

Providers declare capabilities and limitations. Core logic must not assume uniform support for drafts, multiple recipients, scheduling, idempotency, status lookup, or error semantics.

AP-008 - Unknown is a valid safety state

When an external result cannot be proven, the system records an unknown/needs-review state and reconciles before retry.

AP-009 - Safety limits are layered

Throughput control may apply globally, by provider, physical account, endpoint, operation, workspace, and run. User choices cannot disable provider or safety limits.

AP-010 - Secrets remain outside ordinary application data

Databases store credential references and non-secret metadata. Secure secret material belongs to an approved operating-system credential vault.

AP-011 - UI follows user goals

The standard experience is organized around choosing a service, connecting accounts, adding customers, preparing invoices, reviewing, testing, and sending or scheduling.

AP-012 - Progressive disclosure preserves one product

Advanced controls are revealed in context rather than implemented as a separate incompatible application mode. Diagnostics remain separate.

AP-013 - Events cross thread and layer boundaries

Workers publish structured application events; the UI consumes them on the UI thread. Direct worker-to-widget calls are prohibited.

AP-014 - External operations are auditable and idempotent

Provider calls carry stable operation context, persist attempts, classify errors, and support reconciliation where possible.

AP-015 - Hybrid data architecture is the approved direction

The target direction is a global control.db plus one isolated database per workspace, with explicit reservation and reconciliation rather than assumed cross-database atomicity.

AP-016 - Architecture is governed and executable

Critical boundaries must become architecture fitness tests. New decisions use ADRs; changes to approved baseline use ACRs.

AP-017 - Dependencies remain behind boundaries

Third-party libraries must not become domain architecture. They are selected for approved needs and confined to adapters or infrastructure layers.

AP-018 - Recovery is designed before throughput optimization

Correct durable state, idempotency, shutdown, and reconciliation take priority over maximum send speed.