Repository Structure

Understand the top-level layout of erxes/erxes so you can find backend services, frontend projects, plugins, and standalone apps. This guide follows version 3.1.7 (03acdf712c).

For running the product from source, use Local Setup. For the service runtime, see Backend & API Gateway.

Top-level directories

erxes/
├── backend/
│   ├── core-api/          Core business logic (port 3300)
│   ├── gateway/           API gateway + Apollo Router (port 4000)
│   ├── erxes-api-shared/  Shared library for all services
│   ├── plugins/           Plugin microservices (*_api)
│   └── services/          Background services (automations, logs)
├── frontend/
│   ├── core-ui/           Module Federation host (port 3001)
│   ├── libs/              erxes-ui + ui-modules shared UI
│   └── plugins/           Frontend remotes (*_ui)
├── apps/                  Standalone apps (not started by dev:apis/dev:uis)
│   ├── client-portal-template/
│   ├── help-center/
│   ├── frontline-widgets/
│   └── posclient-front/
├── scripts/               create-plugin, start-api-dev, start-ui-dev
├── .github/workflows/     CI image builds per service/app
├── nx.json                Nx task orchestration
├── pnpm-workspace.yaml    Includes backend/** and frontend/**
└── AGENTS.md              Contributor and agent rules

Backend

• backend/core-api/src/main.ts starts Core API on PORT || 3300 and joins the gateway via joinErxesGateway.
• backend/gateway/src/main.ts listens on 4000, proxies /graphql to the internal Apollo Router on 50000.
• backend/erxes-api-shared/src/ holds utils/ (service discovery, Redis, tRPC, agent-tools), core-modules/ (reusable domain logic), and core-types/.
• backend/plugins/*_api/src/main.ts starts each plugin with startPlugin({ name, port }). For example Sales uses port 3305.
• backend/services/automations and backend/services/logs run queue workers; they are not plugin APIs.

Frontend

• frontend/core-ui/src/bootstrap.tsx is the browser entry. In development it renders directly; in production it fetches /get-frontend-plugins and loads remotes.
• frontend/core-ui/module-federation.config.ts maps ENABLED_PLUGINS to <name>_ui remotes. The host runs on port 3001.
• frontend/libs/erxes-ui/src provides generic UI primitives; frontend/libs/ui-modules/src provides business-domain UI. Import them as erxes-ui and ui-modules.
• frontend/plugins/*_ui/src/ holds config.tsx, modules/, pages/, and widgets/ per plugin.

Apps and scripts

Standalone apps under apps/ have their own dependencies and ports (3800, 3900, 7002, widgets build). They are deployed separately; see Client Portal, Help Center, POS Client, and Messenger Installation.

scripts/start-api-dev.js maps ENABLED_PLUGINS to *_api projects plus gateway; scripts/start-ui-dev.js maps them to *_ui remotes for Core UI.

Source references

• Root manifest and workspace.
• Core API entry and gateway entry.
• Service discovery.
• Contributor rules.