{"owner":"twentyhq","repo":"twenty","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"skills":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nTwenty is an open-source CRM built with modern technologies in a monorepo structure. The codebase is organized as an Nx workspace with multiple packages.\n\n## Key Commands\n\n### Development\n```bash\n# Start development environment (frontend + backend + worker)\nyarn start\n\n# Individual package development\nnpx nx start twenty-front     # Start frontend dev server\nnpx nx start twenty-server    # Start backend server\nnpx nx run twenty-server:worker  # Start background worker\n```\n\n### Testing\n```bash\n# Preferred: run a single test file (fast)\nnpx jest path/to/test.test.ts --config=packages/PROJECT/jest.config.mjs\n\n# Run all tests for a package\nnpx nx test twenty-front      # Frontend unit tests\nnpx nx test twenty-server     # Backend unit tests\nnpx nx run twenty-server:test:integration:with-db-reset  # Integration tests with DB reset\n# To run an individual test or a pattern of tests, use the following command:\ncd packages/{workspace} && npx jest \"pattern or filename\"\n\n# Storybook\nnpx nx storybook:build twenty-front\nnpx nx storybook:test twenty-front\n\n# When testing the UI end to end, click on \"Continue with Email\" and use the prefilled credentials.\n```\n\n### Code Quality\n```bash\n# Linting (diff with main - fastest, always prefer this)\nnpx nx lint:diff-with-main twenty-front\nnpx nx lint:diff-with-main twenty-server\nnpx nx lint:diff-with-main twenty-front --configuration=fix  # Auto-fix\n\n# Linting (full project - slower, use only when needed)\nnpx nx lint twenty-front\nnpx nx lint twenty-server\n\n# Type checking\nnpx nx typecheck twenty-front\nnpx nx typecheck twenty-server\n\n# Format code\nnpx nx fmt twenty-front\nnpx nx fmt twenty-server\n```\n\n### Build\n```bash\n# Build packages (twenty-shared must be built first)\nnpx nx build twenty-shared\nnpx nx build twenty-front\nnpx nx build twenty-server\n```\n\n### Database Operations\n```bash\n# Database management\nnpx nx database:reset twenty-server         # Reset database\nnpx nx run twenty-server:database:init:prod # Initialize database\nnpx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)\n\n# Generate an instance command (fast or slow)\nnpx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>\n```\n\n### Database Inspection (Postgres MCP)\n\nA read-only Postgres MCP server is configured in `.mcp.json`. Use it to:\n- Inspect workspace data, metadata, and object definitions while developing\n- Verify migration results (columns, types, constraints) after running migrations\n- Explore the multi-tenant schema structure (core, metadata, workspace-specific schemas)\n- Debug issues by querying raw data to confirm whether a bug is frontend, backend, or data-level\n- Inspect metadata tables to debug GraphQL schema generation issues\n\nThis server is read-only — for write operations (reset, migrations, sync), use the CLI commands above.\n\n### GraphQL\n```bash\n# Generate GraphQL types (run after schema changes)\nnpx nx run twenty-front:graphql:generate\nnpx nx run twenty-front:graphql:generate --configuration=metadata\n```\n\n## Architecture Overview\n\n### Tech Stack\n- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite\n- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)\n- **Monorepo**: Nx workspace managed with Yarn 4\n\n### Package Structure\n```\npackages/\n├── twenty-front/          # React frontend application\n├── twenty-server/         # NestJS backend API\n├── twenty-ui/             # Shared UI components library\n├── twenty-shared/         # Common types and utilities\n├── twenty-emails/         # Email templates with React Email\n├── twenty-website/    # Next.js marketing website\n├── twenty-docs/           # Documentation website\n├── twenty-zapier/         # Zapier integration\n└── twenty-e2e-testing/    # Playwright E2E tests\n```\n\n### Key Development Principles\n- **Functional components only** (no class components)\n- **Named exports only** (no default exports)\n- **Types over interfaces** (except when extending third-party interfaces)\n- **String literals over enums** (except for GraphQL enums)\n- **No 'any' type allowed** — strict TypeScript enforced\n- **Event handlers preferred over useEffect** for state updates\n- **Props down, events up** — unidirectional data flow\n- **Composition over inheritance**\n- **No abbreviations** in variable names (`user` not `u`, `fieldMetadata` not `fm`)\n\n### Naming Conventions\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE\n- **Types/Classes**: PascalCase (suffix component props with `Props`, e.g. `ButtonProps`)\n- **Files/directories**: kebab-case with descriptive suffixes (`.component.tsx`, `.service.ts`, `.entity.ts`, `.dto.ts`, `.module.ts`)\n- **TypeScript generics**: descriptive names (`TData` not `T`)\n\n### File Structure\n- Components under 300 lines, services under 500 lines\n- Components in their own directories with tests and stories\n- Use `index.ts` barrel exports for clean imports\n- Import order: external libraries first, then internal (`@/`), then relative\n\n### Comments\n- Use short-form comments (`//`), not JSDoc blocks\n- Explain WHY (business logic), not WHAT\n- Do not comment obvious code\n- Multi-line comments use multiple `//` lines, not `/** */`\n\n### State Management\n- **Jotai** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections\n- Component-specific state with React hooks (`useState`, `useReducer` for complex logic)\n- GraphQL cache managed by Apollo Client\n- Use functional state updates: `setState(prev => prev + 1)`\n\n### Backend Architecture\n- **NestJS modules** for feature organization\n- **TypeORM** for database ORM with PostgreSQL\n- **GraphQL** API with code-first approach\n- **Redis** for caching and session management\n- **BullMQ** for background job processing\n\n### Database & Upgrade Commands\n- **PostgreSQL** as primary database\n- **Redis** for caching and sessions\n- **ClickHouse** for analytics (when enabled)\n- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)\n- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills\n- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades\n- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery\n- Include both `up` and `down` logic in instance commands\n- Never delete or rewrite committed instance command `up`/`down` logic\n- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation\n\n### Utility Helpers\nUse existing helpers from `twenty-shared` instead of manual type guards:\n- `isDefined()`, `isNonEmptyString()`, `isNonEmptyArray()`\n\n## Development Workflow\n\nIMPORTANT: Use Context7 for code generation, setup or configuration steps, or library/API documentation. Automatically use the Context7 MCP tools to resolve library IDs and get library docs without waiting for explicit requests.\n\n### Before Making Changes\n1. Always run linting (`lint:diff-with-main`) and type checking after code changes\n2. Test changes with relevant test suites (prefer single-file test runs)\n3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)\n4. Check that GraphQL schema changes are backward compatible\n5. Run `graphql:generate` after any GraphQL schema changes\n\n### Code Style Notes\n- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)\n- Follow **Nx** workspace conventions for imports\n- Use **Lingui** for internationalization\n- Apply security first, then formatting (sanitize before format)\n\n### Testing Strategy\n- **Test behavior, not implementation** — focus on user perspective\n- **Test pyramid**: 70% unit, 20% integration, 10% E2E\n- Query by user-visible elements (text, roles, labels) over test IDs\n- Use `@testing-library/user-event` for realistic interactions\n- Descriptive test names: \"should [behavior] when [condition]\"\n- Clear mocks between tests with `jest.clearAllMocks()`\n\n## Dev Environment Setup\n\nAll dev environments (Claude Code web, Cursor, local) use one script:\n\n```bash\nbash packages/twenty-utils/setup-dev-env.sh\n```\n\nThis handles everything: starts Postgres + Redis (auto-detects local services vs Docker), creates databases, copies `.env` files, and initializes the database schema (runs migrations) on a fresh database. Idempotent — safe to run multiple times.\n\n- `--docker` — force Docker mode (uses `packages/twenty-docker/docker-compose.dev.yml`)\n- `--down` — stop services\n- `--reset` — wipe data and restart fresh\n- **Skip the setup script** for tasks that only read code — architecture questions, code review, documentation, etc.\n\n**Note:** CI workflows (GitHub Actions) manage services via Actions service containers and run setup steps individually — they don't use this script.\n\n## Important Files\n- `nx.json` - Nx workspace configuration with task definitions\n- `tsconfig.base.json` - Base TypeScript configuration\n- `package.json` - Root package with workspace definitions\n- `.cursor/rules/` - Detailed development guidelines and best practices\n"},"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nTwenty is an open-source CRM built with modern technologies in a monorepo structure. The codebase is organized as an Nx workspace with multiple packages.\n\n## Key Commands\n\n### Development\n```bash\n# Start development environment (frontend + backend + worker)\nyarn start\n\n# Individual package development\nnpx nx start twenty-front     # Start frontend dev server\nnpx nx start twenty-server    # Start backend server\nnpx nx run twenty-server:worker  # Start background worker\n```\n\n### Testing\n```bash\n# Preferred: run a single test file (fast)\nnpx jest path/to/test.test.ts --config=packages/PROJECT/jest.config.mjs\n\n# Run all tests for a package\nnpx nx test twenty-front      # Frontend unit tests\nnpx nx test twenty-server     # Backend unit tests\nnpx nx run twenty-server:test:integration:with-db-reset  # Integration tests with DB reset\n# To run an individual test or a pattern of tests, use the following command:\ncd packages/{workspace} && npx jest \"pattern or filename\"\n\n# Storybook\nnpx nx storybook:build twenty-front\nnpx nx storybook:test twenty-front\n\n# When testing the UI end to end, click on \"Continue with Email\" and use the prefilled credentials.\n```\n\n### Code Quality\n```bash\n# Linting (diff with main - fastest, always prefer this)\nnpx nx lint:diff-with-main twenty-front\nnpx nx lint:diff-with-main twenty-server\nnpx nx lint:diff-with-main twenty-front --configuration=fix  # Auto-fix\n\n# Linting (full project - slower, use only when needed)\nnpx nx lint twenty-front\nnpx nx lint twenty-server\n\n# Type checking\nnpx nx typecheck twenty-front\nnpx nx typecheck twenty-server\n\n# Format code\nnpx nx fmt twenty-front\nnpx nx fmt twenty-server\n```\n\n### Build\n```bash\n# Build packages (twenty-shared must be built first)\nnpx nx build twenty-shared\nnpx nx build twenty-front\nnpx nx build twenty-server\n```\n\n### Database Operations\n```bash\n# Database management\nnpx nx database:reset twenty-server         # Reset database\nnpx nx run twenty-server:database:init:prod # Initialize database\nnpx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)\n\n# Generate an instance command (fast or slow)\nnpx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>\n```\n\n### Database Inspection (Postgres MCP)\n\nA read-only Postgres MCP server is configured in `.mcp.json`. Use it to:\n- Inspect workspace data, metadata, and object definitions while developing\n- Verify migration results (columns, types, constraints) after running migrations\n- Explore the multi-tenant schema structure (core, metadata, workspace-specific schemas)\n- Debug issues by querying raw data to confirm whether a bug is frontend, backend, or data-level\n- Inspect metadata tables to debug GraphQL schema generation issues\n\nThis server is read-only — for write operations (reset, migrations, sync), use the CLI commands above.\n\n### GraphQL\n```bash\n# Generate GraphQL types (run after schema changes)\nnpx nx run twenty-front:graphql:generate\nnpx nx run twenty-front:graphql:generate --configuration=metadata\n```\n\n## Architecture Overview\n\n### Tech Stack\n- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite\n- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)\n- **Monorepo**: Nx workspace managed with Yarn 4\n\n### Package Structure\n```\npackages/\n├── twenty-front/          # React frontend application\n├── twenty-server/         # NestJS backend API\n├── twenty-ui/             # Shared UI components library\n├── twenty-shared/         # Common types and utilities\n├── twenty-emails/         # Email templates with React Email\n├── twenty-website/    # Next.js marketing website\n├── twenty-docs/           # Documentation website\n├── twenty-zapier/         # Zapier integration\n└── twenty-e2e-testing/    # Playwright E2E tests\n```\n\n### Key Development Principles\n- **Functional components only** (no class components)\n- **Named exports only** (no default exports)\n- **Types over interfaces** (except when extending third-party interfaces)\n- **String literals over enums** (except for GraphQL enums)\n- **No 'any' type allowed** — strict TypeScript enforced\n- **Event handlers preferred over useEffect** for state updates\n- **Props down, events up** — unidirectional data flow\n- **Composition over inheritance**\n- **No abbreviations** in variable names (`user` not `u`, `fieldMetadata` not `fm`)\n\n### Naming Conventions\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE\n- **Types/Classes**: PascalCase (suffix component props with `Props`, e.g. `ButtonProps`)\n- **Files/directories**: kebab-case with descriptive suffixes (`.component.tsx`, `.service.ts`, `.entity.ts`, `.dto.ts`, `.module.ts`)\n- **TypeScript generics**: descriptive names (`TData` not `T`)\n\n### File Structure\n- Components under 300 lines, services under 500 lines\n- Components in their own directories with tests and stories\n- Use `index.ts` barrel exports for clean imports\n- Import order: external libraries first, then internal (`@/`), then relative\n\n### Comments\n- Use short-form comments (`//`), not JSDoc blocks\n- Explain WHY (business logic), not WHAT\n- Do not comment obvious code\n- Multi-line comments use multiple `//` lines, not `/** */`\n\n### State Management\n- **Jotai** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections\n- Component-specific state with React hooks (`useState`, `useReducer` for complex logic)\n- GraphQL cache managed by Apollo Client\n- Use functional state updates: `setState(prev => prev + 1)`\n\n### Backend Architecture\n- **NestJS modules** for feature organization\n- **TypeORM** for database ORM with PostgreSQL\n- **GraphQL** API with code-first approach\n- **Redis** for caching and session management\n- **BullMQ** for background job processing\n\n### Database & Upgrade Commands\n- **PostgreSQL** as primary database\n- **Redis** for caching and sessions\n- **ClickHouse** for analytics (when enabled)\n- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)\n- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills\n- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades\n- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery\n- Include both `up` and `down` logic in instance commands\n- Never delete or rewrite committed instance command `up`/`down` logic\n- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation\n\n### Utility Helpers\nUse existing helpers from `twenty-shared` instead of manual type guards:\n- `isDefined()`, `isNonEmptyString()`, `isNonEmptyArray()`\n\n## Development Workflow\n\nIMPORTANT: Use Context7 for code generation, setup or configuration steps, or library/API documentation. Automatically use the Context7 MCP tools to resolve library IDs and get library docs without waiting for explicit requests.\n\n### Before Making Changes\n1. Always run linting (`lint:diff-with-main`) and type checking after code changes\n2. Test changes with relevant test suites (prefer single-file test runs)\n3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)\n4. Check that GraphQL schema changes are backward compatible\n5. Run `graphql:generate` after any GraphQL schema changes\n\n### Code Style Notes\n- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)\n- Follow **Nx** workspace conventions for imports\n- Use **Lingui** for internationalization\n- Apply security first, then formatting (sanitize before format)\n\n### Testing Strategy\n- **Test behavior, not implementation** — focus on user perspective\n- **Test pyramid**: 70% unit, 20% integration, 10% E2E\n- Query by user-visible elements (text, roles, labels) over test IDs\n- Use `@testing-library/user-event` for realistic interactions\n- Descriptive test names: \"should [behavior] when [condition]\"\n- Clear mocks between tests with `jest.clearAllMocks()`\n\n## Dev Environment Setup\n\nAll dev environments (Claude Code web, Cursor, local) use one script:\n\n```bash\nbash packages/twenty-utils/setup-dev-env.sh\n```\n\nThis handles everything: starts Postgres + Redis (auto-detects local services vs Docker), creates databases, copies `.env` files, and initializes the database schema (runs migrations) on a fresh database. Idempotent — safe to run multiple times.\n\n- `--docker` — force Docker mode (uses `packages/twenty-docker/docker-compose.dev.yml`)\n- `--down` — stop services\n- `--reset` — wipe data and restart fresh\n- **Skip the setup script** for tasks that only read code — architecture questions, code review, documentation, etc.\n\n**Note:** CI workflows (GitHub Actions) manage services via Actions service containers and run setup steps individually — they don't use this script.\n\n## Important Files\n- `nx.json` - Nx workspace configuration with task definitions\n- `tsconfig.base.json` - Base TypeScript configuration\n- `package.json` - Root package with workspace definitions\n- `.cursor/rules/` - Detailed development guidelines and best practices\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Project Overview\n\nTwenty is an open-source CRM built with modern technologies in a monorepo structure. The codebase is organized as an Nx workspace with multiple packages.\n\n## Key Commands\n\n### Development\n```bash\n# Start development environment (frontend + backend + worker)\nyarn start\n\n# Individual package development\nnpx nx start twenty-front     # Start frontend dev server\nnpx nx start twenty-server    # Start backend server\nnpx nx run twenty-server:worker  # Start background worker\n```\n\n### Testing\n```bash\n# Preferred: run a single test file (fast)\nnpx jest path/to/test.test.ts --config=packages/PROJECT/jest.config.mjs\n\n# Run all tests for a package\nnpx nx test twenty-front      # Frontend unit tests\nnpx nx test twenty-server     # Backend unit tests\nnpx nx run twenty-server:test:integration:with-db-reset  # Integration tests with DB reset\n# To run an individual test or a pattern of tests, use the following command:\ncd packages/{workspace} && npx jest \"pattern or filename\"\n\n# Storybook\nnpx nx storybook:build twenty-front\nnpx nx storybook:test twenty-front\n\n# When testing the UI end to end, click on \"Continue with Email\" and use the prefilled credentials.\n```\n\n### Code Quality\n```bash\n# Linting (diff with main - fastest, always prefer this)\nnpx nx lint:diff-with-main twenty-front\nnpx nx lint:diff-with-main twenty-server\nnpx nx lint:diff-with-main twenty-front --configuration=fix  # Auto-fix\n\n# Linting (full project - slower, use only when needed)\nnpx nx lint twenty-front\nnpx nx lint twenty-server\n\n# Type checking\nnpx nx typecheck twenty-front\nnpx nx typecheck twenty-server\n\n# Format code\nnpx nx fmt twenty-front\nnpx nx fmt twenty-server\n```\n\n### Build\n```bash\n# Build packages (twenty-shared must be built first)\nnpx nx build twenty-shared\nnpx nx build twenty-front\nnpx nx build twenty-server\n```\n\n### Database Operations\n```bash\n# Database management\nnpx nx database:reset twenty-server         # Reset database\nnpx nx run twenty-server:database:init:prod # Initialize database\nnpx nx run twenty-server:database:migrate:prod # Run instance commands (fast only)\n\n# Generate an instance command (fast or slow)\nnpx nx run twenty-server:database:migrate:generate --name <name> --type <fast|slow>\n```\n\n### Database Inspection (Postgres MCP)\n\nA read-only Postgres MCP server is configured in `.mcp.json`. Use it to:\n- Inspect workspace data, metadata, and object definitions while developing\n- Verify migration results (columns, types, constraints) after running migrations\n- Explore the multi-tenant schema structure (core, metadata, workspace-specific schemas)\n- Debug issues by querying raw data to confirm whether a bug is frontend, backend, or data-level\n- Inspect metadata tables to debug GraphQL schema generation issues\n\nThis server is read-only — for write operations (reset, migrations, sync), use the CLI commands above.\n\n### GraphQL\n```bash\n# Generate GraphQL types (run after schema changes)\nnpx nx run twenty-front:graphql:generate\nnpx nx run twenty-front:graphql:generate --configuration=metadata\n```\n\n## Architecture Overview\n\n### Tech Stack\n- **Frontend**: React 18, TypeScript, Jotai (state management), Linaria (styling), Vite\n- **Backend**: NestJS, TypeORM, PostgreSQL, Redis, GraphQL (with GraphQL Yoga)\n- **Monorepo**: Nx workspace managed with Yarn 4\n\n### Package Structure\n```\npackages/\n├── twenty-front/          # React frontend application\n├── twenty-server/         # NestJS backend API\n├── twenty-ui/             # Shared UI components library\n├── twenty-shared/         # Common types and utilities\n├── twenty-emails/         # Email templates with React Email\n├── twenty-website/    # Next.js marketing website\n├── twenty-docs/           # Documentation website\n├── twenty-zapier/         # Zapier integration\n└── twenty-e2e-testing/    # Playwright E2E tests\n```\n\n### Key Development Principles\n- **Functional components only** (no class components)\n- **Named exports only** (no default exports)\n- **Types over interfaces** (except when extending third-party interfaces)\n- **String literals over enums** (except for GraphQL enums)\n- **No 'any' type allowed** — strict TypeScript enforced\n- **Event handlers preferred over useEffect** for state updates\n- **Props down, events up** — unidirectional data flow\n- **Composition over inheritance**\n- **No abbreviations** in variable names (`user` not `u`, `fieldMetadata` not `fm`)\n\n### Naming Conventions\n- **Variables/functions**: camelCase\n- **Constants**: SCREAMING_SNAKE_CASE\n- **Types/Classes**: PascalCase (suffix component props with `Props`, e.g. `ButtonProps`)\n- **Files/directories**: kebab-case with descriptive suffixes (`.component.tsx`, `.service.ts`, `.entity.ts`, `.dto.ts`, `.module.ts`)\n- **TypeScript generics**: descriptive names (`TData` not `T`)\n\n### File Structure\n- Components under 300 lines, services under 500 lines\n- Components in their own directories with tests and stories\n- Use `index.ts` barrel exports for clean imports\n- Import order: external libraries first, then internal (`@/`), then relative\n\n### Comments\n- Use short-form comments (`//`), not JSDoc blocks\n- Explain WHY (business logic), not WHAT\n- Do not comment obvious code\n- Multi-line comments use multiple `//` lines, not `/** */`\n\n### State Management\n- **Jotai** for global state: atoms for primitive state, selectors for derived state, atom families for dynamic collections\n- Component-specific state with React hooks (`useState`, `useReducer` for complex logic)\n- GraphQL cache managed by Apollo Client\n- Use functional state updates: `setState(prev => prev + 1)`\n\n### Backend Architecture\n- **NestJS modules** for feature organization\n- **TypeORM** for database ORM with PostgreSQL\n- **GraphQL** API with code-first approach\n- **Redis** for caching and session management\n- **BullMQ** for background job processing\n\n### Database & Upgrade Commands\n- **PostgreSQL** as primary database\n- **Redis** for caching and sessions\n- **ClickHouse** for analytics (when enabled)\n- When changing entity files, generate an **instance command** (`database:migrate:generate --name <name> --type <fast|slow>`)\n- **Fast** instance commands handle schema changes; **slow** ones add a `runDataMigration` step for data backfills\n- **Workspace commands** iterate over all active/suspended workspaces for per-workspace upgrades\n- Commands use `@RegisteredInstanceCommand` and `@RegisteredWorkspaceCommand` decorators for automatic discovery\n- Include both `up` and `down` logic in instance commands\n- Never delete or rewrite committed instance command `up`/`down` logic\n- See `packages/twenty-server/docs/UPGRADE_COMMANDS.md` for full documentation\n\n### Utility Helpers\nUse existing helpers from `twenty-shared` instead of manual type guards:\n- `isDefined()`, `isNonEmptyString()`, `isNonEmptyArray()`\n\n## Development Workflow\n\nIMPORTANT: Use Context7 for code generation, setup or configuration steps, or library/API documentation. Automatically use the Context7 MCP tools to resolve library IDs and get library docs without waiting for explicit requests.\n\n### Before Making Changes\n1. Always run linting (`lint:diff-with-main`) and type checking after code changes\n2. Test changes with relevant test suites (prefer single-file test runs)\n3. Ensure instance commands are generated for entity changes (`database:migrate:generate`)\n4. Check that GraphQL schema changes are backward compatible\n5. Run `graphql:generate` after any GraphQL schema changes\n\n### Code Style Notes\n- Use **Linaria** for styling with zero-runtime CSS-in-JS (styled-components pattern)\n- Follow **Nx** workspace conventions for imports\n- Use **Lingui** for internationalization\n- Apply security first, then formatting (sanitize before format)\n\n### Testing Strategy\n- **Test behavior, not implementation** — focus on user perspective\n- **Test pyramid**: 70% unit, 20% integration, 10% E2E\n- Query by user-visible elements (text, roles, labels) over test IDs\n- Use `@testing-library/user-event` for realistic interactions\n- Descriptive test names: \"should [behavior] when [condition]\"\n- Clear mocks between tests with `jest.clearAllMocks()`\n\n## Dev Environment Setup\n\nAll dev environments (Claude Code web, Cursor, local) use one script:\n\n```bash\nbash packages/twenty-utils/setup-dev-env.sh\n```\n\nThis handles everything: starts Postgres + Redis (auto-detects local services vs Docker), creates databases, copies `.env` files, and initializes the database schema (runs migrations) on a fresh database. Idempotent — safe to run multiple times.\n\n- `--docker` — force Docker mode (uses `packages/twenty-docker/docker-compose.dev.yml`)\n- `--down` — stop services\n- `--reset` — wipe data and restart fresh\n- **Skip the setup script** for tasks that only read code — architecture questions, code review, documentation, etc.\n\n**Note:** CI workflows (GitHub Actions) manage services via Actions service containers and run setup steps individually — they don't use this script.\n\n## Important Files\n- `nx.json` - Nx workspace configuration with task definitions\n- `tsconfig.base.json` - Base TypeScript configuration\n- `package.json` - Root package with workspace definitions\n- `.cursor/rules/` - Detailed development guidelines and best practices\n","category":"root","tokens":2328}]}