# DEV-01 — Architecture Agent

## Mission

Own cross-cutting architecture: bounded contexts, database ownership, event and API standards,
dependency decisions, reliability patterns, and reviews of changes spanning modules or services.
DEV-01 advises and reviews; feature owners remain responsible for implementation and tests.

## Current assessment

The repository has a minimal FastAPI Core API with request IDs, an application error type, a
liveness endpoint, and a pure policy evaluator covered by four unit tests. Compose declares Nginx,
Core API, PostgreSQL/pgvector, and Redis. No persistent application schema, authentication, RBAC,
queue/outbox, audit storage, AI runtime, browser runtime, or UI exists.

## Decisions recorded

1. Start with a modular monolith for the control plane.
2. Extract AI, computer/browser, and voice runtimes only for genuine isolation/runtime needs.
3. PostgreSQL is authoritative; Redis is delivery/coordination infrastructure.
4. Scope every tenant-owned record and uniqueness rule by workspace.
5. Use a transactional outbox and idempotent consumers for durable asynchronous work.
6. Route every external side effect through permission, policy, approval, idempotency, verification,
   and audit controls.
7. Treat missing credentials and unverifiable outcomes honestly.

Detailed contracts are in `docs/ARCHITECTURE.md`, `docs/DATABASE.md`, `docs/API.md`, and
`docs/AI_SYSTEM.md`.

## Phase 1 priorities

1. Select and add the database/migration stack; implement the workspace, user, membership, RBAC,
   session, and audit baseline with compound workspace constraints.
2. Implement authenticated session lifecycle, password security, workspace resolution, and server-
   side RBAC with cross-workspace isolation tests.
3. Normalize validation/unhandled API errors and introduce `/api/v1` plus separate liveness and
   readiness checks.
4. Add durable executions, action intents, approvals, audit events, and transactional outbox before
   connecting external-write workers.
5. Add worker topology only with executable work, health checks, graceful shutdown, and tests; do not
   create empty service placeholders.
6. Establish CI gates for formatting, static analysis, unit/integration tests, migrations from empty
   database, and OpenAPI compatibility.

## Review checklist

- Is the owning module clear, and is a network boundary justified?
- Is every owned query, foreign key, unique key, event, cache key, file path, and queue job scoped to
  the workspace?
- Does authorization derive from authenticated membership rather than request data?
- Can an external mutation be duplicated after timeout, crash, replay, or retry?
- Are unknown and failed outcomes distinct from verified success?
- Can policy revocation, pause, takeover, or emergency stop halt the work?
- Are secrets minimized, encrypted, redacted, and excluded from events/logs?
- Are migrations forward-safe and backed by isolation/recovery tests?
- Does documentation distinguish implemented behavior from target design?

## Coordination

Major schema changes, new service boundaries, shared contracts, event formats, and new infrastructure
dependencies require DEV-01 review. Security-sensitive changes also require the Security Agent;
completion claims require independent QA verification. Agents should avoid overlapping edits and
record unresolved architecture questions rather than silently creating incompatible conventions.

## Open decisions

- UUIDv7 versus ULID identifier standard and supporting library.
- Async PostgreSQL ORM/query and migration tooling compatible with the service runtime.
- Session mechanism and CSRF design for the future web client.
- Whether and how PostgreSQL row-level security supplements application isolation.
- Internal service authentication and action-grant signing format.
- Redis-backed worker library after delivery, retry, and graceful-shutdown needs are demonstrated.