> ## Documentation Index
> Fetch the complete documentation index at: https://system.muzemus.online/llms.txt
> Use this file to discover all available pages before exploring further.

# External services

> Third-party integrations and how MUZE connects to them

## Service map

```mermaid theme={null}
graph LR
    subgraph MUZE["MUZE Backend"]
        API["NestJS API"]
    end

    subgraph Storage["Cloudflare R2"]
        R2["S3-compatible object storage"]
    end

    subgraph Email["Email delivery"]
        Brevo["Brevo API (prod)"]
        Nodemailer["Nodemailer (dev)"]
    end

    API -->|"PUT/GET via @aws-sdk/client-s3"| R2
    API -->|"Production"| Brevo
    API -->|"Development fallback"| Nodemailer
```

pdf-lib (PDF generation) and adm-zip (archive creation) run in-process and are not external services.

## Hosted infrastructure

| Service              | Purpose          | Notes                                                                                       |
| -------------------- | ---------------- | ------------------------------------------------------------------------------------------- |
| **Neon PostgreSQL**  | Primary database | Serverless Postgres. Connection pooling via built-in PgBouncer; `directUrl` for migrations. |
| **Render**           | Backend hosting  | Node 20 runtime. Deploys are manual (`autoDeploy: false` in `render.yaml`).                 |
| **Firebase Hosting** | Frontend CDN     | Serves the React SPA; rewrites all routes to `index.html`.                                  |

## Cloudflare R2 (file storage)

Stores uploaded files: employee size profile CSVs, order documents, and bulk import files.

* Accessed through `@aws-sdk/client-s3` against R2's S3-compatible API
* Credentials in `R2_ACCOUNT_ID`, `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_BUCKET_NAME`
* No CDN or public access; all file access goes through the backend API
* No file size limits at the R2 level; the 20MB Express body limit is the practical ceiling
* No lifecycle policies; uploaded files persist indefinitely

## Brevo (email delivery)

Delivers transactional email: staff invitations, password resets, order notifications.

* The `EmailService` in `backend/src/notifications/email.service.ts` handles all sending
* Production uses Brevo's HTTPS REST API (`BREVO_API_KEY` + `BREVO_SENDER_EMAIL`); development falls back to nodemailer SMTP (e.g. Gmail)
* Brevo works on Render free because it uses HTTPS, not SMTP ports (25/465/587 are blocked on Render free)
* Requires authorizing Render's egress IP in Brevo's authorized-IP list
* Templates are defined in code; every attempt is recorded in the `EmailLog` table
* No email queue; emails are sent during the request cycle (failures logged, never blocking)
* No delivery-status webhooks and no unsubscribe mechanism (transactional email only)

## In-process libraries

| Library   | Purpose                                         | Limitations                                                                       |
| --------- | ----------------------------------------------- | --------------------------------------------------------------------------------- |
| `pdf-lib` | Sales Order PDFs, packing slips, report exports | CPU-bound and synchronous; no caching; large reports regenerate on every download |
| `adm-zip` | ZIP bundles for bulk report downloads           | Entire archive built in memory before sending                                     |

## What MUZE does not integrate with

| Category                            | Status                                                               |
| ----------------------------------- | -------------------------------------------------------------------- |
| ERP systems                         | No integration                                                       |
| SMS / WhatsApp                      | WhatsApp channel reserved in the notification schema; no gateway yet |
| Payment processing                  | Not applicable (entitlement-based)                                   |
| Identity provider / SSO             | No integration; local accounts only                                  |
| Warehouse management                | No integration                                                       |
| POS systems                         | No integration                                                       |
| Monitoring / APM                    | Logs via Render stdout only                                          |
| Error tracking (Sentry and similar) | No integration                                                       |