Backend API Architecture¶

This document defines the REST API standards and core endpoints for the Pebble Orchestrator. The backend is built on Django REST Framework (DRF), providing a robust, multi-tenant capable service layer.

Authentication & Security¶

JWT-Based Auth¶

All API requests require a Bearer token in the Authorization header.

Provider: SimpleJWT (Django)
Token Swap: LDAP/SSO session -> JWT.
Expiry: 1 Hour access, 24 Hour refresh.

RBAC (Role-Based Access Control)¶

Roles are enforced at the viewset level:

Sales Rep: Can only view/edit their own assigned Leads/Customers.
Ops Manager: Can view all boards and update sync statuses.
IT Admin: Full access to Masters and DevOps endpoints.

Core Endpoints¶

1. Ingestion Layer¶

Hand-off point for the Pebble Email Listener service.

POST /api/v1/ingestion/email/
Payload: Raw email metadata (Subject, From, Body, Attachments S3 Path).
Action: Generates a unique EmailCard ID and triggers classification.

2. AI Classification Engine¶

Requesting classification for a card or document.

POST /api/v1/classify/card/
Payload: { "card_id": "UUID", "context": "Optional forced stream" }
Response: { "stream": "CRM|ERP|Tender", "confidence": 0.98, "summary": "..." }

3. CRM Master API¶

The source of truth for Company data.

GET /api/v1/crm/companies/ (Filtered by tenant)
POST /api/v1/crm/companies/ (Create company)
GET /api/v1/crm/companies/{id}/tabs/{tab_name}/ (8-tab data access)

4. Integration Bus (Plane.so)¶

Bi-directional bridge for Kanban updates.

POST /api/v1/sync/plane/webhook/
Action: Receives state changes from Plane.so (e.g., column move).
Impact: Triggers business logic (e.g., creating Sale Order in ERP).

Request/Response Standards¶

Success Envelope¶

{
  "status": "success",
  "data": { ... },
  "meta": { "timestamp": "...", "version": "1.0.0" }
}

Error Envelope¶

{
  "status": "error",
  "error": {
    "code": "VAL_001",
    "message": "GSTIN Validation Failed",
    "details": { "gstin": "Invalid format" }
  }
}

← Back to Architecture