API¶
The Trove API is the core backend service - a NestJS 11 application running on Fastify that exposes a REST interface consumed by the Admin Portal, Customer Frontend, and Worker Service.
Stack¶
| Layer | Technology |
|---|---|
| Framework | NestJS 11 |
| HTTP adapter | Fastify |
| API style | REST |
| Database | MySQL 8 via MikroORM |
| Authentication | Auth0 + JWT |
| Documentation | Swagger (OpenAPI) |
| Error monitoring | Sentry |
Running Locally¶
The API starts on port 3000 by default.
Swagger UI is available at:
Authentication¶
Authentication uses Auth0 with JWT tokens. The API validates tokens on each request and enforces role-based access using NestJS guards.
Five token types are in use across the platform:
| Token Type | Used By |
|---|---|
| Vendor | Brand users accessing the Admin Portal |
| Recipient | Gift recipients accessing the storefront |
| Admin | Internal platform administration |
| Shopify OAuth | Shopify integration flow |
| Xero OAuth | Xero integration flow |
Rate Limiting¶
The API enforces a rate limit of 30 requests per second per client to protect against abuse and ensure fair usage.
Domain Modules¶
The API is organised into NestJS modules by domain:
| Module | Responsibility |
|---|---|
| Users | User accounts, profiles, and authentication context |
| Vendors | Brand (vendor) accounts, settings, and onboarding |
| Storefronts | Per-vendor storefront configuration and customisation |
| Products | Product catalogue management and Shopify sync |
| Orders | Order creation, status management, and fulfilment |
| Carts | Cart sessions for the recipient gift selection flow |
| Payments | Stripe Connect payment processing and payout management |
Third-Party Integrations¶
Stripe Connect¶
Handles all payment processing. Vendors onboard via Stripe Connect so payouts flow directly to their accounts. The API manages:
- Stripe Connect account creation and onboarding links
- Payment intent creation and confirmation
- Webhook handling for payment events
Shopify¶
Vendors can connect a Shopify store via OAuth. The API manages:
- OAuth authorisation flow and token storage
- Product import from Shopify into the Trove catalogue
- Incoming Shopify webhooks (processed asynchronously via the Worker)
Xero¶
Used for invoice generation and accounting reconciliation. The API manages the Xero OAuth flow and passes invoice jobs to the Worker.
Auth0¶
All authentication is delegated to Auth0. The API validates Auth0-issued JWTs and maps them to internal user records.
Sentry¶
Runtime errors and performance issues are captured and reported to Sentry automatically via the NestJS Sentry integration.
Database¶
The API uses MikroORM to interact with a MySQL 8 database.
- Entity definitions and repositories live in
libs/api/data-access - Schema is managed via migrations in
database/migrations/ - Seeders for development data are in
database/seeders/
Migrations¶
# Apply pending migrations
pnpm nx run api:migration:up
# Create a new migration after entity changes
pnpm nx run api:migration:create
Background Jobs¶
The API does not process background work directly - it enqueues jobs to AWS SQS, which are then consumed by the Worker Service. This keeps the API responsive and separates concerns for long-running or retryable operations.
Jobs enqueued by the API include:
- Email sending
- Shopify webhook processing
- Product sync
- Invoice generation
- Slack notifications
- Order push to external systems
Swagger / API Documentation¶
Interactive API documentation is available via Swagger UI at /api/docs when the server is running. This is generated automatically from NestJS decorators and provides a full reference of all endpoints, request shapes, and response types.
File Storage¶
Files (product images, exports, etc.) are stored in AWS S3. The API generates pre-signed URLs for secure client-side uploads and downloads. Encryption at rest is handled via AWS KMS.