60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# 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.
|
||
|
||
> Resource set is archetype‑specific. Endpoints below are a **pipeline/classification example** — adapt for chat‑first, generation, or automation products.
|
||
|
||
## 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.
|