Monorepo Structure

Ever Gauzy uses an NX-managed monorepo with Lerna for package management. The repository contains multiple applications, libraries, and plugins organized in a structured hierarchy.

Root Directory Layout

ever-gauzy/
├── .circleci/              # CircleCI CI/CD configuration
├── .deploy/                # Deployment configurations
│   ├── api/                # API Docker configs
│   ├── db/                 # Database init scripts
│   ├── desktop/            # Desktop app deployment
│   ├── desktop-timer/      # Desktop timer deployment
│   ├── jitsu/              # Jitsu data ingestion config
│   ├── k8s/                # Kubernetes manifests
│   ├── mcp/                # MCP server Docker config
│   ├── mcp-auth/           # MCP auth server Docker config
│   ├── redis/              # Redis configuration
│   ├── ssh/                # SSH key management
│   └── webapp/             # Web app deployment
├── .github/                # GitHub Actions workflows
├── .scripts/               # Build & configuration scripts
├── apps/                   # Application projects
├── packages/               # Library packages
├── docker-compose*.yml     # Docker Compose files
├── nx.json                 # NX workspace configuration
├── angular.json            # Angular workspace configuration
├── tsconfig.base.json      # Base TypeScript configuration
├── package.json            # Root package.json
├── lerna.json              # Lerna configuration
└── .env.sample             # Environment variable template

Applications (`apps/`)

Applications are deployable end-user products:

Application	Path	Type	Description
API	`apps/api`	NestJS	Main backend API server
Gauzy (Web UI)	`apps/gauzy`	Angular	Primary web interface
Desktop	`apps/desktop`	Electron	All-in-one desktop app (UI + API + Timer)
Desktop Timer	`apps/desktop-timer`	Electron	Standalone time & activity tracker
Server	`apps/server`	Electron	Desktop server app (embeds API)
API Server	`apps/api-server`	Electron	API-only desktop server
Server-API	`apps/server-api`	NestJS	Server-side API module
Server-UI	`apps/server-ui`	Angular	Server app UI
Desktop-UI	`apps/desktop-ui`	Angular	Desktop app UI
Gauzy-E2E	`apps/gauzy-e2e`	Cypress	End-to-end tests
MCP	`apps/mcp`	Node.js	Model Context Protocol server
MCP Auth	`apps/mcp-auth`	Node.js	MCP OAuth 2.0 server

Packages (`packages/`)

Packages are shared libraries consumed by applications:

Core Libraries

Package	Path	Purpose
@gauzy/core	`packages/core`	Core backend module — entities, services, controllers, guards
@gauzy/common	`packages/common`	Shared constants, enums, interfaces, and utilities
@gauzy/contracts	`packages/contracts`	TypeScript interfaces/types shared between frontend and backend
@gauzy/config	`packages/config`	Configuration management and environment loading

Authentication & Security

Package	Path	Purpose
@gauzy/auth	`packages/auth`	Authentication strategies (JWT, Social OAuth, Magic Login)

Database & ORM

Package	Path	Purpose
@gauzy/adapters	`packages/adapters`	Multi-ORM adapter layer for TypeORM and MikroORM

Desktop

Package	Path	Purpose
@gauzy/desktop-libs	`packages/desktop-libs`	Desktop app shared libraries
@gauzy/desktop-ui-lib	`packages/desktop-ui-lib`	Desktop app Angular UI components
@gauzy/desktop-window	`packages/desktop-window`	Electron window management

UI Libraries

Package	Path	Purpose
@gauzy/ui-config	`packages/ui-config`	UI configuration and feature flags
@gauzy/ui-core	`packages/ui-core`	Core Angular components, services, and pipes
@gauzy/ui-sdk	`packages/ui-sdk`	SDK for building UI extensions

Plugins

