Introduction to Twenty
Understand Twenty, the
Introduction to Twenty
TL;DR for Product Managers
Twenty is an open-source CRM — think Salesforce or HubSpot, but self-hostable, customizable, and free. Teams use it to track companies, contacts, and deals. What makes it different is that you can create custom data objects (like Notion databases), automate workflows (like Zapier), and integrate email and calendar — all within a modern, Linear-like UI.
What is Twenty?
Twenty is a modern, open-source Customer Relationship Management (CRM) platform. It's a full-stack monorepo containing 15+ packages that together deliver a product competitive with Salesforce and HubSpot — but with full source code access, self-hosting, and a dramatically better user experience inspired by tools like Notion, Linear, and Airtable.
The Product at a Glance
| Dimension | Details |
|---|---|
| What it does | CRM — manage companies, contacts, deals, emails, calendar |
| Who uses it | Sales teams, startups, any company tracking customer relationships |
| How it's different | Open-source, self-hosted, custom objects, modern UX, workflow automation |
| Core tech | NestJS + React + PostgreSQL + Redis |
| Repo structure | Nx monorepo (15+ packages with Yarn workspaces) |
| License | AGPL-3.0 |
| Deployment | Docker Compose (4 services), plus K8s, Railway, Coolify, etc. |
Core Concepts
Twenty organizes data around Workspaces (multi-tenant) and a metadata-driven object system. Unlike traditional CRMs with rigid schemas, Twenty lets users define their own data objects.
Standard Objects (Built-In)
Workspace (your organization — the multi-tenancy boundary)
├── Companies (businesses you're tracking)
│ └── People (contacts at those companies)
├── Opportunities (deals / sales pipeline)
├── Tasks (to-dos and follow-ups)
├── Notes (free-form notes attached to records)
├── Messages (synced emails from Gmail / Microsoft)
├── Calendar Events (synced calendar from Gmail / Microsoft)
├── Workflows (automation: triggers → actions)
├── Attachments (files linked to records)
├── Views (saved filters, sorts, layouts per object)
└── Workspace Members (team members with roles)Custom Objects
The key differentiator: Twenty's metadata-driven architecture lets users create entirely new data objects (like "Vendors", "Partnerships", or "Support Tickets") with custom fields, relationships, and views — all without changing the backend code. The server dynamically generates GraphQL schemas and database tables from metadata definitions.
For PMs: Why Custom Objects Matter
Traditional CRMs force your business into predefined categories (Leads, Contacts, Accounts, Deals). If your workflow doesn't fit, you're stuck with workarounds. Twenty's custom objects let you model your exact business process — similar to creating a custom database in Notion, but with full CRM features (relationships, views, automations) built on top.
The Tech Stack — Why Each Piece Exists
| Layer | Technology | Why It's Used |
|---|---|---|
| Backend | NestJS 11 (TypeScript) | Enterprise-grade Node.js framework with dependency injection |
| API | GraphQL (Yoga) + REST | GraphQL for flexible queries; REST for simple integrations |
| Database | PostgreSQL 16 | Relational integrity for complex CRM relationships |
| ORM | TypeORM | Mature Node.js ORM with migration support |
| Cache / Broker | Redis | Session cache + BullMQ message broker |
| Job Queue | BullMQ | Background jobs (email sync, webhooks, workflows) |
| Analytics | ClickHouse | High-performance columnar store for analytics queries |
| Frontend | React 18 + Vite 7 | Fast SPA with modern build tooling |
| State | Jotai | Atomic state management — minimal boilerplate |
| GraphQL Client | Apollo Client | Mature GraphQL client with caching and real-time |
| Styling | Linaria (@wyw-in-js) | Zero-runtime CSS-in-JS — no performance cost |
| i18n | Lingui | Internationalization (17+ languages) |
| UI Components | Internal twenty-ui + Mantine | Custom component library built on accessible primitives |
| Rich Text | BlockNote + TipTap | Block-based editor for notes and descriptions |
| Real-time | GraphQL SSE | Server-Sent Events for live database updates |
| Build | Nx + Yarn workspaces | Monorepo orchestration with caching |
| Auth | Passport (JWT, OAuth, SAML, OIDC) | Multi-method authentication |
| Payments | Stripe | Billing for hosted version |
| AI | AI SDK (OpenAI, Anthropic, etc.) | AI-powered features |
For PMs: What's Metadata-Driven?
Most CRMs have a fixed database schema — adding a new object type requires a developer to write code, create migrations, and deploy. Twenty stores object definitions as metadata in the database itself. When a user creates a "Vendors" custom object, Twenty reads the metadata and dynamically creates the database table, GraphQL schema, and UI — no deployment needed. This is the same pattern Salesforce uses internally.
Key Statistics
| Metric | Value |
|---|---|
| Monorepo packages | 15+ |
| Backend modules | 40+ NestJS modules |
| Standard CRM objects | 10+ (Company, Person, Opportunity, Task, Note, etc.) |
| Job queues | 15+ (messaging, calendar, workflow, email, webhook, etc.) |
| Auth methods | 6 (JWT, Google OAuth, Microsoft OAuth, SSO, SAML, OIDC) |
| Supported languages | 17+ via Lingui i18n |
| GitHub stars | 25,000+ |
| Docker services | 4 (server, worker, PostgreSQL, Redis) |
| API types | GraphQL + REST (both fully featured) |
Core Features
CRM Fundamentals
- Companies & People — Track organizations and contacts with rich fields (domain, ARR, employees, emails, phones, addresses)
- Opportunities — Sales pipeline with kanban and table views, custom stages
- Tasks & Notes — To-do tracking and free-form notes attached to any record
- Views — 5 layout types (Table, Kanban, Calendar, etc.) with filters, sorts, group-by
Modern Differentiators
- Custom Objects & Fields — Create any data type with custom relationships
- Workflow Automation — Trigger-based automations (record created → send email, update field, call webhook)
- Email Integration — Gmail and Microsoft 365 sync (read, send, track)
- Calendar Integration — Google Calendar and Microsoft calendar sync
- Permissions & Roles — Custom RBAC with granular field-level permissions
- AI Features — AI SDK integration for enrichment, summarization, and more
- Apps Ecosystem — Plugin system for community and internal extensions
- Zapier Integration — Connect to 5,000+ external services
- Webhooks — Event-driven notifications to external systems
- API (GraphQL + REST) — Both fully featured for programmatic access
- Self-hosting — Full control over data and infrastructure
User Experience
- Modern UI — Inspired by Linear, Notion, and Airtable
- Keyboard shortcuts — Power-user navigation
- Command palette — Quick search and actions
- Dark mode — Built-in theme support
- Internationalization — 17+ languages
What Makes Twenty Different
- Metadata-driven custom objects — Like Salesforce's platform but fully open-source
- Modern UX — Miles ahead of Salesforce/HubSpot in design and usability
- Open-source + self-hosted — Own your CRM data completely
- Dual API (GraphQL + REST) — Flexible integration options
- Workflow automation — Built-in automation engine with visual editor
- Email & calendar sync — Native Gmail/Microsoft integration, not a bolt-on
What's Next
Architecture Overview
System design, database schema, metadata engine, and API patterns.
Workflows & Data Flows
Key user journeys traced through frontend, API, and database.
How Twenty Is Built
Repository structure, build system, dependencies, and deployment.