GraphQL API & Schema Builder

Relevant source files

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

• CLAUDE.md
• packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts
• packages/twenty-server/test/integration/graphql/codegen/index.ts
• packages/twenty-codex-plugin/AGENTS.md
• packages/twenty-shared/src/constants/DocumentationPaths.ts
• packages/twenty-front/src/locales/generated/en.ts

Twenty utilizes a code-first GraphQL API architecture powered by NestJS and GraphQL Yoga to provide a flexible and strongly-typed interface for CRM data management. The system is designed to handle multi-tenant requirements by dynamically generating schemas based on metadata and workspace-specific configurations.

The GraphQL infrastructure is a core component of the backend, allowing the frontend and external integrations to query complex relationship structures, perform bulk operations, and manage workspace metadata with strict type safety.

Sources: CLAUDE.md:104, CLAUDE.md:143

Core Architecture & Tech Stack

The backend architecture leverages NestJS modules to organize features, with TypeORM serving as the primary ORM for PostgreSQL interactions. GraphQL is implemented using a code-first approach, meaning the TypeScript classes and decorators define the schema structure.

Component Overview

Component	Technology	Role
Server Framework	NestJS	Module organization and dependency injection
API Layer	GraphQL Yoga	Execution engine for GraphQL queries and mutations
ORM	TypeORM	Mapping TypeScript entities to PostgreSQL tables
Cache	Redis	Caching and session management
State (Frontend)	Jotai & Apollo Client	Global state and GraphQL cache management

Sources: CLAUDE.md:103-107, CLAUDE.md:141-146

Data Flow Diagram

The following diagram illustrates the request flow from the client through the GraphQL layer to the data persistence layer.

A visual representation of the request lifecycle in the Twenty GraphQL ecosystem.
Sources: CLAUDE.md:104-107, CLAUDE.md:141-146

Schema Generation & Management

Twenty differentiates between several types of schemas to support its multi-tenant and metadata-driven nature. This includes "core" schemas for standard CRM data and "metadata" schemas for defining the structure of objects and fields themselves.

Introspection and Codegen

The project includes automated tools for schema introspection and test generation. The integration test suite uses introspection queries to discover the available types and fields in the workspace, automatically generating E2E tests for resolvers.

// Example Introspection for Test Generation
const fetchGraphQLSchema = async (): Promise<IntrospectionResponse> => {
  const headers = {
    Authorization: BEARER_TOKEN,
    'Content-Type': 'application/json',
  };
  const response = await fetch(GRAPHQL_URL, {
    method: 'POST',
    headers,
    body: JSON.stringify({ query: INTROSPECTION_QUERY }),
  });
  return response.json();
};

Sources: packages/twenty-server/test/integration/graphql/codegen/index.ts:18-32

Multi-Tenant Schema Structure

The system utilizes a multi-layered schema approach:

• Core Schema: Contains standard CRM objects (People, Companies, Opportunities).
• Metadata Schema: Used to debug and manage object definitions, migrations, and workspace-specific configurations.
• Workspace Schemas: Dynamic schemas generated per-tenant based on custom fields and objects.

Sources: CLAUDE.md:79-84

Development Workflow

When modifying the GraphQL API, developers must follow a specific lifecycle to ensure type consistency across the monorepo.

GraphQL CLI Commands

Twenty provides specific commands via Nx to synchronize the frontend with backend schema changes.

Command	Description
npx nx run twenty-front:graphql:generate	Generates frontend types from the core GraphQL schema
npx nx run twenty-front:graphql:generate --configuration=metadata	Generates types from the metadata schema

Sources: CLAUDE.md:88-91

Testing Strategy

The GraphQL layer is tested using a pyramid approach, with approximately 70% unit tests, 20% integration tests, and 10% E2E tests. Integration tests for resolvers are often auto-generated by inspecting the schema, ensuring that every object connection has a corresponding test that validates field selection and response shapes.

The automated workflow for ensuring GraphQL resolver integrity.
Sources: CLAUDE.md:121-125, packages/twenty-server/test/integration/graphql/codegen/index.ts:46-102

API Comparisons & Tooling

While GraphQL is the primary interface for the frontend, Twenty also provides REST and MCP (Model Context Protocol) alternatives for specific use cases.

Feature	GraphQL API	REST API	MCP Server
Primary Use	Frontend Application	Third-party Integrations	LLM Agents (Claude/Cursor)
Schema	Dynamic/Code-first	OpenAPI 3.1.1	Typed Tools
Auth	JWT / Bearer	Bearer Token	OAuth / API Key
Pagination	Cursor-based (Edges/Nodes)	Cursor-based	Tool-specific

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:13-100, packages/twenty-codex-plugin/AGENTS.md:21-25

Implementation Notes

• Backward Compatibility: Developers are required to ensure that any GraphQL schema changes are backward compatible to avoid breaking existing clients.
• Relay Patterns: The generated tests confirm the use of Relay-style pagination, looking for edges and node structures in connection types.

Sources: CLAUDE.md:118, packages/twenty-server/test/integration/graphql/codegen/index.ts:70-80

Conclusion

The GraphQL API and Schema Builder in Twenty provide a robust, type-safe backbone for the CRM. By combining a code-first approach with automated introspection and codegen tools, the system maintains a high degree of developer productivity and data integrity across a complex, multi-tenant environment.