Doramagic.ai
Chinese

Doramagic Project Pack · Human Manual

twenty

The open alternative to Salesforce, designed for AI.

Overview

Related topics: Src

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Production-Style Integrations

Continue reading this section for the full explanation and source context.

Section Development Loop

Continue reading this section for the full explanation and source context.

Related Pages

Related topics: Src

Overview

What Is Twenty

Twenty is a modern, open-source Customer Relationship Management (CRM) platform distributed as a TypeScript monorepo. The repository bundles the CRM server, a React-based front end, an app development platform, a UI component library, a typed client SDK, and the marketing and documentation sites under a single workspace managed by Nx (README.md).

The top-level README positions Twenty as "The #1 Open-Source CRM" and highlights four flagship capabilities: CRM data version control, customizable layouts, AI agents and chats, and a primitives-based extensibility model. The server stack is TypeScript, Nx, NestJS, BullMQ, PostgreSQL, and Redis, while the client is built with React. The project also endorses Greptile for code review, Sentry for bug capture, and Crowdin for translations (README.md).

Monorepo Package Layout

The packages/ directory holds the libraries and applications that compose the workspace. Each package has its own package.json declaring subpath exports and dependencies, which the table below summarizes using only information sourced from the provided files.

PackageRoleNotable Details
twenty-sharedCross-package shared code: types, utilities, AI helpers, workflow primitives, Vite tooling, i18n, and testing harnesses.Exposes typed subpaths such as ai, application, logic-function, metadata, types, utils, vite, workflow, and workspace (packages/twenty-shared/package.json).
twenty-client-sdkTyped client for the Twenty GraphQL/REST API and metadata generation.Depends on @genql/runtime, graphql, lodash, and esbuild; ships dual ESM/CJS output with vite-plugin-dts (packages/twenty-client-sdk/package.json).
create-twenty-appScaffolding CLI for new Twenty apps.Wraps a local Twenty server in Docker, exposes yarn twenty dev, remote:add, sync, build, and publish commands, and ships a troubleshooting guide (packages/create-twenty-app/README.md).
twenty-uiComponent library and design system used inside Twenty.Built on SCSS Modules and Base UI; ships Storybook as living documentation; theme-constants is imported by ~943 files and must remain a drop-in replacement (packages/twenty-ui/README.md).
twenty-docsMintlify-powered documentation site.46 user-guide pages, 24 developer pages, and 25 UI pages; navigation is split between a base structure file and a Crowdin-pushed label template (packages/twenty-docs/README.md).
twenty-codex-pluginCodex plugin that teaches an AI agent how to build, deploy, and query Twenty apps.Bundles five skills, the public docs MCP server, and a setup-mcp.sh helper; licensed AGPL-3.0 (packages/twenty-codex-plugin/README.md, packages/twenty-codex-plugin/package.json).

The Apps Ecosystem

A central concept in Twenty is the App: a self-contained bundle of CRM entities that can be installed into a workspace. The Postcard example explicitly enumerates the full entity surface: application.config.ts for metadata and variables, custom objects with inline fields, standalone fields and relations (ONE_TO_MANY, MANY_TO_ONE), logic functions, front components, roles, views, navigation menu items, AI skills, agents, and page layouts (packages/twenty-apps/examples/postcard/README.md). The same shape is used by production apps under packages/twenty-apps/community/ and packages/twenty-apps/internal/.

Production-Style Integrations

The GitHub connector ingests pull requests, issues, contributors, and GitHub Projects v2 items. It exposes HTTP logic functions such as count-prs, fetch-prs, count-issues, fetch-issues, count-contributors, fetch-contributors, count-project-items, and fetch-project-items, plus a signed-webhook handler handle-github-webhook. Configuration is driven by the variables GITHUB_REPOS (required), GITHUB_PROJECTS (optional, accepting owner/number or full project URLs), and GITHUB_WEBHOOK_SECRET (optional). Seven front components surface the connector in the UI, including a Contributor Stats panel and two Top-20 dashboard widgets for PR authors and reviewers (packages/twenty-apps/community/github-connector/README.md).

