# Twenty CRM — Developer Reference Wiki

> Twenty is an open-source, self-hostable CRM built as an Nx monorepo with a NestJS/GraphQL backend, React/Jotai frontend, and a multi-tenant metadata-driven schema engine. This reference covers architecture, core modules, data flows, and operational surfaces for contributors and integrators.

This is a Grok-Wiki source-grounded repository wiki. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown wiki](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6.md)
- [Human interactive wiki](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6)
- [GitHub repository](https://github.com/twentyhq/twenty)

## Repository

- Repository: twentyhq/twenty

- Generated: 2026-05-27T05:38:42.694Z
- Updated: 2026-05-29T04:34:33.990Z
- Runtime: Claude Code
- Format: Technical
- Pages: 6

## Pages

- [Technical Orientation](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/01-technical-orientation.md): Repository layout, Nx workspace conventions, tech stack, key entry points (main.ts, app.module.ts, index.tsx), and how the backend, frontend, and shared packages relate to each other. Starting point for any new contributor.
- [Metadata Engine & Multi-Tenant Schema](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/02-metadata-engine-multi-tenant-schema.md): The heart of Twenty's flexibility: the metadata engine that drives dynamic object definitions, field types, relations, and per-workspace GraphQL schema generation. Covers TwentyORM, workspace datasource, metadata modules (object-metadata, field-metadata, index-metadata), and the workspace cache layer.
- [Core NestJS Modules & API Surface](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/03-core-nestjs-modules-api-surface.md): Server-side domain modules: auth (JWT, SSO), billing, messaging, calendar, workflow, workspace, and the GraphQL API layers (code-first resolvers, subscriptions, dataloaders). How NestJS modules are registered in app.module.ts and how the GraphQL Yoga gateway is configured.
- [Workspace Runtime, Jobs & Instance Commands](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/04-workspace-runtime-jobs-instance-commands.md): BullMQ background worker, queue-worker bootstrapping, database migration commands (RegisteredInstanceCommand / RegisteredWorkspaceCommand), upgrade pattern (fast vs slow instance commands), and the workspace event emitter that drives real-time side effects.
- [Frontend Module Map & State Architecture](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/05-frontend-module-map-state-architecture.md): React 18 / Jotai / Apollo Client architecture: how modules (object-record, settings, auth, workflow, command-menu, navigation) are structured, how global state atoms compose with GraphQL cache, and the Linaria/Lingui conventions. Covers the twenty-ui shared component library and the metadata-store that mirrors backend schema on the client.
- [Integrations, Extension Points & Operational Surfaces](https://grok-wiki.com/public/wiki/twentyhq-twenty-7ed82e5a21f6/pages/06-integrations-extension-points-operational-surfaces.md): External integration surfaces: Zapier connector, REST/GraphQL client SDK (twenty-client-sdk), email templates (twenty-emails), connected-account sync (messaging, calendar), AI/code-interpreter modules, and the Docker Compose dev/prod setup. How to extend Twenty with new workspace modules, custom objects, and external connectors.

## Source Files

- `CLAUDE.md`
- `nx.json`
- `package.json`
- `packages/twenty-client-sdk`
- `packages/twenty-docker`
- `packages/twenty-e2e-testing`
- `packages/twenty-emails/src`
- `packages/twenty-front/src/index.tsx`
- `packages/twenty-front/src/modules/auth`
- `packages/twenty-front/src/modules/command-menu`
- `packages/twenty-front/src/modules/metadata-store`
- `packages/twenty-front/src/modules/navigation`
- `packages/twenty-front/src/modules/object-record`
- `packages/twenty-front/src/modules/settings`
- `packages/twenty-front/src/modules/workflow`
- `packages/twenty-server/docs/UPGRADE_COMMANDS.md`
- `packages/twenty-server/src/app.module.ts`
- `packages/twenty-server/src/command`
- `packages/twenty-server/src/database`
- `packages/twenty-server/src/engine/api`
- `packages/twenty-server/src/engine/core-entity-cache`
- `packages/twenty-server/src/engine/core-modules/ai`
- `packages/twenty-server/src/engine/core-modules/auth`
- `packages/twenty-server/src/engine/core-modules/billing`
- `packages/twenty-server/src/engine/core-modules/core-engine.module.ts`
- `packages/twenty-server/src/engine/dataloaders`
- `packages/twenty-server/src/engine/metadata-modules/field-metadata`
- `packages/twenty-server/src/engine/metadata-modules/object-metadata`
- `packages/twenty-server/src/engine/subscriptions`
- `packages/twenty-server/src/engine/twenty-orm`
- `packages/twenty-server/src/engine/workspace-cache`
- `packages/twenty-server/src/engine/workspace-cache-storage`
- `packages/twenty-server/src/engine/workspace-datasource`
- `packages/twenty-server/src/engine/workspace-event-emitter`
- `packages/twenty-server/src/engine/workspace-manager`
- `packages/twenty-server/src/main.ts`
- `packages/twenty-server/src/modules/connected-account`
- `packages/twenty-server/src/modules/messaging`
- `packages/twenty-server/src/modules/modules.module.ts`
- `packages/twenty-server/src/modules/workflow`
- `packages/twenty-server/src/queue-worker`
- `packages/twenty-ui/src`
- `packages/twenty-utils/setup-dev-env.sh`
- `packages/twenty-zapier`
- `README.md`
- `tsconfig.base.json`