create AI_template

docs/backend/api-design.md

@@ -0,0 +1,57 @@
+# Backend: API Design
+
+---
+**Last Updated:** 2025-01-17  
+**Phase:** Phase 0 (Planning)  
+**Status:** Draft — finalize in Phase 1  
+**Owner:** Backend Architect  
+**References:**
+- `/docs/backend/architecture.md`
+- `/docs/backend/payment-flow.md`
+- `/docs/backend/security.md`
+---
+
+## 1. Principles
+- REST with versioning (`/api/v1`), consistent envelope and errors.
+- Tenant-scoped resources; role-based authorization.
+- Idempotent ingestion/webhook endpoints; trace IDs for debugging.
+
+## 2. Core Resources (high-level)
+- `/auth` — login, tenant context, token refresh.
+- `/tenants` — tenant profile, roles, invites.
+- `/integrations` — connect sources (OAuth2/webhooks), view health, rotate secrets, webhook endpoints.
+- `/records` — list/filter, detail (raw + normalized + reasoning), bulk actions, reprocess.
+- `/rules` — CRUD, enable/disable, test/preview, stats.
+- `/processing` — trigger re-evaluation (rules → embeddings → LLM), inspect outcomes.
+- `/approvals` — approval queue, approve/override, optional rule creation.
+- `/reports` — dashboards/summary generation, export status/download.
+- `/billing` — session/portal links, subscription status (webhook-driven).
+- `/events` — read-only event log feed for downstream agents.
+- `/files/attachments` — uploads/metadata (if exposed).
+
+## 3. Payments/Billing (Provider-agnostic)
+- `POST /billing/session` — create checkout session for subscription/plan change.
+- `GET /billing/status` — current subscription status (webhook-driven source of truth).
+- `GET /billing/portal` — customer portal link for payment method/plan management.
+- `POST /billing/webhooks/provider` — verify signature; idempotent subscription updates; log billing events.
+
+## 4. Ingestion/Webhooks
+- Receivers for external providers (e.g., `/integrations/webhooks/{provider}`): verify signature, dedupe, enqueue to BullMQ; emit `INGESTED` with `source_agent`.
+
+## 5. Processing & Approvals
+- `POST /processing/run` — trigger re-evaluation for a scoped set (source/date/status).
+- `POST /approvals/{id}/approve` — accept decision; log `APPROVED`.
+- `POST /approvals/{id}/override` — override outcome; optional rule payload; log `APPROVED` and `RULE_CREATED` when applicable.
+
+## 6. Events
+- `GET /events` — read-only feed (paginated) for downstream agents/clients; filters: tenant, type, time range, source_agent.
+
+## 7. Response Envelope (example)
+```json
+{
+  "data": { ... },
+  "error": null,
+  "meta": { "traceId": "..." }
+}
+```
+Errors: `data = null`, `error` with code/message/context.