Package	Path	Purpose
@gauzy/plugin-changelog	`packages/plugins/plugin-changelog`	Changelog and audit trail
@gauzy/plugin-integration-ai	`packages/plugins/plugin-integration-ai`	Gauzy AI integration
@gauzy/plugin-integration-github	`packages/plugins/plugin-integration-github`	GitHub integration
@gauzy/plugin-integration-hubstaff	`packages/plugins/plugin-integration-hubstaff`	HubStaff integration
@gauzy/plugin-integration-jira	`packages/plugins/plugin-integration-jira`	Jira integration
@gauzy/plugin-integration-make	`packages/plugins/plugin-integration-make`	Make.com integration
@gauzy/plugin-integration-upwork	`packages/plugins/plugin-integration-upwork`	Upwork integration
@gauzy/plugin-integration-zapier	`packages/plugins/plugin-integration-zapier`	Zapier integration
@gauzy/plugin-integration-activepieces	`packages/plugins/plugin-integration-activepieces`	ActivePieces integration
@gauzy/plugin-jitsu-analytics	`packages/plugins/jitsu-analytics`	Jitsu analytics plugin
@gauzy/plugin-job-search	`packages/plugins/job-search`	Job board search integration
@gauzy/plugin-job-search-ui	`packages/plugins/job-search-ui`	Job search UI components
@gauzy/plugin-job-matching-ui	`packages/plugins/job-matching-ui`	Job matching UI components
@gauzy/plugin-job-proposal-ui	`packages/plugins/job-proposal-ui`	Job proposal UI components
@gauzy/plugin-knowledge-base	`packages/plugins/knowledge-base`	Knowledge base and help center
@gauzy/plugin-knowledge-base-ui	`packages/plugins/knowledge-base-ui`	Knowledge base UI
@gauzy/plugin-legal-ui	`packages/plugins/legal-ui`	Legal pages UI
@gauzy/plugin-onboarding-ui	`packages/plugins/onboarding-ui`	Onboarding flow UI
@gauzy/plugin-product-reviews	`packages/plugins/product-reviews`	Product reviews module
@gauzy/plugin-sentry	`packages/plugins/sentry`	Sentry error tracking

NX Workspace Configuration

`nx.json`

The NX configuration defines:

Task runners — local and cloud (NX Cloud) task execution
Cache targets — build, test, lint operations are cached
Task dependencies — build order between projects
Default options — output directories, test settings

Task Graph

NX manages the dependency graph between projects automatically:

Key NX Commands

# Run a target for a specific project
npx nx serve api
npx nx build gauzy

# Run affected targets (only changed projects)
npx nx affected --target=build
npx nx affected --target=test

# Visualize dependency graph
npx nx graph

# List all projects
npx nx show projects

# Run multiple targets
npx nx run-many --target=build --projects=api,gauzy

TypeScript Configuration

The monorepo uses a hierarchical TSConfig setup:

tsconfig.base.json          # Base compiler options (strict, ES2022, paths)
├── apps/api/tsconfig.json
├── apps/gauzy/tsconfig.json
├── packages/core/tsconfig.json
└── packages/*/tsconfig.json

Path aliases are defined in tsconfig.base.json:

{
  "compilerOptions": {
    "paths": {
      "@gauzy/core": ["packages/core/src/index.ts"],
      "@gauzy/common": ["packages/common/src/index.ts"],
      "@gauzy/contracts": ["packages/contracts/src/index.ts"],
      "@gauzy/config": ["packages/config/src/index.ts"],
      "@gauzy/auth": ["packages/auth/src/index.ts"],
      "@gauzy/adapters": ["packages/adapters/src/index.ts"],
      "@gauzy/ui-config": ["packages/ui-config/src/index.ts"],
      "@gauzy/ui-core/*": ["packages/ui-core/src/lib/*"]
    }
  }
}

Build System

Build Targets

Target	Description	Caching
`build`	Compile TypeScript / Angular	✅ NX cached
`serve`	Start dev server	❌ Not cached
`test`	Run unit tests	✅ NX cached
`lint`	Run ESLint	✅ NX cached
`e2e`	Run E2E tests	❌ Not cached

Build Order

NX automatically resolves build order via implicit and explicit dependencies. Key principles:

@gauzy/contracts builds first (no dependencies)
@gauzy/common builds next (depends on contracts)
@gauzy/config and @gauzy/auth build after common
@gauzy/core builds after all above
Applications (api, gauzy) build after their dependencies
Plugin packages build after core and relevant UI packages

Technology Stack — frameworks and libraries used
Backend Architecture — NestJS module structure
Frontend Architecture — Angular module structure
Development Guide — working with NX in development

Root Directory Layout​

Applications (apps/)​

Packages (packages/)​

Core Libraries​

Authentication & Security​

Database & ORM​

Desktop​

UI Libraries​

Plugins​

NX Workspace Configuration​

nx.json​

Task Graph​

Key NX Commands​

TypeScript Configuration​

Build System​

Build Targets​

Build Order​

Related Pages​