πŸ—οΈ Architecture

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:

ApplicationPathTypeDescription
APIapps/apiNestJSMain backend API server
Gauzy (Web UI)apps/gauzyAngularPrimary web interface
Desktopapps/desktopElectronAll-in-one desktop app (UI + API + Timer)
Desktop Timerapps/desktop-timerElectronStandalone time & activity tracker
Serverapps/serverElectronDesktop server app (embeds API)
API Serverapps/api-serverElectronAPI-only desktop server
Server-APIapps/server-apiNestJSServer-side API module
Server-UIapps/server-uiAngularServer app UI
Desktop-UIapps/desktop-uiAngularDesktop app UI
Gauzy-E2Eapps/gauzy-e2eCypressEnd-to-end tests
MCPapps/mcpNode.jsModel Context Protocol server
MCP Authapps/mcp-authNode.jsMCP OAuth 2.0 server

Packages (packages/)

Packages are shared libraries consumed by applications:

Core Libraries

PackagePathPurpose
@gauzy/corepackages/coreCore backend module β€” entities, services, controllers, guards
@gauzy/commonpackages/commonShared constants, enums, interfaces, and utilities
@gauzy/contractspackages/contractsTypeScript interfaces/types shared between frontend and backend
@gauzy/configpackages/configConfiguration management and environment loading

Authentication & Security

PackagePathPurpose
@gauzy/authpackages/authAuthentication strategies (JWT, Social OAuth, Magic Login)

Database & ORM

PackagePathPurpose
@gauzy/adapterspackages/adaptersMulti-ORM adapter layer for TypeORM and MikroORM

Desktop

PackagePathPurpose
@gauzy/desktop-libspackages/desktop-libsDesktop app shared libraries
@gauzy/desktop-ui-libpackages/desktop-ui-libDesktop app Angular UI components
@gauzy/desktop-windowpackages/desktop-windowElectron window management

UI Libraries

PackagePathPurpose
@gauzy/ui-configpackages/ui-configUI configuration and feature flags
@gauzy/ui-corepackages/ui-coreCore Angular components, services, and pipes
@gauzy/ui-sdkpackages/ui-sdkSDK for building UI extensions

Plugins

PackagePathPurpose
@gauzy/plugin-changelogpackages/plugins/plugin-changelogChangelog and audit trail
@gauzy/plugin-integration-aipackages/plugins/plugin-integration-aiGauzy AI integration
@gauzy/plugin-integration-githubpackages/plugins/plugin-integration-githubGitHub integration
@gauzy/plugin-integration-hubstaffpackages/plugins/plugin-integration-hubstaffHubStaff integration
@gauzy/plugin-integration-jirapackages/plugins/plugin-integration-jiraJira integration
@gauzy/plugin-integration-makepackages/plugins/plugin-integration-makeMake.com integration
@gauzy/plugin-integration-upworkpackages/plugins/plugin-integration-upworkUpwork integration
@gauzy/plugin-integration-zapierpackages/plugins/plugin-integration-zapierZapier integration
@gauzy/plugin-integration-activepiecespackages/plugins/plugin-integration-activepiecesActivePieces integration
@gauzy/plugin-jitsu-analyticspackages/plugins/jitsu-analyticsJitsu analytics plugin
@gauzy/plugin-job-searchpackages/plugins/job-searchJob board search integration
@gauzy/plugin-job-search-uipackages/plugins/job-search-uiJob search UI components
@gauzy/plugin-job-matching-uipackages/plugins/job-matching-uiJob matching UI components
@gauzy/plugin-job-proposal-uipackages/plugins/job-proposal-uiJob proposal UI components
@gauzy/plugin-knowledge-basepackages/plugins/knowledge-baseKnowledge base and help center
@gauzy/plugin-knowledge-base-uipackages/plugins/knowledge-base-uiKnowledge base UI
@gauzy/plugin-legal-uipackages/plugins/legal-uiLegal pages UI
@gauzy/plugin-onboarding-uipackages/plugins/onboarding-uiOnboarding flow UI
@gauzy/plugin-product-reviewspackages/plugins/product-reviewsProduct reviews module
@gauzy/plugin-sentrypackages/plugins/sentrySentry 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:

Diagram; its source is available below
Diagram source
graph LR
    API["apps/api"] --> Core["packages/core"]
    Core --> Common["packages/common"]
    Core --> Contracts["packages/contracts"]
    Core --> Auth["packages/auth"]
    Core --> Config["packages/config"]
    Core --> Adapters["packages/adapters"]

    Gauzy["apps/gauzy"] --> UICore["packages/ui-core"]
    UICore --> UIConfig["packages/ui-config"]
    UICore --> UISDK["packages/ui-sdk"]
    UICore --> Contracts
    Common --> Contracts

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

TargetDescriptionCaching
buildCompile TypeScript / Angularβœ… NX cached
serveStart dev server❌ Not cached
testRun unit testsβœ… NX cached
lintRun ESLintβœ… NX cached
e2eRun E2E tests❌ Not cached

Build Order

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

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

Edit this page

Copyright Β© 2023-Present Ever Co. LTD.Docs by Sourcey