Repository structure

Inbox Agent is a TypeScript modular monolith. Package boundaries are enforced by scripts/check-package-boundaries.mjs and tests/architecture/package-boundaries.test.ts.

Layout

apps/web                 Next.js UI host. Renders docs markdown. No core business rules. Must not import providers.
apps/workers             Worker hosts. Compose application services.
packages/domain          Canonical model. No provider, DB, or AI SDK imports.
packages/application     Use-case orchestration.
packages/api-contracts   Stable DTOs.
packages/providers       Provider adapters. SDK objects stop here.
packages/security        Policy, sanitization, signed app sessions, AES-256-GCM token helpers, and the secret-store interface.
packages/ai              Model-independent AI gateway and prompt sanitizer. Must not import providers.
packages/persistence     Repository implementations.
packages/jobs            Background job contracts.
packages/observability   Logging, metrics, and log redaction.
packages/config          Environment and feature flags.
packages/testing         Shared test helpers.
database/migrations      Reviewable schema changes. MAIL-72 runner applies these to `inbox_agent`.
fixtures/mail            Synthetic fixtures only.
fixtures/production-mail Empty of mail payloads. See POLICY.md.

Forbidden imports

A deliberate violation fixture lives at tests/architecture/fixtures/forbidden-imports. CI must fail when that tree is scanned without --expect-fail.