Introduction to Twenty CRM

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• PRODUCT.md
• packages/twenty-docs/README.md
• packages/twenty-codex-plugin/AGENTS.md
• packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md

Twenty is an open-source Customer Relationship Management (CRM) platform designed to provide technical teams with the building blocks for complex business needs. Unlike traditional CRMs, Twenty is built to be versioned, shipped, and extended like standard software stacks. It provides a modular architecture that allows users to define objects, workflows, and AI agents as code.

Sources: README.md:16-20, PRODUCT.md:5-10

The platform serves as an API backbone for go-to-market stacks, enabling deep integration with external tools and the creation of custom internal applications. It supports multiple deployment models, including a managed cloud service and self-hosting options via Docker and Kubernetes.

Sources: README.md:25-45, packages/twenty-website/src/app/[locale]/customers/elevate-consulting/page.tsx:75-80

Architecture Overview

Twenty is structured as an Nx workspace monorepo, utilizing a modern full-stack TypeScript environment. The architecture is designed for multi-tenancy and high extensibility through a dedicated Apps framework.

Technical Stack

Layer	Technologies
Frontend	React 18, TypeScript, Jotai (State), Linaria (Styling), Vite, Lingui (i18n)
Backend	NestJS, TypeORM, PostgreSQL, Redis, GraphQL (Yoga), BullMQ (Jobs)
Monorepo	Nx workspace, Yarn 4
Analytics	ClickHouse (Optional)

Sources: CLAUDE.md:100-140, README.md:105-115

Core Components

The following diagram illustrates the high-level relationship between the main packages in the Twenty repository:

The frontend application (twenty-front) communicates with the NestJS backend (twenty-server) primarily via GraphQL. Common utilities and types are shared across the monorepo via the twenty-shared package.

Sources: CLAUDE.md:118-128, CLAUDE.md:175-182

Data Model & Extensibility

Twenty uses a code-first approach to data modeling. Users can extend standard objects (like Person, Company, and Opportunity) or define entirely custom objects.

Object Definitions

Entities are defined using the Twenty SDK. A typical object definition includes fields, labels, and metadata.

import { defineObject, FieldType } from 'twenty-sdk/define';

export default defineObject({
  nameSingular: 'deal',
  namePlural: 'deals',
  labelSingular: 'Deal',
  labelPlural: 'Deals',
  fields: [
    { name: 'name', label: 'Name', type: FieldType.TEXT },
    { name: 'amount', label: 'Amount', type: FieldType.CURRENCY },
  ],
});

Sources: README.md:37-45

Standard vs Custom Objects

Twenty encourages a "database discipline" where standard objects are reused and extended before creating new custom objects. For example, a human actor is typically modeled as a Person with a role flag rather than a new custom object.

Object Type	Description
Standard	Core CRM entities: Companies, Persons, Opportunities, Tasks, Notes.
Custom	Domain-specific entities defined by the user (e.g., "Deals", "Properties").
System	Built-in relations and timelines automatically attached to objects.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-partner-design-doc/design-doc-doctrine.md:115-125, packages/twenty-codex-plugin/references/publish-app/prepare-for-app-store.md:35-45

Feature Set

AI Agents & Workflows

Twenty integrates AI as a core capability rather than an add-on. AI agents can be configured with custom "skills" to perform tasks like lead scoring, automated outreach, and account research. These agents interact directly with the CRM data via the Model Context Protocol (MCP).

Sources: README.md:95-102, packages/twenty-claude-skills/skills/twenty-record-presentation/SKILL.md:10-25

Layouts & UI Components

The UI is composed of several surfaces:

• Views: Table, Kanban, and Calendar views for data visualization.
• Front Components: React components that can be registered to render inside the Twenty UI.
• Command Menu: Quick action triggers for workspace navigation and entity management.

Sources: packages/twenty-codex-plugin/AGENTS.md:50-65, packages/twenty-docs/README.md:10-15

Deployment & Operations

Twenty supports various deployment environments to match different security and infrastructure requirements.

Environment	Description
Twenty Cloud	Managed SaaS offering, zero-ops setup.
Docker Compose	Community-supported containerized deployment for self-hosting.
Kubernetes	Community-maintained Helm charts for enterprise-grade orchestration.
Local Dev	Nx-driven development environment with support for Postgres and Redis.

Sources: README.md:27-35, packages/twenty-docker/k8s/README.md:5-15, CLAUDE.md:15-30

Database Migrations

Twenty manages schema changes through "Instance Commands." These are categorized as:

• Fast: Handles standard schema changes (columns, types, constraints).
• Slow: Includes data backfills or complex transformations via a runDataMigration step.

Sources: CLAUDE.md:75-85

Summary

Twenty CRM represents a shift from "bought" to "built" CRM systems. By providing the core primitives of a CRM (objects, layouts, and workflows) as code-extensible building blocks, it allows organizations to maintain full ownership of their go-to-market infrastructure while leveraging modern AI and automation capabilities.