Architecture Overview

Understanding the Otesse platform architecture helps you build better integrations. Here is how the system is structured.

Platform Architecture

                    ┌─────────────────┐
                    │  Customer Portal │
                    │  (Next.js)       │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   API Gateway    │
                    │  (REST + Auth)   │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
    ┌─────────▼──────┐ ┌────▼─────┐ ┌─────▼──────────┐
    │ Booking Service │ │ CRM      │ │ Payment Service│
    │                 │ │ Service  │ │ (Stripe)       │
    └─────────┬──────┘ └────┬─────┘ └─────┬──────────┘
              │              │              │
              └──────────────┼──────────────┘
                             │
                    ┌────────▼────────┐
                    │    Database      │
                    │    (Convex)      │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   Real-time      │
                    │   (PartyKit)     │
                    └─────────────────┘

Core Components

API Layer

REST API — Standard CRUD operations for all resources
JSON format — All request and response bodies use JSON
Versioned — API versions in the URL path (/v1/)
Pagination — All list endpoints support cursor-based pagination

Database (Convex)

Real-time — Data changes are pushed to connected clients instantly
ACID transactions — All mutations are transactional
Indexed queries — Optimized for common access patterns
Schema-enforced — All data is validated against the schema at write time

Real-time (PartyKit)

WebSocket connections — Persistent connections for live updates
Room-based — Each entity type has its own broadcast room
Low latency — Updates propagate in under 100ms

Payments (Stripe)

PCI compliant — Card data never touches our servers
Tokenized — Payment methods stored as Stripe tokens
Webhooks — Stripe events are processed and re-emitted as Otesse events

Data Model

The core entities and their relationships:

Customer ─┬─ Address (1:N)
          ├─ Booking (1:N)
          ├─ Invoice (1:N)
          ├─ Subscription (1:N)
          └─ PaymentMethod (1:N)

Booking ──┬─ Customer (N:1)
          ├─ Zone (N:1)
          ├─ Industry (N:1)
          ├─ CartItems (1:N)
          ├─ Invoice (1:1)
          └─ StaffAssignment (1:N)

Zone ─────┬─ PostalCode (1:N)
          ├─ Boundary (1:N)
          └─ PricingRule (1:N)

Industry ─┬─ Category (1:N)
          ├─ Product (1:N via Category)
          └─ Extra (1:N)

API Design Principles

Resource-oriented — URLs represent resources, not actions
Consistent — All endpoints follow the same patterns (list, get, create, update, delete)
Idempotent — Safe to retry failed requests without side effects
Filterable — List endpoints accept query parameters for filtering and sorting
Expandable — Related resources can be included via ?expand=customer,invoice

Rate Limiting

All API requests are rate-limited per API key:

Standard: 100 req/min
Professional: 500 req/min
Enterprise: 2,000 req/min

See Rate Limiting for details.

Security

TLS 1.2+ — All communication is encrypted in transit
API key rotation — Keys can be rotated without downtime
Webhook signatures — HMAC-SHA256 verification for all webhook deliveries
Scope-based permissions — API keys are restricted to specific resource types