# Architecture Overview {#architecture-overview}


Ever Gauzy is built as a modern, full-stack TypeScript monorepo using enterprise-grade frameworks. This document provides a high-level view of the platform's architecture.


## System Architecture {#system-architecture}






```mermaid
graph TB
    subgraph Client["Client Layer"]
        A1["Angular UI<br/>(Web SPA, Port: 4200)"]
        A2["Desktop App<br/>(Electron, Embedded)"]
        A3["Desktop Timer<br/>(Electron, Standalone)"]
        A4["Ever Teams<br/>(React/RN)"]
    end

    subgraph Server["Server Layer — NestJS API Server (Port: 3000)"]
        B1["Auth Guards"]
        B2["CQRS Commands"]
        B3["REST API / Swagger"]
        B4["GraphQL (WIP)"]
        B5["MCP Server (AI Tools)"]
        B6["Modules (Core)"]
        B7["Plugin System"]
        B8["Event Bus (CQRS)"]
        B9["Job Scheduler (Bull/Redis)"]
    end

    subgraph Data["Data Layer"]
        C1["TypeORM"]
        C2["MikroORM"]
        C3["Knex"]
        C4["Redis"]
        C5["OpenSearch"]
        D1["PostgreSQL / MySQL / SQLite"]
        D2["Cache"]
        D3["Search"]
    end

    A1 & A2 & A3 & A4 -- "HTTP / WebSocket" --> Server
    C1 & C2 & C3 --> D1
    C4 --> D2
    C5 --> D3
```






## Architectural Layers {#architectural-layers}



### 1. Client Layer {#1-client-layer}


The client layer consists of multiple application types, all consuming the same API:

| Application            | Technology                     | Package Location     | Purpose                             |
| ---------------------- | ------------------------------ | -------------------- | ----------------------------------- |
| **Web UI**             | Angular 19+, Nebular/ngx-admin | `apps/gauzy`         | Primary web interface               |
| **Desktop App**        | Electron + Angular             | `apps/desktop`       | All-in-one desktop application      |
| **Desktop Timer**      | Electron + Angular             | `apps/desktop-timer` | Time tracking & activity monitoring |
| **Desktop Server**     | Electron + NestJS              | `apps/server`        | Self-hosted API server              |
| **API Server Desktop** | Electron + NestJS              | `apps/api-server`    | API-only server deployment          |
| **Ever Teams**         | React/Next.js + React Native   | External repo        | Modern PM/Task interface            |


### 2. API Layer (NestJS) {#2-api-layer-nestjs}


The backend is a NestJS application following **CQRS** (Command Query Responsibility Segregation) patterns:

- **Controllers** — handle HTTP requests, validate inputs, route to handlers
- **Commands/Queries** — encapsulate business logic via the CQRS pattern
- **Services** — core business logic and data access
- **Guards** — authentication and authorization (JWT, Roles, Permissions, Tenant)
- **Interceptors** — request/response transformation, logging
- **Pipes** — input validation and transformation (class-validator)
- **Modules** — NestJS dependency injection containers


### 3. Data Layer {#3-data-layer}


The platform uses a **Multi-ORM** architecture supporting:

- **TypeORM** — primary ORM with extensive entity definitions, repositories, and migrations
- **MikroORM** — alternative ORM with its own repositories and entity metadata
- **Knex** — raw SQL query builder for complex queries and migrations

All three ORMs connect to the same database and share entity definitions through a shared **Multi-ORM decorator** system.


### 4. Infrastructure Layer {#4-infrastructure-layer}


- **PostgreSQL** — primary production database
- **SQLite** — lightweight development/demo database
- **Redis** — caching, session store, and job queue
- **OpenSearch** — full-text search indexing
- **MinIO/S3** — file and image storage
- **Cube** — analytics and BI semantic layer
- **Zipkin/OTEL** — distributed tracing


## Key Architecture Patterns {#key-architecture-patterns}



### Multi-Tenant Architecture {#multi-tenant-architecture}


Every entity in the system is scoped to a **tenant**. The `TenantBaseEntity` base class provides:

- Automatic `tenantId` injection on create/update
- Automatic `tenantId` filtering on read queries
- Cross-tenant access prevention at the ORM level

