Backend Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- CLAUDE.md
- packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md
- packages/twenty-codex-plugin/AGENTS.md
- packages/twenty-codex-plugin/CHANGELOG.md
- packages/twenty-codex-plugin/references/develop-app/app-structure.md
- packages/twenty-codex-plugin/skills/develop-app/SKILL.md
The backend of Twenty is built as a robust, multi-tenant system using the NestJS framework. It serves as the core engine for data management, business logic execution, and integration handling within the Nx monorepo workspace. The architecture is designed to support high extensibility through modular packages and a unified API layer.
Sources: CLAUDE.md:12-18, CLAUDE.md:122-127
Core Tech Stack
The backend follows a modern TypeScript-based stack optimized for performance and scalability.
| Component | Technology | Purpose |
|---|---|---|
| Framework | NestJS | Feature organization and dependency injection |
| ORM | TypeORM | Database interaction and schema management |
| Primary Database | PostgreSQL | Relational data storage and multi-tenancy |
| Cache/Sessions | Redis | Session management and high-speed data access |
| API Layer | GraphQL (GraphQL Yoga) | Unified data access for frontend and apps |
| Background Jobs | BullMQ | Asynchronous job processing and task queuing |
| Analytics | ClickHouse | Large-scale analytical data processing (when enabled) |
Sources: CLAUDE.md:122-127, CLAUDE.md:154-157
Multi-Tenancy and Database Structure
The backend utilizes a multi-tenant schema structure within PostgreSQL to isolate data across different workspaces. This includes core system schemas, metadata schemas for configuration, and individual workspace-specific schemas for tenant data.
The database isolation ensures that workspace members can only interact with their specific data while the system maintains global metadata for schema generation.
Sources: CLAUDE.md:79-84, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:213-219
Application Extensibility
Extensibility is achieved through "Twenty Apps," which are modular extensions that can define new data models, logic, and UI components. The backend manages the lifecycle and registration of these extensions.
Logic Functions and Automations
Automations can be implemented using two primary mechanisms:
- Workflows: Visual, trigger-based automations managed within the product.
- Logic Functions: TypeScript-based serverless functions that handle complex side effects or external integrations. These are often sandboxed for production safety.
Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:94-98, packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:143-150
Integration Lifecycle
The backend facilitates connections to third-party services via OAuth and connection providers.
Data Management Patterns
The backend enforces strict naming conventions and file structures for maintainability. Services are kept under 500 lines, and entities use kebab-case with descriptive suffixes.
Naming Conventions
- Services:
*.service.ts - Entities:
*.entity.ts - DTOs:
*.dto.ts - Modules:
*.module.ts - Utils:
<name>.util.ts
Sources: CLAUDE.md:105-110, packages/twenty-codex-plugin/references/develop-app/app-structure.md:46-52
Instance and Workspace Commands
The backend manages schema changes and data migrations through specialized command decorators:
- @RegisteredInstanceCommand: Automatic discovery of commands that apply schema or structural changes.
- @RegisteredWorkspaceCommand: Commands that iterate over active/suspended workspaces to perform per-tenant upgrades.
Sources: CLAUDE.md:146-152
Testing and Quality Assurance
The backend uses a pyramid strategy for testing, prioritizing unit and integration tests.
Integration tests are specifically isolated, often running against a dedicated database instance on port 2021 to avoid interference with development data on port 2020.
Sources: CLAUDE.md:167-169, packages/twenty-codex-plugin/AGENTS.md:52-58, packages/twenty-codex-plugin/CHANGELOG.md:57-62
Summary
The Twenty backend architecture is a modular, multi-tenant system built on NestJS and PostgreSQL. It balances structural rigidity through enforced coding standards and multi-schema isolation with high flexibility via the Twenty App SDK. By leveraging Redis for caching and BullMQ for background tasks, the backend provides a scalable foundation for both core CRM features and custom-built extensions.