Architecture Overview
Nexa is a modular SaaS platform built around a case — the unit of work that represents one airline disruption and the passengers it affected. Every other module exists to move a case from OPEN to CONFIRMED with full auditability and minimum operator intervention.
Runtime topology
- API surface serves the public REST endpoints over HTTPS, region by region.
- Background workers run every long or flaky operation off the request path. They scale independently per stage so a slow PSP can't congest allocation.
- Nexa Data Layer holds every aggregate: cases, passengers, policies, demand, allocation waves, reservations, notifications, audit. Customers only see it through the API and the operations console.
- Provider integrations are interface-typed. The orchestration layer sees
HotelProvider,BookingProvider,EmailProvider,PaymentProvider— never the concrete vendor. AI capabilities are Nexa Trained Models on Google, consumed through the same kind of internal contract.
Core modules
| Module | Responsibility |
|---|---|
| Cases | Case lifecycle, passenger groups, stay-plan calculation, re-accommodation |
| Policies | Versioned policy engine with per-tier constraints and AI synthesis |
| Demand | Room request intake, approvals (auto + manual), compliance tracking |
| Hotels | Multi-provider search, normalization, deduplication, caching |
| Allocation | Ranking, assignment, PNR integrity, tier separation, inventory tracking |
| Booking | Provider bookings, retries, fallbacks, voucher generation, manual review |
| Notifications | Localized email templates, idempotent delivery |
| Contracts | Direct hotel contracts with guaranteed rates and inventory |
| Agent | Nexa Trained Model on Google for exception triage (per-tenant toggle) |
| Audit | Immutable action log with before/after snapshots |
| Jobs | Background workers: allocation, booking, payment, notifications, agent |
| Auth | JWT with role-based guards (ADMIN, OPS_SUPERVISOR, AIRPORT_OPERATOR) |
| Idempotency | Duplicate prevention on case creation, bookings, notifications |
| Rooming | Per-tier room math given passenger mix |
| Airports | Catalog of airports with coordinates and metadata |
Case lifecycle
- OPEN — event received, passengers grouped, stay plan computed.
- ENRICHING — optional step for data enrichment (e.g. flight lookup, rooming math).
- ALLOCATING — demand approved, allocation worker searching and scoring hotels.
- BOOKING — reservation requests in flight with provider retries and fallbacks.
- CONFIRMED / PARTIAL — rooms booked; vouchers queued for delivery.
- MANUAL_REVIEW — everything automated failed; a manual-review item holds the context and the agent's recommendations.
- CLOSED — end-of-life after check-out or case abandonment.
Asynchronous workflow
Nexa isolates every expensive or flaky operation behind a managed background queue:
| Queue | Retries | Backoff | Purpose |
|---|---|---|---|
nexa-allocation | 3 | Exp 2s | Search, rank, assign |
nexa-booking | 5 | Exp 5s | Provider booking calls |
nexa-payment | 5 | Exp 3s | PSP tokenization when applicable |
nexa-notification | 5 | Exp 3s | Email send + tracking |
nexa-agent | 1 | — | Nexa exception agent triage |
Each job carries an idempotency key; a dead-letter policy creates a manual-review item when retries are exhausted.
Data boundaries
- Sensitive passenger data is stored as reference IDs; full documents (passport, DNI) live in the airline's system-of-record.
- Card data is never persisted — only PSP tokens and confirmation IDs.
- Audit is append-only and never mutated; every document carries an actor, reason, timestamp, and before/after snapshot.