See [Multi-Tenancy](https://sourcey-gauzy.pages.dev/architecture/multi-tenancy/index.md) for details.


### Plugin Architecture {#plugin-architecture}


The platform supports **dynamic plugins** for extending functionality:

```typescript
@Module({})
export class PluginModule {
  static forRoot(plugins: Type<any>[]): DynamicModule {
    return {
      module: PluginModule,
      imports: plugins,
    };
  }
}
```

Plugins can add: entities, controllers, services, commands, and event handlers. See [Plugin System](https://sourcey-gauzy.pages.dev/development/plugin-system/index.md).


### CQRS Pattern {#cqrs-pattern}


Business logic is organized into Commands (write) and Queries (read):

```
Controller → CommandBus/QueryBus → Handler → Service → Repository
```

This pattern enables:

- Clear separation of read and write operations
- Event-driven side effects
- Easier testing through handler isolation


### Event Bus {#event-bus}


The platform uses NestJS `@nestjs/cqrs` events for inter-module communication:

```typescript
// Publishing an event
this.eventBus.publish(new EmployeeCreatedEvent(employee));

// Handling an event in another module
@EventHandler(EmployeeCreatedEvent)
export class EmployeeCreatedHandler {
  handle(event: EmployeeCreatedEvent) {
    /* ... */
  }
}
```


### Request Context {#request-context}


A `RequestContext` utility provides access to the current request context throughout the application:

```typescript
// Access current user, tenant, and organization
const tenantId = RequestContext.currentTenantId();
const userId = RequestContext.currentUserId();
const orgId = RequestContext.currentOrganizationId();
```


## Data Flow {#data-flow}



### Typical API Request Flow {#typical-api-request-flow}






```mermaid
graph LR
    A["Client Request"] --> B["Guard (Auth)"]
    B --> C["Pipe (Validation)"]
    C --> D["Handler (CQRS)"]
    D --> E["Service"]
    E --> F["Repository (ORM)"]
    F --> G["Database"]
```





1. **Guard**: Validates JWT token, checks roles/permissions, resolves tenant
2. **Pipe**: Validates request body against DTO (Data Transfer Object) classes
3. **Handler**: Executes business logic via CQRS command/query handler
4. **Service**: Performs data access, integrations, and business rules
5. **Repository**: Issues database queries through the active ORM


### Guard Chain {#guard-chain}






```mermaid
graph LR
    A["JWT Auth Guard"] --> B["Tenant Resolve"]
    B --> C["Role Guard"]
    C --> D["Permission Guard"]
```






## Deployment Models {#deployment-models}


| Model                  | Components                    | Best For                      |
| ---------------------- | ----------------------------- | ----------------------------- |
| **SaaS**               | Cloud-hosted API + UI         | Multi-tenant production       |
| **Self-Hosted**        | Docker or bare metal          | Private infrastructure        |
| **Desktop Server**     | Electron app hosting API      | Small teams, individuals      |
| **Desktop All-in-One** | Full platform in single app   | Personal use                  |
| **Client-Server**      | Separate API server + clients | Teams with centralized server |


## Related Pages {#related-pages}


- [Monorepo Structure](https://sourcey-gauzy.pages.dev/architecture/monorepo-structure/index.md) — NX workspace organization
- [Technology Stack](https://sourcey-gauzy.pages.dev/architecture/technology-stack/index.md) — all technologies used
- [Backend Architecture](https://sourcey-gauzy.pages.dev/architecture/backend-architecture/index.md) — NestJS internals
- [Frontend Architecture](https://sourcey-gauzy.pages.dev/architecture/frontend-architecture/index.md) — Angular UI
- [Multi-ORM Architecture](https://sourcey-gauzy.pages.dev/architecture/multi-orm-architecture/index.md) — TypeORM, MikroORM, Knex
- [Plugin System](https://sourcey-gauzy.pages.dev/development/plugin-system/index.md) — extending the platform
- [Multi-Tenancy](https://sourcey-gauzy.pages.dev/architecture/multi-tenancy/index.md) — tenant isolation
- [Design Principles](https://sourcey-gauzy.pages.dev/architecture/design-principles/index.md) — core philosophy