Architecture Overview

System Architecture

Diagram source

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

1. Client Layer

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

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

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

• 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

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 for details.

Plugin Architecture

The platform supports dynamic plugins for extending functionality:

@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.

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

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

// 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

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

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

Data Flow

Typical API Request Flow

Diagram source

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

Diagram source

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

Deployment Models

Related Pages

• Monorepo Structure — NX workspace organization
• Technology Stack — all technologies used
• Backend Architecture — NestJS internals
• Frontend Architecture — Angular UI
• Multi-ORM Architecture — TypeORM, MikroORM, Knex
• Plugin System — extending the platform
• Multi-Tenancy — tenant isolation
• Design Principles — core philosophy