The Fireflies internal app transcribes calls and links them to CalendarEvent records, storing a rich-text AI summary with bullet points, action items grouped by speaker, topics, and keywords, alongside a per-speaker quote breakdown. It also ships three workflow tools — Sync Fireflies Call for backfill and recovery, List Fireflies Calls By Participant as a workflow entry step, and an AI chat tool — turning logic functions into first-class workflow steps (packages/twenty-apps/internal/twenty-fireflies/README.md).

Development Loop

The create-twenty-app CLI provides the canonical edit/test loop. From an app directory, yarn twenty dev runs a local Twenty server, yarn twenty remote:add registers the local server as a sync target using an API key from Settings → Developers, and yarn twenty build and yarn twenty deploy produce installable artifacts. The CLI's troubleshooting section flags three recurring failures: a non-starting server usually means Docker is down, authentication failures mean remote:add must be re-run, and missing generated types indicate that yarn twenty dev is not running (packages/create-twenty-app/README.md).

AI-Assisted Authoring

The twenty-codex-plugin package wraps the same platform in an AI-agent-friendly form. It ships five skills — create-app, develop-app, manage-app, publish-app, and use-twenty-mcp — coordinated by an AGENTS.md operating manual and reference documents under references/. The plugin works in two layers: a bundled twenty-docs MCP server is available immediately for documentation search, while workspace MCP endpoints are deliberately left user-local and are configured with bash packages/twenty-codex-plugin/scripts/setup-mcp.sh myworkspace.twenty.com, which names the server after the workspace host (for example, twenty-myworkspace) (packages/twenty-codex-plugin/README.md). The package declares Node 24.5+ and Yarn 4.0.2+ engines and is published under AGPL-3.0 (packages/twenty-codex-plugin/package.json).

See Also

Source: https://github.com/twentyhq/twenty / Human Manual

Src

Related topics: Overview, Src

Section Related Pages

Continue reading this section for the full explanation and source context.

Related Pages

Related topics: Overview, Src

Src

1. Purpose and Scope

Within the Twenty monorepo, src/ is the canonical source-of-truth directory used by every first-class package and every Twenty app. It holds the handwritten TypeScript (and, where applicable, Bash) code that gets compiled, packaged, and shipped, as opposed to generated artefacts that live under dist/, build output, or the README/markdown that lives at the package root.

The directory is used in three distinct roles:

In short, anything you author as a contributor belongs under src/; anything that is the result of a build does not.

2. App `src/` Layout

The most prescriptive use of src/ is inside a Twenty app. The postcard example documents the standard subfolders, and the same skeleton is reused by the GitHub connector and the Fireflies apps.

Subfolder (under src/)Purpose
objects/Custom object definitions that the app installs into a workspace.
fields/Field definitions attached to standard or custom objects.
logic-functions/Serverless logic functions exposed as HTTP endpoints (e.g. POST /github/count-prs).
front-components/Sandboxed UI components rendered inside the Twenty front-end.
workflows/Workflow definitions, including the AI-call sync workflows used by Fireflies.
agents/AI agents with a system prompt, consumed by the workflow builder.
page-layouts/Custom record-page layouts that embed front-component widgets.

Sources: packages/twenty-apps/examples/postcard/README.md, packages/twenty-apps/community/github-connector/README.md, packages/twenty-apps/internal/twenty-fireflies/README.md.

The GitHub connector demonstrates the runtime shape of these folders: thirteen logic functions live under src/logic-functions/ and seven front components are declared under src/front-components/, one per user-facing surface (commands on objects, panels, dashboard widgets). Source: packages/twenty-apps/community/github-connector/README.md.

