AI_template/docs/backend/overview.md

Backend: Overview

---

Last Updated: 2025-01-17
Phase: Phase 0 (Planning)
Status: Approved
Owner: Backend Architect
References:

• /docs/project-overview.md
• /docs/backend/architecture.md
• /docs/backend/payment-flow.md

---

1. Role of Backend

• Own business logic for ingestion, processing/classification (rules + embeddings + LLM fallback), approvals, reporting, billing, and audit.
• Integrate safely with external providers (OAuth2/webhooks, payment provider, LLM provider) and expose consistent APIs + events.
• Enforce security: tenant isolation, RBAC, webhook verification, event/audit logging.

2. Main Domain Areas

• Auth & Tenants: authentication/authorization, roles, tenant-scoped access.
• Integrations: external providers via OAuth2/webhooks; connection health.
• Records: normalized feeds, statuses (ingested, processed, needs_approval, approved, failed), reasoning_trace JSONB.
• Rules & Processing: rules engine, embeddings similarity, LLM fallback; logging with source_agent.
• Approvals: human-in-the-loop decisions, overrides, optional rule creation; audit trail.
• Reports & Exports: dashboards/summaries with export history.
• Billing: provider-hosted subscriptions, tenant-scoped access control, webhooks.
• Events: /api/events feed for downstream agents and internal observability.

3. Integrations

• External data providers: OAuth2 + webhooks; signatures/verification; idempotent writes via workers.
• Payment provider: subscriptions, checkout/portal; webhooks for lifecycle events.
• LLM provider: OpenAI API via single helper; configurable model.
• Queues: BullMQ (Redis) for ingestion/categorization/notifications.