# Architecture

How the gateway, services, frontend host, and shared libraries fit together


How the gateway, backend services, frontend host, and shared libraries fit together at runtime.

erxes is a single Nx/pnpm monorepo. On the backend, each service is an Express app that exposes an Apollo Federation subgraph; the gateway composes them into one supergraph behind a single public `/graphql` endpoint. On the frontend, one Module Federation host (`core-ui`) loads a remote per enabled plugin. MongoDB stores tenant data; Redis carries service discovery, session tokens, and every BullMQ queue.

## Key concepts

- **One public endpoint.** The gateway on port `4000` ([main.ts](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/gateway/src/main.ts)) is the only service clients call. It proxies `/graphql` to an Apollo Router it spawns on `127.0.0.1:50000`, forwards `/pl:<name>` to a plugin's own HTTP routes (webhooks, callbacks), and falls through to Core API for everything else.
- **Redis service discovery.** Every backend registers `erxes-service-<name>` (its address) and `erxesservice:config:<name>` (Mongo URL, `meta`, release version) through [service-discovery.ts](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/backend/erxes-api-shared/src/utils/service-discovery.ts). The gateway waits for `core` plus every name in `ENABLED_PLUGINS` before it composes the supergraph and starts listening.
- **Subdomain tenancy.** The gateway derives the tenant from the request hostname; each service builds per-tenant Mongoose models from that subdomain, so the same code serves every organization.
- **Module Federation frontend.** `core-ui` (port `3001`) loads `<name>_ui/config` for each enabled plugin and builds routes, navigation, settings, and widgets from the exported `IUIConfig`. In production the remote entries come from the `plugins.erxes.io` CDN, not from your containers (see [bootstrap.tsx](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/frontend/core-ui/src/bootstrap.tsx)).
- **Shared libraries with hard boundaries.** Backend code uses `erxes-api-shared` (`utils`, `core-types`, `core-modules` entrypoints); frontend code uses `erxes-ui` and `ui-modules`, always through public exports, never another service's source.
- **Background services are not subgraphs.** `logs` (`3301`) and `automations` (`3302`) are BullMQ workers the gateway never routes GraphQL to. Plugins reach them through `meta` registrations and named `<service>-<queue>` queues on Redis.

## Request flow

```text
Browser ── HTTPS ──> Nginx ── /gateway/ ──> Gateway :4000
                                            │  userMiddleware maps Bearer / app /
                                            │  portal / agent credentials into
                                            │  user, clientportal, cpuser headers
                                            ├─ /graphql ──> Apollo Router 127.0.0.1:50000
                                            │                 ├─> Core API :3300     (core subgraph)
                                            │                 └─> Plugin APIs :3303+ (subgraphs)
                                            ├─ /pl:<name> ──> plugin HTTP routes (webhooks)
                                            └─ / ──> Core API routes
                                                     (/initial-setup, /get-frontend-plugins, ...)

Every service registers in Redis:  erxes-service-<name>,  erxesservice:config:<name>
BullMQ queues on Redis ──> logs-service :3301,  automations-service :3302
core-ui :3001 host loads <name>_ui remotes via Module Federation
(production remote entries served from plugins.erxes.io)
```

## Guides

- [Backend & API Gateway](https://erxes.io/docs/architecture-backend-gateway): Core API, plugin APIs, and federated gateway composition
- [Frontend & Plugin Loading](https://erxes.io/docs/architecture-frontend): Core UI host and Module Federation remotes
- [Shared Libraries](https://erxes.io/docs/architecture-shared-libraries): Reuse erxes-api-shared, erxes-ui, and ui-modules
- [Background Services](https://erxes.io/docs/architecture-background-services): Automations and logs workers with BullMQ and Redis