The Fireflies app illustrates that src/ also holds workflow tools — runtime helpers exposed in the workflow builder and in AI chat — alongside traditional workflows. These are declared as code in src/ rather than configured in the UI so that they can be version-controlled and reused across workspaces. Source: packages/twenty-apps/internal/twenty-fireflies/README.md.

A typical local development loop is to edit files under src/, then run yarn twenty dev (or yarn twenty remote:add followed by yarn twenty app:dev) to push the changes into a local Twenty server for inspection. Source: packages/twenty-apps/examples/postcard/README.md.

3. Library and Renderer `src/` Layout

Shared libraries use src/ as the input to their bundler; the public surface is then re-exported from dist/ and registered in typesVersions for subpath imports.

For twenty-shared, the package exposes thirteen subpath entries (ai, application, constants, database-events, i18n, logic-function, metadata, testing, translations, types, utils, vite, workflow, workspace). Each subpath maps to a sibling folder under src/ and is materialised into dist/<subpath>/index.d.ts for consumers. Source: packages/twenty-shared/package.json.

The twenty-client-sdk package follows the same pattern with four subpaths (core, metadata, rest, generate) and declares bundled runtime dependencies (graphql, genql, lodash, prettier) plus dev-time tooling (vite, vitest, vite-plugin-dts). Source: packages/twenty-client-sdk/package.json.

