# kevinorjg/optarys-invex architecture

> Architecture diagram of the GitHub repository kevinorjg/optarys-invex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kevinorjg/optarys-invex
- Repository: https://github.com/kevinorjg/optarys-invex

## Overview

##### Project Type and Purpose
- This is a “monolithic” back-end service built on the NestJS framework (TypeScript/Node.js).
- It exposes HTTP endpoints for account management, authentication (sign-in/sign-up), RBAC (roles & permissions), health checks, and metrics.
- It follows a layered, Domain-Driven structure (Presentation → Application → Domain → Infrastructure).

##### High-Level Layers & Top-Level Directories
- src/main.ts & nest-cli.json – Nest entry point & CLI config
- src/presentation – HTTP controllers (REST endpoints)
- src/application – Business use-cases, handlers, DTOs, guards, mediator & logging services
- src/domain – Core entities & contracts interfaces
- src/infrastructure – Database context (TypeORM models) & tenant configuration
- src/app.module.ts & dependencyInjection.ts – Module wiring & DI container setup

##### Reading the README
- Confirms a standard NestJS starter with build/start scripts, tests, and deployment guidance.
- No external front-end; it’s purely a back-end API.

##### Main Components
A. Client(s) (e.g., web/mobile)
B. API Gateway / NestJS Application
· Presentation Layer (Controllers: Auth, Account, Access, Health, Metrics)
· Application Layer
– Use-Case Handlers (CreateAccountHandler, SignInWithCredentialsHandler)
– Mediator Service for command dispatch
– Logger Service
– Guards (AuthGuard)
· Domain Layer (Entities: User, Account, Role, Permission; Contracts)
· Infrastructure Layer
– TypeORM Context (Entities mapped to DB tables)
– Tenant Context (multi-tenant config)
C. Database (e.g., PostgreSQL)
D. External Monitoring/Metrics
· Node Exporter (install_node_exporter.sh)
· Prometheus/Grafana pulling from /metrics endpoint

##### Relationships & Data Flow
1. HTTP Client → (1) Presentation Controller
2. Controller → (2) Application Handler via DI
3. Handler → (3) Domain Entities / Business Logic
4. Domain → (4) Infrastructure (TypeORM Repository → SQL DB)
5. Handlers/Services log events → (5) Logger Service
6. Metrics Endpoint scraped by Node Exporter/Prometheus

