# Introduction

What erxes is, how the platform fits together, and where to start


erxes is a self-hosted, source-available Experience Operating System (XOS) that combines customer data, marketing, sales, operations, and support in one platform. It is developed as a single Nx-powered pnpm monorepo that you extend through plugins.

## Choose your starting point

- [Local Setup](https://erxes.io/docs/local-setup): Run the product from source with MongoDB and Redis.
- [Deployment](https://erxes.io/docs/self-hosting): Deploy erxes on your own infrastructure.
- [Create a Plugin](https://erxes.io/docs/create-plugin): Add a business capability with backend and frontend projects.
- [Messenger Widget](https://erxes.io/docs/erxes-messenger): Embed chat and forms on a website.
- [CMS + Next.js](https://erxes.io/docs/content-plug-cms-next-developers-introduction): Build a website backed by Content plugin data.
- [Contributing](https://erxes.io/docs/contribute): Propose a fix or improve the documentation.

## What can you do with erxes?

The core platform provides shared capabilities such as contacts, products, properties, segments, documents, automations, and permissions. Plugins add business-specific functionality. The Community Edition includes backend plugins for sales, operations, frontline customer service, content management, and POS (`posclient`); further plugins are part of the Enterprise Edition, licensed separately.

As a developer, you can:

- Extend the platform with backend services and frontend plugins.
- Integrate applications through GraphQL and published service interfaces.
- Build customer-facing experiences with the client portal, help center, and widgets.
- Self-host an installation and manage its infrastructure and data, subject to the repository's license terms.

## How the parts work together

The Core UI is the browser entry point. It loads plugin UI modules through Module Federation and sends GraphQL requests to the gateway. Plugin UIs extend navigation and feature screens while reusing the platform's public UI libraries.

On the backend, Core API and plugin APIs register their addresses and configuration in Redis. The gateway composes their GraphQL schemas for Apollo Router and exposes a federated `/graphql` endpoint. Service-to-service calls use tRPC procedures defined by the module that provides them. Backend model creation uses the request subdomain to select the tenant's data.

Redis also supports queues and subscriptions. Background services such as automations and logs need their own running processes when those features are used. An enabled plugin name selects projects or services for discovery; it does not provision production containers or external integrations.

Standalone apps such as widgets and the client portal have separate builds and deployment configuration. In production, Core API returns plugin asset URLs hosted at `plugins.erxes.io`, so not all browser assets come from your own host; see [Deployment](https://erxes.io/docs/self-hosting).

## Technology stack

The toolchain versions below are declared in the root manifest and lockfile.

| Area | Version |
| --- | --- |
| Package manager | pnpm `9.12.3` (required, `packageManager` field) |
| Build system | Nx `20.0.8` with caching and task orchestration |
| Runtime | Node.js 22 in CI |
| Language | TypeScript `5.7.3` |

### Backend

The gateway (port 4000) runs Apollo Router in front of Core API (port 3300) and one Express service per enabled plugin API.

```text
        API Gateway (port 4000)
     Apollo Router + service discovery
                  |
    ┌─────────────┼─────────────┐
    ▼             ▼             ▼
 Core API     Plugin APIs   Background
 (3300)       (3303+)       services (3301-3302)
    └─────────────┼─────────────┘
                  ▼
        MongoDB + Redis/BullMQ
```

- **Framework:** Express 4 with Apollo Server v4 and Apollo Federation (`@apollo/subgraph`)
- **Service calls:** tRPC v11 for type-safe service-to-service procedures
- **Database:** MongoDB via Mongoose `8.13.2`
- **Cache and queues:** Redis (`ioredis` 5) and BullMQ 5
- **Real-time:** GraphQL subscriptions over `graphql-redis-subscriptions`
- **Authentication:** JWT (`jsonwebtoken`) and WorkOS SSO

### Frontend

The Core UI host (port 3001) loads each enabled `*_ui` remote through Module Federation. Plugin remotes use development ports 3002-3011.

- **Framework:** React `18.3.1` with React Router v7
- **Bundler:** Rspack `1.0.5` with `@module-federation/enhanced` `0.6.6`
- **Styling:** Tailwind CSS v4 + PostCSS
- **UI:** `erxes-ui`, the Radix-based design system, and `ui-modules` for reusable business UI
- **State:** Jotai + Apollo Client; React Hook Form + Zod; `react-i18next`

### Standalone apps

Apps under `apps/` carry their own dependencies; the React 18 version above applies to the main frontend only.

| App | Stack | Dev port |
| --- | --- | --- |
| `client-portal-template` | Next.js `16.0.3`, React 19 | 3800 |
| `help-center` | Next.js `16.3.2`, React 19 | 3900 |
| `posclient-front` | Next.js 14, React 18, PWA | 7002 |
| `frontline-widgets` | Rspack bundle (chat, forms) | n/a |

## Repository structure

The main development areas; [Repository Structure](https://erxes.io/docs/repository-structure) has the full map with per-plugin ports.

```text
erxes/
├── backend/                  # Backend microservices
│   ├── gateway/             # API gateway + Apollo Router (4000)
│   ├── core-api/            # Core business logic (3300)
│   ├── erxes-api-shared/    # Shared library for all services
│   ├── plugins/             # Plugin APIs (*_api, ports 3303+)
│   ├── services/            # Background services (automations, logs)
│   └── saas-migrations/     # Standalone migration scripts
├── frontend/
│   ├── core-ui/             # Module Federation host (3001)
│   ├── libs/                # erxes-ui + ui-modules
│   └── plugins/             # Plugin remotes (*_ui, ports 3002-3011)
├── apps/                    # Standalone apps (portal, help center, POS, widgets)
├── scripts/                 # create-plugin, start-api-dev, start-ui-dev
└── cloudflare/mail-worker/  # Inbound email routing worker
```

## Source code and community

The product source is on GitHub. Read the repository's contribution guide before changing core or plugin code.

- [erxes](https://github.com/erxes/erxes): the product codebase
- [Contributing guide](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/CONTRIBUTING.md): how to contribute

Join the [erxes Discord](https://discord.gg/erxes) to ask development questions, discuss integrations, and share your work with the community.

## Licensing and deployment

erxes is source-available. The repository's [LICENSE.md](https://github.com/erxes/erxes/blob/f91e8c6f4714c910a32c6b6e14fe085f6435c89e/LICENSE.md) contains AGPLv3 provisions, references separate Enterprise Edition terms, and states that erxes may not be hosted as a SaaS product that competes with erxes Inc. Third-party components retain their respective licenses.

Self-hosting, modifying, and distributing erxes remain subject to those terms; source availability does not mean every plugin or commercial deployment is unrestricted.

For hosted offerings, Enterprise options, and pricing, see [erxes](https://erxes.io). When self-hosting, your team is responsible for deployment, upgrades, backups, and ongoing infrastructure maintenance.