58 lines
2.5 KiB
Markdown
58 lines
2.5 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.
|
|
|
|
## 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.
|