##### Architectural Patterns & Principles
- Layered Architecture (Separation of Concerns)
- Dependency Injection (Nest modules & custom dependencyInjection.ts)
- Mediator Pattern for decoupled command handling
- Guard pattern for authorization
- Domain-Driven Design (Entities & Contracts)
- Multi-tenant support via tenantContext

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["HTTP Client (Web/Mobile)"]:::external

    %% Nest Entry & Root Module
    subgraph "NestJS Application"
        Main["src/main.ts"]:::code
        AppModule["AppModule\n(src/app.module.ts)"]:::code
    end

    Client -->|"1. HTTP"| AuthController
    Client -->|"1. HTTP"| AccountController
    Client -->|"1. HTTP"| AccessController
    Client -->|"1. HTTP"| HealthController
    Client -->|"1. HTTP"| MetricsController

    Main --> AppModule

    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        AuthController["AuthController"]:::presentation
        AccountController["AccountController"]:::presentation
        AccessController["AccessController"]:::presentation
        HealthController["HealthController"]:::presentation
        MetricsController["MetricsController"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        MediatorService["MediatorService"]:::application
        LoggerService["LoggerService"]:::application
        AuthGuard["AuthGuard"]:::application
        CreateAccountHandler["CreateAccountHandler"]:::application
        SignInWithCredentialsHandler["SignInWithCredentialsHandler"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        UserEntity["User Entity"]:::domain
        DomainContracts["Domain Contracts"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        ORMModels["TypeORM Models"]:::infrastructure
        TenantCtx["TenantContext"]:::infrastructure
        TenantCfg["TenantContextConfiguration"]:::infrastructure
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Database["PostgreSQL Database"]:::external
        NodeExporter["Node Exporter"]:::external
        Prometheus["Prometheus/Grafana"]:::external
    end

    %% Flows
    AuthController -->|"2. DI call"| MediatorService
    AccountController -->|"2. DI call"| MediatorService
    AccessController -->|"2. DI call"| MediatorService
    HealthController -->|"2. direct"| LoggerService
    MetricsController -->|"exposes /metrics"| NodeExporter

    MediatorService -->|"invoke"| CreateAccountHandler
    MediatorService -->|"invoke"| SignInWithCredentialsHandler

    AuthGuard -.-> AuthController
    AuthGuard -.-> AccountController
    AuthGuard -.-> AccessController

    CreateAccountHandler -->|"3. uses"| UserEntity
    SignInWithCredentialsHandler -->|"3. uses"| UserEntity

    CreateAccountHandler -->|"5. logs"| LoggerService
    SignInWithCredentialsHandler -->|"5. logs"| LoggerService

    CreateAccountHandler -->|"4. SQL via"| ORMModels
    SignInWithCredentialsHandler -->|"4. SQL via"| ORMModels

    ORMModels -->|"SQL"| Database

    NodeExporter -->|".:metrics"| Prometheus

    %% Click Events
    click AuthController "https://github.com/kevinorjg/optarys-invex/blob/production/src/presentation/controllers/auth/auth.controller.ts"
    click AccountController "https://github.com/kevinorjg/optarys-invex/blob/production/src/presentation/controllers/account/account.controller.ts"
    click AccessController "https://github.com/kevinorjg/optarys-invex/blob/production/src/presentation/controllers/access/access.controller.ts"
    click HealthController "https://github.com/kevinorjg/optarys-invex/blob/production/src/presentation/controllers/healt/healt.controller.ts"
    click MetricsController "https://github.com/kevinorjg/optarys-invex/blob/production/src/presentation/controllers/metrics/metrics.controller.ts"
    click CreateAccountHandler "https://github.com/kevinorjg/optarys-invex/blob/production/src/application/features/account/createAccount/CreateAccountHandler.ts"
    click SignInWithCredentialsHandler "https://github.com/kevinorjg/optarys-invex/blob/production/src/application/features/signup/signInWithCredentials/signInWithCredentialsHandler.ts"
    click AuthGuard "https://github.com/kevinorjg/optarys-invex/blob/production/src/application/guards/auth/auth.guard.ts"
    click MediatorService "https://github.com/kevinorjg/optarys-invex/blob/production/src/application/services/mediator/mediator.service.ts"
    click LoggerService "https://github.com/kevinorjg/optarys-invex/blob/production/src/application/services/logger/logger.service.ts"
    click UserEntity "https://github.com/kevinorjg/optarys-invex/blob/production/src/domain/entities/account.entity.ts"
    click DomainContracts "https://github.com/kevinorjg/optarys-invex/blob/production/src/domain/contracts/module.register.ts"
    click ORMModels "https://github.com/kevinorjg/optarys-invex/blob/production/src/infrastructure/context/models/user.entity.ts"
    click ORMModels "https://github.com/kevinorjg/optarys-invex/blob/production/src/infrastructure/context/models/role.entity.ts"
    click ORMModels "https://github.com/kevinorjg/optarys-invex/blob/production/src/infrastructure/context/models/permission.entity.ts"
    click TenantCtx "https://github.com/kevinorjg/optarys-invex/blob/production/src/infrastructure/context/tenant/tenantContext.ts"
    click TenantCfg "https://github.com/kevinorjg/optarys-invex/blob/production/src/infrastructure/context/tenant/tenantContextConfiguration.ts"
    click Main "https://github.com/kevinorjg/optarys-invex/blob/production/src/main.ts"
    click AppModule "https://github.com/kevinorjg/optarys-invex/blob/production/src/app.module.ts"
    click NodeExporter "https://github.com/kevinorjg/optarys-invex/blob/production/install_node_exporter.sh"

    %% Styles
    classDef presentation fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef application fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef domain fill:#FFF9C4,stroke:#FDD835,color:#F57F17;
    classDef infrastructure fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef external fill:#EEEEEE,stroke:#BDBDBD,color:#424242;
    classDef code fill:#E3F2FD,stroke:#64B5F6,color:#0D47A1,stroke-dasharray: 5 5;
    classDef application dashed stroke-dasharray: 5 5;
    class AuthGuard application;
    class LoggerService application;
    class MediatorService application;
```
