Introduction
What is erxes?
Welcome to the erxes developer documentation!
erxes is a self-hosted, source-available Experience Operating System (XOS). It brings customer data, marketing, sales, operations, and support into a platform that developers can extend through plugins.
This overview was checked against the erxes/erxes repository at version 3.1.7 (03acdf712c). Dependency versions below describe that checkout; consult the package manifests and lockfile for the version you are working with.
Choose your starting point
| Goal | Guide |
|---|---|
| Run the product from source | Local Setup |
| Deploy on your infrastructure | Self-Hosting |
| Add a business capability | Create a Plugin |
| Embed chat or forms on a website | Messenger Installation |
| Build a website backed by CMS data | CMS + Next.js |
| Propose a fix or improve the docs | Contribute |
These guides describe the product monorepo, erxes/erxes. The documentation website is maintained separately in erxes/erxes-global-profile. Template repositories have their own setup and are identified separately in the Content guides.
Documentation categories
Choose a category according to the work you are doing:
- Getting Started: installation and orientation in the product repository.
- Architecture: the gateway, backend services, frontend host, and shared libraries.
- Self-Hosting & Operations: deployment, configuration, migrations, and maintenance.
- Core Platform: shared records, permissions, forms, automations, and data exchange.
- Plugin Development: building and integrating backend and frontend extensions.
- Plugins: individual business capabilities, including Content and Erxes Support Agent.
- Apps & Widgets: customer-facing applications and website embeds.
- API & Integrations: authentication and connections to other applications.
- Contributing: the development and documentation contribution workflow.
Content's template developer, designer, and CMS + Next.js guides are grouped under Plugins → Content. Messenger installation is under Apps & Widgets. Muted sidebar topics identify planned documentation; linked topics have published pages.
What can you do with erxes?
The core platform provides shared capabilities such as contacts, products, forms, segments, automations, and permissions. Plugins add business-specific functionality, including sales, operations, customer service, accounting, and content management.
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.
Source Code & Contribution
The product source and contributor guidance are available on GitHub. Read the repository's contribution guide and applicable AGENTS.md files before changing core or plugin code.
- erxes - erxes codebase
- erxes Contributing guide - to contribute
Community & Support
Join the erxes Discord to ask development questions, discuss integrations, and share your work with the community.
Project Overview
The repository combines backend microservices, a frontend host with plugin remotes, shared libraries, and standalone applications.
Key Characteristics
- Architecture: Nx-powered pnpm monorepo with microservices architecture
- License: Source-available; see the licensing section below for AGPLv3 provisions, Enterprise terms, and the competing-SaaS restriction
- Package Manager: pnpm (v9.12.3) - REQUIRED
- Build System: Nx (v20.0.8) with intelligent caching and task orchestration
- Development Runtime: Node.js 22 recommended, matching current CI
- Language: TypeScript 5.7.3
Core Philosophy
- Extend business capabilities through plugin architecture
- Self-host to control your deployment and data
- Microservices with GraphQL Federation
- Micro-frontends with Module Federation
Architecture & Technology Stack
Backend Stack
┌─────────────────────────────────────────┐
│ API Gateway (Port 4000) │
│ Apollo Router + Service Discovery │
└─────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Core API │ │ Plugin │ │ Plugin │
│ (3300) │ │ APIs │ │ APIs │
└──────────┘ └──────────┘ └──────────┘
│ │ │
└─────────────┴─────────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ MongoDB │ │ Redis │
│ │ │ + BullMQ │
└──────────┘ └──────────┘
Technologies:
- Runtime: Node.js with TypeScript 5.7.3
- Framework: Express.js
- GraphQL: Apollo Server v4, Apollo Federation (@apollo/subgraph)
- Service Communication: tRPC v11 for type-safe service-to-service calls
- Database: MongoDB with Mongoose (v8.13.2)
- Cache/Queue: Redis (ioredis) + BullMQ v5.40.0
- Real-time: GraphQL Subscriptions (graphql-redis-subscriptions)
- Authentication: JWT (jsonwebtoken), WorkOS for SSO
Frontend Stack
The main frontend consists of the Core UI host and independently buildable plugin remotes. Ports shown here are development defaults; individual projects define their own ports.
┌─────────────────────────────────────────┐
│ Core UI (Host - Port 3001) │
│ Module Federation Host Application │
└─────────────────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ Plugin │ │ Plugin │ │ Plugin │
│ UI (3005)│ │ UI (3006)│ │ UI (3007)│
└──────────┘ └──────────┘ └──────────┘
Technologies:
- Framework: React 18.3.1
- Bundler: Rspack v1.0.5 (Rust-based)
- Module Federation: @module-federation/enhanced v0.6.6
- Styling: TailwindCSS v4.1.17 + PostCSS
- UI Components:
erxes-ui, the Radix-based design system, andui-modulesfor reusable business UI - State Management: Jotai (atomic state) + Apollo Client
- Routing: React Router v7
- Forms: React Hook Form + Zod validation
- i18n: react-i18next
- Rich Text: BlockNote editor
- Icons: @tabler/icons-react
- Data Visualization: Recharts
Apps
Standalone applications have their own dependencies. The React 18 version above applies to the main frontend, not every application in the repository. Frontend plugin development should use the public components in erxes-ui and ui-modules rather than importing Radix primitives directly.
Standalone Applications:
- client-portal-template: Next.js 16 customer portal using React 19
- posclient-front: Next.js 14 POS with PWA support
- frontline-widgets: Customer-facing widgets (chat, forms)
- help-center: Next.js 16 help center using React 19
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 procedures use tRPC where the owning module defines 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, the checked Core API returns plugin asset URLs hosted at plugins.erxes.io. Read the self-hosting guide before assuming all browser assets are served by your own host.
Repository Structure
This tree highlights the main development areas; it is not an exhaustive directory listing.
erxes/
├── backend/ # Backend microservices
│ ├── gateway/ # API Gateway (Port 4000)
│ │ └── src/main.ts # Gateway entry point
│ ├── core-api/ # Core business logic (Port 3300)
│ │ ├── src/
│ │ │ ├── main.ts # Core API entry point
│ │ │ ├── apollo/ # GraphQL schema & resolvers
│ │ │ ├── init-trpc.ts # Core tRPC router
│ │ │ ├── modules/ # Business logic modules
│ │ │ │ ├── contacts/
│ │ │ │ ├── products/
│ │ │ │ ├── segments/
│ │ │ │ ├── automations/
│ │ │ │ └── documents/
│ │ │ ├── meta/ # Automation, segment configs
│ │ │ └── routes.ts # Express routes
│ │ ├── Dockerfile
│ │ ├── project.json # Nx configuration
│ │ └── tsconfig.json
│ ├── erxes-api-shared/ # Shared library for all services
│ │ └── src/
│ │ ├── utils/ # Service discovery, Redis, MQ
│ │ ├── core-types/ # TypeScript type definitions
│ │ └── core-modules/ # Reusable business logic
│ ├── plugins/ # Plugin microservices
│ │ ├── sales_api/ # Sales plugin (Port 3305)
│ │ ├── operation_api/ # Operations plugin
│ │ ├── frontline_api/ # Customer service plugin
│ │ ├── accounting_api/ # Accounting plugin
│ │ ├── content_api/ # Content management
│ │ └── ...
│ └── services/ # Background services
│ ├── automations/ # Automation execution engine
│ └── logs/ # Logging service
├── frontend/ # Frontend applications
│ ├── core-ui/ # Module federation host (Port 3001)
│ │ ├── src/
│ │ │ ├── main.ts # Entry point
│ │ │ └── bootstrap.tsx # App bootstrap
│ │ └── module-federation.config.ts
│ ├── libs/ # Shared UI libraries
│ │ ├── erxes-ui/ # Core UI components & state
│ │ └── ui-modules/ # Reusable UI modules
│ └── plugins/ # Frontend plugin remotes
│ ├── sales_ui/ # Sales UI plugin (Port 3005)
│ │ ├── src/
│ │ │ ├── config.tsx # Plugin configuration
│ │ │ ├── modules/ # Module components
│ │ │ ├── pages/ # Page components
│ │ │ └── widgets/ # Widget components
│ │ ├── module-federation.config.ts
│ │ └── rspack.config.ts
│ └── ...
├── apps/ # Standalone applications
│ ├── client-portal-template/ # Next.js 16 customer portal
│ ├── posclient-front/ # Next.js 14 POS client
│ ├── help-center/ # Next.js 16 help center
│ └── frontline-widgets/ # Customer-facing widgets
├── scripts/ # Development scripts
│ ├── create-plugin.js # Plugin generator
│ ├── start-api-dev.js # Start all API services
│ └── start-ui-dev.js # Start all UI plugins
├── .github/workflows/ # CI/CD pipelines
├── nx.json # Nx configuration
├── pnpm-workspace.yaml # pnpm workspace config
├── package.json # Root package.json
├── tsconfig.base.json # Base TypeScript config
└── AGENTS.md # Repository contributor and agent guidance
Licensing & Deployment
erxes is source-available. The repository's LICENSE.md contains AGPLv3 provisions, references separate Enterprise Edition terms, and explicitly states that erxes may not be hosted as a SaaS version that competes with erxes Inc. Third-party components retain their respective licenses.
Self-hosting, modifying, and distributing erxes remain subject to the applicable license terms. Source availability does not mean every plugin or commercial deployment is unrestricted. Consult the license for your checkout and confirm Enterprise or SaaS arrangements with erxes before relying on a particular commercial use or plugin entitlement.
For current hosted offerings, Enterprise options, and pricing, consult erxes. When self-hosting, your team is responsible for deployment, upgrades, backups, and ongoing infrastructure maintenance.
Next Steps
Continue to Local Setup to prepare your development environment and run erxes locally.
Source references
This overview is tied to the checked 3.1.7 revision, not a guarantee about the latest branch. Dependency declarations describe version ranges; the lockfile records resolved packages.