The twenty-ui package uses src/ to organise a theming system (src/theme/, src/theme-constants/), global styles (src/styles/), and a categorical component library split into display/, input/, layout/, navigation/, feedback/, and components/. The package uses the internal alias @ui/* so that files moved between twenty-ui and twenty-ui-deprecated diff cleanly. Source: packages/twenty-ui/README.md.

For twenty-front-component-renderer, src/ doubles as the place where Storybook stories live. The src/__stories__/ tree is grouped by HTML tag and category (for example html-tag/form/input/), with each scenario shipping as a *.front-component.tsx bundle plus a paired *.stories.tsx Storybook file. Shared plumbing — utility helpers, fixture loaders, render harnesses — lives in src/__stories__/shared/test-utils/. Source: packages/twenty-front-component-renderer/src/__stories__/shared/test-utils/README.md.

4. Script and Tooling `src/` Equivalents

Not every package keeps its hand-written code strictly inside a directory named src/. The server package, for example, keeps its Bash tooling under packages/twenty-server/scripts/ssl-generation/ and provides a self-contained script.sh that generates a private key, a root certificate authority, and a domain certificate, then (on macOS) registers the root with the keychain. Source: packages/twenty-server/scripts/ssl-generation/README.md.

The Codex plugin uses scripts/ for its one-shot helpers — notably setup-mcp.sh (which configures a workspace MCP server) and validate.js (a Node script that lints the plugin manifest) — and skills/ for the actual Codex skill bundles that drive app creation, development, publishing, and querying. Source: packages/twenty-codex-plugin/package.json and packages/twenty-codex-plugin/README.md.

5. Common Conventions

Across all roles, the following conventions hold:

  • Anything meant to be published ends up under a path declared in the package's files field; for the Codex plugin this includes scripts/, skills/, templates/, and references/ but never build output. Source: packages/twenty-codex-plugin/package.json.
  • Anything that is generated (compiled JS, .d.ts, sourcemaps) lives under dist/ and is the only directory re-exported through typesVersions. Source: packages/twenty-shared/package.json.
  • App src/ folders are namespace-aligned with the app's HTTP route names; the GitHub connector exposes /github/* paths for PR/issue/contributor/project commands and /contributors/* plus /pull-request-reviews/* for derived data, with each route implemented by a single file under src/logic-functions/. Source: packages/twenty-apps/community/github-connector/README.md.
flowchart LR
  subgraph Authoring["Author-time (src/)"]
    A1["App: objects/ fields/ logic-functions/ front-components/ workflows/ agents/ page-layouts/"]
    A2["Library: src/&lt;subpath&gt;/ for ai, metadata, workflow, ..."]
    A3["Renderer: src/__stories__/ + src/__stories__/shared/test-utils/"]
    A4["Tooling: scripts/ or skills/"]
  end
  subgraph Build["Build-time"]
    B1["tsc / vite / esbuild"]
    B2["Storybook static export"]
    B3["Bash tooling (no build)"]
  end
  subgraph Ship["Ship-time (dist/ or files[])"]
    C1["dist/&lt;subpath&gt;/index.d.ts"]
    C2["npm package tarball"]
    C3["Codex marketplace entry"]
  end
  A1 --> B1 --> C2
  A2 --> B1 --> C1
  A3 --> B2 --> C2
  A4 --> B3 --> C3

See Also

Sources: packages/twenty-apps/examples/postcard/README.md, packages/twenty-apps/community/github-connector/README.md, packages/twenty-apps/internal/twenty-fireflies/README.md.

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

high Installation risk requires verification

May increase setup, validation, or first-run risk for the user.

high Security or permission risk requires verification

Developers may expose sensitive permissions or credentials: Hard Delete Option in Command Menu

high Security or permission risk requires verification

May increase setup, validation, or first-run risk for the user.

medium Installation risk requires verification

Upgrade or migration may change expected behavior: twenty/v2.12.0

Doramagic Pitfall Log

Found 23 structured pitfall item(s), including 3 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

  • Severity: high
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/twentyhq/twenty/issues/21969

2. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Developers should check this security_permissions risk before relying on the project: Hard Delete Option in Command Menu
  • User impact: Developers may expose sensitive permissions or credentials: Hard Delete Option in Command Menu
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Hard Delete Option in Command Menu. Context: Source discussion did not expose a precise runtime context.
  • Evidence: failure_mode_cluster:github_issue | https://github.com/twentyhq/twenty/issues/21273

3. Security or permission risk: Security or permission risk requires verification

  • Severity: high
  • Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/twentyhq/twenty/issues/21273

4. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: twenty/v2.12.0
  • User impact: Upgrade or migration may change expected behavior: twenty/v2.12.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: twenty/v2.12.0. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.12.0

5. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v2.7.0
  • User impact: Upgrade or migration may change expected behavior: v2.7.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v2.7.0. Context: Observed when using docker
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.7.0

6. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v2.8.0
  • User impact: Upgrade or migration may change expected behavior: v2.8.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v2.8.0. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.8.0

7. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v2.9.0
  • User impact: Upgrade or migration may change expected behavior: v2.9.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v2.9.0. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/v2.9.0

8. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
  • User impact: May increase setup, validation, or first-run risk for the user.
  • Recommended check: Reproduce the official install and quickstart path in an isolated environment.
  • Evidence: community_evidence:github | https://github.com/twentyhq/twenty/issues/19676

9. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2
  • User impact: Developers may misconfigure credentials, environment, or host setup: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: QuotaExceededError blocks login after upgrading to 2.12.x / 2.13.2. Context: Observed when using docker
  • Evidence: failure_mode_cluster:github_issue | https://github.com/twentyhq/twenty/issues/21581

10. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: twenty/v2.10
  • User impact: Upgrade or migration may change expected behavior: twenty/v2.10
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: twenty/v2.10. Context: Observed during version upgrade or migration.
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.10.0

11. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: twenty/v2.13.0
  • User impact: Upgrade or migration may change expected behavior: twenty/v2.13.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: twenty/v2.13.0. Context: Observed when using node
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.13.0

12. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: twenty/v2.14.0
  • User impact: Upgrade or migration may change expected behavior: twenty/v2.14.0
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: twenty/v2.14.0. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/twentyhq/twenty/releases/tag/twenty/v2.14.0

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 12

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using twenty with real data or production workflows.

Source: Project Pack community evidence and pitfall evidence