# twentyhq/twenty architecture

> Architecture diagram of the GitHub repository twentyhq/twenty, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/twentyhq/twenty
- Repository: https://github.com/twentyhq/twenty
- Video tour (about a minute): https://gitdiagram.com/twentyhq/twenty/video

## Overview

Twenty is an open-source, extensible CRM. A typical user works with workspace records and views in the CRM, while the server provides application and data services; developers can define app objects, views, agents, and logic functions as code and publish them to a workspace. The repository also includes a desktop call-recording companion and example apps. The README documents the product capabilities, but the sampled source does not establish most frontend-to-server or server-to-storage call paths, so those links are omitted rather than inferred.

Main entry points: [`packages/twenty-companion/src/main/services/RecordingController.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/RecordingController.ts) (Desktop companion), [`packages/twenty-apps`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps) (Workspace apps), [`packages/twenty-front/src`](https://github.com/twentyhq/twenty/tree/main/packages/twenty-front/src) (CRM interface), [`packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts`](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts) (Server API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_crm["CRM experience"]
  node_crm_ui["CRM interface"]
  node_records[("CRM records")]
  node_views["Views"]
  node_workflows["Workflows"]
  node_agents["AI agents"]
end

subgraph group_server["CRM services"]
  node_server_api["Server API"]
  node_applications["Application service"]
  node_marketplace["App marketplace"]
end

subgraph group_apps["App platform"]
  node_sdk["App SDK"]
  node_scaffold["App scaffolding"]
  node_published_app["Workspace apps"]
  node_real_estate["Real estate CRM<br/>[property.object.ts]"]
end

subgraph group_companion["Desktop companion"]
  node_companion_app["Desktop companion"]
  node_companion_state["Meeting state<br/>[CompanionState.ts]"]
  node_workspace_client["Workspace client<br/>[TwentyClient.ts]"]
  node_recorder["Recording capture"]
end

node_user(("CRM user"))
node_recall["Recall desktop SDK"]

node_user -.->|"uses"| node_crm_ui
node_crm_ui -.->|"accesses CRM"| node_server_api
node_server_api -.->|"queries records"| node_records
node_user -.->|"works in views"| node_views
node_user -.->|"uses workflows"| node_workflows
node_user -.->|"uses agents"| node_agents
node_scaffold -->|"creates app"| node_published_app
node_sdk -->|"defines primitives"| node_published_app
node_published_app -->|"publishes to workspace"| node_applications
node_applications -.->|"offers apps"| node_marketplace
node_real_estate -->|"defines pipeline"| node_views
node_companion_app -->|"updates state"| node_companion_state
node_companion_app -->|"uses client"| node_workspace_client
node_companion_app -->|"controls capture"| node_recall

click node_crm_ui "https://github.com/twentyhq/twenty/tree/main/packages/twenty-front/src"
click node_records "https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts"
click node_views "https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/internal/real-estate/src/views/buyer-pipeline.view.ts"
click node_workflows "https://github.com/twentyhq/twenty/tree/main/packages/twenty-server/src/modules/workflow"
click node_agents "https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/public/call-recorder/src/agents"
click node_server_api "https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts"
click node_applications "https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/application/application.service.ts"
click node_marketplace "https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-query.service.ts"
click node_sdk "https://github.com/twentyhq/twenty/blob/main/packages/twenty-sdk/src/sdk/define/objects/is-engine-derived-label-identifier.ts"
click node_scaffold "https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src/create-app.command.ts"
click node_published_app "https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps"
click node_real_estate "https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/internal/real-estate/src/objects/property.object.ts"
click node_companion_app "https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/RecordingController.ts"
click node_companion_state "https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/shared/types/CompanionState.ts"
click node_workspace_client "https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/TwentyClient.ts"
click node_recorder "https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/RecordingController.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_crm_ui,node_records,node_views,node_workflows,node_agents,node_user toneBlue
class node_server_api,node_applications,node_marketplace toneAmber
class node_sdk,node_scaffold,node_published_app,node_real_estate toneMint
class node_companion_app,node_companion_state,node_workspace_client,node_recorder toneRose
class node_recall toneIndigo
```

## Components

### CRM experience

- [CRM interface](https://github.com/twentyhq/twenty/tree/main/packages/twenty-front/src): `packages/twenty-front/src`
- [CRM records](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts): `packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts`
- [Views](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/internal/real-estate/src/views/buyer-pipeline.view.ts): `packages/twenty-apps/internal/real-estate/src/views/buyer-pipeline.view.ts`
- [Workflows](https://github.com/twentyhq/twenty/tree/main/packages/twenty-server/src/modules/workflow): `packages/twenty-server/src/modules/workflow`
- [AI agents](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps/public/call-recorder/src/agents): `packages/twenty-apps/public/call-recorder/src/agents`

### CRM services

- [Server API](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts): `packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts`
- [Application service](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/application/application.service.ts): `packages/twenty-server/src/engine/core-modules/application/application.service.ts`
- [App marketplace](https://github.com/twentyhq/twenty/blob/main/packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-query.service.ts): `packages/twenty-server/src/engine/core-modules/application/application-marketplace/marketplace-query.service.ts`

### App platform

- [App SDK](https://github.com/twentyhq/twenty/blob/main/packages/twenty-sdk/src/sdk/define/objects/is-engine-derived-label-identifier.ts): `packages/twenty-sdk/src/sdk/define/objects/is-engine-derived-label-identifier.ts`
- [App scaffolding](https://github.com/twentyhq/twenty/blob/main/packages/create-twenty-app/src/create-app.command.ts): `packages/create-twenty-app/src/create-app.command.ts`
- [Workspace apps](https://github.com/twentyhq/twenty/tree/main/packages/twenty-apps): `packages/twenty-apps`
- [Real estate CRM](https://github.com/twentyhq/twenty/blob/main/packages/twenty-apps/internal/real-estate/src/objects/property.object.ts): `packages/twenty-apps/internal/real-estate/src/objects/property.object.ts`

### Desktop companion

- [Desktop companion](https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/RecordingController.ts): `packages/twenty-companion/src/main/services/RecordingController.ts`
- [Meeting state](https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/shared/types/CompanionState.ts): `packages/twenty-companion/src/shared/types/CompanionState.ts`
- [Workspace client](https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/TwentyClient.ts): `packages/twenty-companion/src/main/services/TwentyClient.ts`
- [Recording capture](https://github.com/twentyhq/twenty/blob/main/packages/twenty-companion/src/main/services/RecordingController.ts): `packages/twenty-companion/src/main/services/RecordingController.ts`

### Other components

- **CRM user**
- **Recall desktop SDK**

## Connections

- CRM user → CRM interface: uses (evidence: `README.md`)
- CRM interface → Server API: accesses CRM
- Server API → CRM records: queries records (evidence: `packages/twenty-server/src/engine/api/common/common-query-runners/common-base-query-runner.service.ts`)
- CRM user → Views: works in views (evidence: `README.md`)
- CRM user → Workflows: uses workflows (evidence: `README.md`)
- CRM user → AI agents: uses agents (evidence: `README.md`)
- App scaffolding → Workspace apps: creates app (evidence: `README.md`)
- App SDK → Workspace apps: defines primitives (evidence: `README.md`)
- Workspace apps → Application service: publishes to workspace (evidence: `README.md`)
- Application service → App marketplace: offers apps
- Real estate CRM → Views: defines pipeline (evidence: `packages/twenty-apps/internal/real-estate/src/views/buyer-pipeline.view.ts`)
- Desktop companion → Meeting state: updates state (evidence: `packages/twenty-companion/src/main/services/RecordingController.ts`)
- Desktop companion → Workspace client: uses client (evidence: `packages/twenty-companion/src/main/services/RecordingController.ts`)
- Desktop companion → Recall desktop SDK: controls capture (evidence: `packages/twenty-companion/src/main/services/RecordingController.ts`)