dotb_ai-platform/ARCHITECTURE.md

# Architecture

## Status and scope

This document records boundaries for the approved AI Platform rebuild and app-auth baseline `omni-ai-platform-app-auth` revision 2. The local implementation is covered by provider checks documented in `docs/contracts/app-auth-provider-handoff.md`; cross-service and production acceptance remain pending. The root Lead Scoring provider specification `docs/specs/ai-platform-lead-scoring.md` remains `review_ready` for that acceptance. The archived code and documents under `old_repo/` are historical evidence, not the new architecture or implementation.

AI Platform is a provider service: it executes bounded rule scoring and a selected AI profile, maintains scoring-run lifecycle, and exposes result retrieval. DotB-Omni owns customer-configured rules/weights, HITL and customer actions, snapshot construction, user authorization, and CRM writeback. Omni is notified of terminal outcome through an agreed signed HMAC webhook and then calls the authenticated GET endpoint for run details. DotB EMS remains the CRM system of record. There is no customer-facing settings or review UI in this service scope.

## Intended backend boundaries

The modular monolith has one runtime and one deployable backend. These boundaries apply to the implementation under `src/ai_platform/`.

- **Bootstrap/composition:** loads validated settings and composes framework, database, provider client, and application workflows. Resource lifetime is established here.
- **Platform:** app-key verification, Lead Scoring permission and app-scoped run access, shared persistence/runtime concerns, and operational interfaces. It does not own Omni customer configuration or user permissions.
- **Lead Scoring domain:** rule execution, scoring-run state/invariants, and profile semantics. Deterministic scoring rules should be pure functions; run identity and lifecycle belong in an entity/value model where useful.
- **Lead Scoring application:** admission, idempotency, execution coordination, result retrieval, and notification workflow. Use cases own transaction meaning; infrastructure supplies mechanisms. Its versioned AI profile selects AIHub or OpenAI-compatible for the service and contains model, prompts and timeout; OpenAI-compatible URL is also versioned, while API key stays in server settings. App-provided rules and weights arrive in each run body. Bootstrap constructs the AIHub adapter and an OpenAI-compatible adapter for the URL captured in the run's profile; raw V-Key is forwarded only for AIHub.
- **Infrastructure:** database mappings/repositories, separate AIHub and OpenAI-compatible HTTP adapters, HMAC signing, and delivery adapters. Provider details stop at these boundaries.
- **Presentation:** HTTP request/response mapping, app-auth dependency at the edge, health/readiness, and API error mapping. Transport schemas do not become domain objects by accident.

Dependency direction is inward: presentation and infrastructure may depend on application/domain contracts; domain does not depend on frameworks, persistence, network, environment, or application orchestration. Bootstrap is the composition root. Avoid generic base services, empty ports, service locators, and multiple deployment processes unless evidence requires them.

## Lifecycle and data invariants

1. Authenticate the Omni installation as a stable app and require its Lead Scoring permission before accessing a run.
2. Validate bounded request input and calculate a stable canonical-body fingerprint.
3. Scope client-supplied UUID idempotency to `(app_id, account_id, request_id)`. Same identity/same canonical body resolves to the existing run; same identity/different body conflicts. The service generates a distinct run UUID. Omni owns account/user authorization; the provider does not register accounts.
4. Commit admitted run before acknowledging acceptance. Execution holds raw V-Key only in current process memory; it is never persisted.
5. Rules-only requires no AIHub or V-Key; medium bounded two-pass is the default when AI is requested. Light/heavy are deferred until verified demand, not placeholders.
6. Persist terminal outcome independently from notification delivery. A server-configured per-app URL and signing secret route the signed webhook, which carries app/account/request/run identity. Missing callback configuration blocks new admission after replay lookup. Omni performs authenticated GET for the authoritative result. Key issuance/rotation stays in operator CLI; Admin Web lists status and revokes without receiving keys.
7. One-process recovery terminalizes work that cannot resume after interruption. It does not restore the lost V-Key or promise an automatic retry.
8. Delete/redact sensitive run material at 90 days under an approved policy; app offboarding and backup treatment need operational decisions.

Local provider tests cover these constraints within AI Platform. Consumer behavior, external AIHub protocol and production operations still require the acceptance checks in the spec.

## Transaction and effect boundaries

- Application use cases define atomic boundaries, including run transition and any durable notification intent where selected. Persistence adapters implement transactions.
- AIHub requests are network effects with explicit timeout and bounded policy once AIHub behavior has been verified. Never add speculative provider retries.
- HMAC delivery is an effect with bounded retry and observable terminal delivery state. Exact signing and replay rules are contract decisions with Omni.
- Clock, UUID generation, provider client, and persistence are explicit inputs at the application boundary when deterministic testing or lifecycle behavior requires them.
- Domain functions are deterministic and I/O-free. Stateful objects are justified by identity, invariant, or lifecycle rather than used as namespaces.

## Admin Web design system

Admin Web dùng SvelteKit 5, Tailwind CSS v4 semantic tokens, shadcn-svelte component source cho button/input/card/badge/table khi UI cần, Bits UI cho dialog/dropdown/popover hoặc tương tác phức tạp, và một icon family Lucide nếu cần icon. Chỉ thêm component đang dùng, không scaffold cả catalog. `src/lib/components/ui/` chỉ chứa primitives không biết domain; route giữ thành phần chỉ dùng tại route. HTML native là lựa chọn đúng cho form, label và bảng đơn giản khi không cần behavior phức tạp. Style tokens có một nguồn trong `apps/web/src/app.css`; UI phải kiểm tra focus, keyboard, validation, responsive và contrast. Browser chỉ gọi SvelteKit; backend auth/credentials và `BACKEND_INTERNAL_URL` thuộc `$lib/server/`. Không tạo frontend Clean Architecture giả lập.

## Verification structure (target)

- Unit: domain calculations, validation and transitions without network/database.
- Integration: persistence/migrations on the selected production database and AIHub HTTP adapter with controlled transport.
- Functional: HTTP request through application/persistence and back, including app isolation and account-scoped idempotency.
- Architecture: import direction, framework isolation, and composition-root rules.
- Contract: shared provider/Omni fixtures for requests, replay conflicts, result GET, HMAC delivery, acknowledgements, and errors.
- Operational: process interruption, recovery terminality, 90-day redaction, secret-leak sentinels, and deployment restore drills.

Actual test commands, directories, and enforcement must follow checked-in tooling once present; do not describe this target taxonomy as an existing test suite.

## Deferred decisions

Production hosting/orchestrator, network and TLS topology, secret manager and rotation ownership, database backup/restore and deletion guarantees, alerting/observability destination, load/SLO targets, exact contract publication/versioning, and AIHub protocol/model/timeouts remain deferred. Resolve them with accountable owners before the corresponding implementation or deployment. No production-readiness claim is warranted while these remain open.