Introduction

What is erxes?

Hello 👋 Welcome to the erxes developer documentation!

erxes is a source available experience management infrastructure. Pioneering the future of experiences with XOS (Experience Operating System). Hubspot + Qualitics alternative

What can you do with erxes?

Achieving growth and unity within your company is possible. Find more about what you can do with erxes as follows:

erxes is a source available project (see LICENSE for more information); everyone (individuals and companies, especially SaaS providers) can use it for free privately to create better experiences for everything they do, such as customer, employee, production, service, and many more experiences.

erxes Marketplace serves as a hub for accessing a diverse range of plugins, extensions, and integrations designed to enhance the functionality and capabilities of the erxes operating system. From productivity tools to specialized industry solutions, the Marketplace offers a curated selection of offerings to cater to the varying needs of users. Whether you're a small business looking to streamline your operations or a large enterprise seeking advanced features, the Marketplace provides a one-stop shop for discovering and implementing valuable additions to your erxes experience. With user reviews, ratings, and detailed descriptions, you can easily evaluate and select the right plugins for your specific requirements. Additionally, developers and third-party providers can leverage the Marketplace to showcase their creations, reaching a broader audience of erxes users and contributing to the ecosystem's growth. By fostering collaboration and innovation, the Marketplace enriches the erxes community, empowering users to tailor their experience and maximize the value derived from the platform.

Open-source & Contribution

Our community is at the heart of everything we do. We understand that people who contribute to a project are the main drivers who push a project forward. erxes core project, the documentation, and any related tool can be found in the erxes on GitHub.

• erxes - erxes codebase
• erxes Docker - erxes containerized
• erxes Contributing guide - to contribute

Community

erxes documentation contains instructions for everything you need to know about erxes. For additional information, you can use any of these channels to get the answer you want:

Support

If you need any support during your development with erxes, you can join our Discord. You will get help directly from our core team and our community.

By joining our Discord Server, you'll also have the chance to participate in many events and showcase your work with erxes.

Project Overview

erxes (pronounced 'erk-sis') is a secure, self-hosted, and scalable source-available Experience Operating System (XOS) that enables businesses to manage marketing, sales, operations, and support in one unified platform.

Key Characteristics

• Architecture: Nx-powered pnpm monorepo with microservices architecture
• License: AGPLv3 (core) with Enterprise Edition plugins
• Package Manager: pnpm (v9.12.3) - REQUIRED
• Build System: Nx (v20.0.8) with intelligent caching and task orchestration
• Version: TypeScript 5.7.3, Node.js 18+

Core Philosophy

• 100% customizable through plugin architecture
• Self-hosted for data privacy
• 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   │  │Elasticsea│
│          │  │  +BullMQ │  │   rch    │
└──────────┘  └──────────┘  └──────────┘

Technologies:

• Runtime: Node.js with TypeScript 5.7.3
• Framework: Express.js
• GraphQL: Apollo Server v4, Apollo Federation (@apollo/subgraph)
• API: tRPC v11 for type-safe endpoints
• Database: MongoDB with Mongoose (v8.13.2)
• Cache/Queue: Redis (ioredis) + BullMQ v5.40.0
• Search: Elasticsearch 7
• Real-time: GraphQL Subscriptions (graphql-redis-subscriptions)
• Authentication: JWT (jsonwebtoken), WorkOS for SSO

Frontend Stack

┌─────────────────────────────────────────┐
│    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, faster than Webpack)
• Module Federation: @module-federation/enhanced v0.6.6
• Styling: TailwindCSS v4.1.17 + PostCSS
• UI Components: Radix UI primitives + custom design system (erxes-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:

1. client-portal-template: Next.js 16 customer portal
2. posclient-front: Next.js 14 POS with PWA support
3. frontline-widgets: Customer-facing widgets (chat, forms)

Repository Structure

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
│   │   │   ├── trpc/         # 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 (EE)
│   │   ├── content_api/      # Content management (EE)
│   │   └── ...
│   └── 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
│   └── 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 (26+ workflows)
├── nx.json                    # Nx configuration
├── pnpm-workspace.yaml        # pnpm workspace config
├── package.json               # Root package.json
├── tsconfig.base.json         # Base TypeScript config
└── CLAUDE.md                  # This file

What kind of licence erxes has?

Please see the LICENSE file for licensing information.

Are these all free? Can we just use it for free?

Yes, we're source available software, our license is AGPLv3 with Enterprise Edition, which means some of our plugins and code for SaaS are require prior agreement and kept private under Enterprise Edition. But the rest are all free for you to install and use for you. Please read more about our license here.

However, we provides 5 different packages for our clients, which include:

Self-serve version that is suitable for small to medium enterprises who want to leave all your tech-related work to us and only focus on your main operation that is non-technical. Pricing is super simple in that you can get access to erxes for free and use it as long as you want as an individual. Then as your business grows, you can only pay for what you need, rather than having a bunch of junk that comes within the package.

Self-hosted version that is suitable for SaaS providers or enterprises operating in highly regulated industries, like insurance, mobile network providers, banking and etc. As it is self-hosted, you must ensure you and your organization have a skilled DevOps person/team to look after the server to maintain the smooth operation of your erxes operating system daily. As an erxes user, you can choose between using the Source Available Edition, which is entirely free, or paid plan of the Enterprise Edition.

Enterprise version of erxes caters to the needs of established businesses and organizations requiring robust solutions. It offers advanced features tailored for large-scale operations, including enhanced security measures and comprehensive analytics tools. With flexible pricing options, you can scale your usage according to your requirements, ensuring cost-effectiveness as your enterprise grows.

Embedded version of erxes is designed for integration within third-party applications or platforms, offering seamless customer experience management capabilities. This version allows developers to embed erxes functionalities directly into their software, enhancing user engagement and satisfaction. With customizable features and API integrations, you can tailor the embedded version to align perfectly with your product offerings and branding.

Platform version of erxes is ideal for entrepreneurs looking to launch and manage platform businesses. With white-labeling options and extensive customization capabilities, you can adapt the platform to suit your specific niche and branding requirements. Leveraging erxes core plugins, components, and enterprise features, you can power your entire platform ecosystem, offering high-value services and generating revenue through paid plugins and subscriptions.

Infrastructure version is for is the best choice for starting a platform business. You can white-label the design or change every line of code to make it work for you, and this is where you can leverage erxes core plugins, components, and enterprise features to power your entire platform business that includes some of the very specific, high-level paid plugins.

Edit this page