# ziyadh-ali/workwave-api architecture

> Architecture diagram of the GitHub repository ziyadh-ali/workwave-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ziyadh-ali/workwave-api
- Repository: https://github.com/ziyadh-ali/workwave-api

## Overview

##### Project Type and Purpose
- This is a backend-only (Node.js/TypeScript) REST API for a company portal that manages employees, leave, payroll, messaging, etc.
- It follows a clean/hexagonal (onion) architecture:
– Adapters (controllers, repositories, services)
– Application (use cases)
– Domain (entities, DTOs, mappers, interfaces)
– Framework/Infrastructure (HTTP server, DI container, database, external services)

##### File Structure and Map to Architectural Layers
- src/frameworks/http/server.ts & src/frameworks/routes → API gateway layer (Express server + route definitions)
- src/adapters/controllers → HTTP “ports” (Controllers implement API endpoints)
- src/adapters/middlewares → cross-cutting concerns (auth, logging, error handling)
- src/adapters/repositories → infrastructure implementations of repository interfaces
- src/useCases → application services (orchestrate business flows)
- src/entities → domain models, DTOs, interfaces, mappers, repository & service interfaces
- src/frameworks/database → database connection (mongoConnect), schemas & ORM models
- src/adapters/service & src/shared → integrations with external systems (SMTP, Cloudinary, socket server, cron jobs)
- src/frameworks/di → dependency-injection registry and resolver

##### README for Additional Insight
- Confirms purpose: “company portal to manage employees.”
- Implies modules for attendance, leave, payroll, messaging, PDF generation, admin vs. employee roles.

1. HTTP Request → Routes → AuthMiddleware → Controller
2. Controller calls corresponding Use Case (injected via DI)
3. Use Case calls Repository Interface and/or Service Interface
4. Repository Implementation (Adapter) uses Mongoose Model → MongoDB
5. Data flows back up: DB → Model → Repository → Use Case → Controller → Response
6. External Service calls (e.g., Mailer, Cloudinary, Socket) branch off from Use Cases or Services
7. CronService (adapter) triggers scheduled Use Case executions
c. Architectural Patterns & Principles:
– Dependency Inversion: Controllers → Use Case Interfaces; Use Cases → Repository Interfaces
– Single Responsibility: Each layer has a distinct concern
– Separation of Concerns & Testability: Domain logic isolated in Use Cases & Entities
– Hexagonal/Clean Architecture: Adapters and Frameworks sit at the edges, core domain at center
d. Technologies & Frameworks to annotate:
– Node.js, TypeScript, Express
– Mongoose (MongoDB)
– JWT, bcrypt (security)
– Multer/Cloudinary (file uploads)
– Nodemailer (email)
– socket.io (real-time messages)
– node-cron (scheduled jobs)
– ts-yr (DI container, if applicable)

##### Essential Elements (Don’t Over-Complicate)
- Express Server → Controllers → Use Cases → Repositories → MongoDB
- External Adapters: Email, File Upload, Socket, Scheduler
- DI Container wiring components together
– Include error-handling and logging middleware as part of the request pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HTTP/API Layer
    subgraph "HTTP/API Layer"
        direction TB
        ExpressServer["Express Server"]:::api
        Routes["Routes"]:::api
    end

    %% Adapter Layer
    subgraph "Adapter Layer"
        direction TB
        Middlewares["Middlewares"]:::adapter
        Controllers["Controllers"]:::adapter
        RepositoryImpl["Repository Implementations"]:::adapter
        ExternalServices["External Service Adapters"]:::adapter
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        UseCases["Use Cases"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        Entities["Entities, DTOs, Interfaces, Mappers"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        DIContainer["Dependency Injection Container"]:::infra
        MongoConnect["MongoConnect"]:::infra
        Schemas["DB Schemas"]:::infra
        Models["ORM Models"]:::infra
        DB[(MongoDB)]:::infra
    end

    %% Shared Layer
    subgraph "Shared Layer"
        direction TB
        SharedUtils["Shared Utilities & Config"]:::shared
    end

    %% Connections
    ExpressServer -->|hosts| Routes
    Routes -->|uses| Middlewares
    Middlewares -->|calls| Controllers
    Controllers -->|injects via DI| UseCases
    UseCases -->|calls| RepositoryImpl
    RepositoryImpl -->|uses| Schemas
    Schemas -->|defines| Models
    Models -->|connects| MongoConnect
    MongoConnect -->|reads/writes| DB
    UseCases -->|integrates| ExternalServices

    %% DI Wiring
    DIContainer --> Controllers
    DIContainer --> UseCases
    DIContainer --> RepositoryImpl
    DIContainer --> ExternalServices

    %% Click Events
    click ExpressServer "https://github.com/ziyadh-ali/workwave-api/blob/main/src/frameworks/http/server.ts"
    click Routes "https://github.com/ziyadh-ali/workwave-api/tree/main/src/frameworks/routes/"
    click Controllers "https://github.com/ziyadh-ali/workwave-api/tree/main/src/adapters/controllers/"
    click Middlewares "https://github.com/ziyadh-ali/workwave-api/tree/main/src/adapters/middlewares/"
    click RepositoryImpl "https://github.com/ziyadh-ali/workwave-api/tree/main/src/adapters/repositories/"
    click ExternalServices "https://github.com/ziyadh-ali/workwave-api/tree/main/src/adapters/service/"
    click UseCases "https://github.com/ziyadh-ali/workwave-api/tree/main/src/useCases/"
    click Entities "https://github.com/ziyadh-ali/workwave-api/tree/main/src/entities/"
    click MongoConnect "https://github.com/ziyadh-ali/workwave-api/blob/main/src/frameworks/database/mongodb/mongoConnect.ts"
    click Schemas "https://github.com/ziyadh-ali/workwave-api/tree/main/src/frameworks/database/schemas/"
    click Models "https://github.com/ziyadh-ali/workwave-api/tree/main/src/frameworks/database/models/"
    click DIContainer "https://github.com/ziyadh-ali/workwave-api/tree/main/src/frameworks/di/"
    click SharedUtils "https://github.com/ziyadh-ali/workwave-api/tree/main/src/shared/"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#1F618D,color:#1B4F72
    classDef adapter fill:#D5F5E3,stroke:#196F3D,color:#145A32
    classDef application fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef domain fill:#FDEBD0,stroke:#BA4A00,color:#873600
    classDef infra fill:#E5E8E8,stroke:#566573,color:#2C3E50
    classDef shared fill:#F9EBEA,stroke:#943126,color:#641E16
```
