# julianbesteiro/deliverit-back architecture

> Architecture diagram of the GitHub repository julianbesteiro/deliverit-back, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/julianbesteiro/deliverit-back
- Repository: https://github.com/julianbesteiro/deliverit-back

## Overview

##### Project Type & Purpose
- The project is a back-end service for a package distribution application. It is designed for a package distribution company; with distinct roles for package delivery drivers and administrators.
- The system uses NodeJS, Express, and TypeScript. It is containerized (Docker, EKS manifests) and follows a GitFlow branching strategy.
- The application handles functionalities such as delivery order management, route scheduling, and real-time updates on deliveries.

##### File Structure Analysis
- Major top-level directories:
- “src”: This contains core application code (controllers, models, services, repositories, middlewares, routes, schemas, config).
- “config”: Holds environment-specific configurations like development, production, and swaggerOptions (API documentation).
- “db”: Contains database configuration/setup scripts.
- “tests”: Contains unit, integration, and end-to-end tests.
- “dist”: Build output reflecting the compiled JavaScript files.
- Deployment-related files: Dockerfile, docker-compose.yml, and folders like “eks” and “.github/workflows” for CI/CD.
- The clear MVC-like pattern emerges with:
- Routes and Controllers managing HTTP requests.
- Services encapsulating business logic.
- Repositories handling data persistence.
- Middleware to intercept and process requests (error handling, authorization checks).

a. Main Components:
- Client/API Gateway: Although the front-end is not part of this repository, the API is exposed through Express routes.
- Express Server: The entry point (src/server.ts) where the Express app is configured.
- Controllers: Including admin, delivery, order, sworn, and user controllers, which receive API requests.
- Middlewares: Authentication (isAuth), authorization (isAdmin), error handling, and other pre-controller functions.
- Services: Modules that implement the core business logic (admin, delivery, order, user, sworn services).
- Repositories: Handle data interactions with the database (admin, delivery, order, user, sworn repositories).
- Models & Schemas: Define the data objects handled by the application (Delivery, Order, Sworn, User).
- Config & Utils: Global configuration files (e.g., DB and swaggerOptions) and utilities for tasks such as email sending, token management, and scheduled jobs.
- External Integrations: For example, AWS S3 utility for file storage, emailing service, and cron jobs for periodic tasks.
- Database: Represented by the “db” folder containing configuration and initialization (even if the specific database type isn’t mentioned, it is a core component).

b. Relationships/Interactions:
- Flow starts at the Express Server receiving HTTP requests which are routed to the appropriate Controller.
- Controllers call corresponding Services that encapsulate business logic.
- Services interact with Repositories to perform CRUD operations with the database.
- Middleware tasks (authentication, error handling) intercept the requests before reaching Controllers.
- Utility modules (for sending emails, uploading to S3, token management) support the core business flow.
- Config files provide the runtime environment, such as DB connections, server port configurations, and Swagger options for API documentation.
- CI/CD pipelines (via GitHub workflows, Dockerfile, and EKS manifests) support automated testing, deployment, and scaling.

c. Important Architectural Patterns/Design Principles:
- MVC-like pattern: Clear separation between Controllers, Services, and Repositories.
- Modular Design: Well-organized components promote separation of concerns with independent modules (middlewares, utils, tests).
- Containerization and CI/CD Integration: The Docker and EKS-related files indicate a container-based deployment and integration pipeline.
- Dependency Inversion: By using interfaces extensively (as seen in the src/interfaces directory), the project favors loosely coupled components.
- Testing Focus: Structured tests (unit, integration, E2E) suggest an emphasis on maintainability and quality assurance.

d. Relevant Technologies/Frameworks:
- Express and NodeJS as the core server framework.
- TypeScript for static typing and better maintainability.
- Docker and Kubernetes (EKS manifests) for deployment.
- GitHub Actions for CI/CD integration.
- Utilities for AWS (S3), email sending, and cron jobs.
- External libraries such as ESLint, Prettier, and Husky for code quality and linting.

##### Final Recommendations
- Remember that clarity is key: ensure that each component’s role is clearly defined and that connections show logical data flows or dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client HTTP Request"]:::external

    Container["DeliverIT Container"]:::deployment
    DeploymentCD["CI/CD Pipeline"]:::deployment
    DockerFiles["Docker Files"]:::deployment
    Kubernetes["Kubernetes Manifests"]:::deployment
    GitHubActions["GitHub Actions"]:::deployment

    ExpressServer["Express Server"]:::api
    Configurations["Configurations"]:::config

    subgraph "Middlewares Layer"
        Auth["Authentication Middleware"]:::middleware
        AdminAuth["Authorization Middleware"]:::middleware
        ErrorHandler["Error Handler Middleware"]:::middleware
    end

    subgraph "Controllers Layer"
        AdminController["Admin Controller"]:::controller
        DeliveryController["Delivery Controller"]:::controller
        OrderController["Order Controller"]:::controller
        SwornController["Sworn Controller"]:::controller
        UserController["User Controller"]:::controller
    end

    subgraph "Services Layer"
        AdminService["Admin Service"]:::service
        DeliveryService["Delivery Service"]:::service
        OrderService["Order Service"]:::service
        SwornService["Sworn Service"]:::service
        UserService["User Service"]:::service
    end

    subgraph "Repositories Layer"
        AdminRepository["Admin Repository"]:::repository
        DeliveryRepository["Delivery Repository"]:::repository
        OrderRepository["Order Repository"]:::repository
        SwornRepository["Sworn Repository"]:::repository
        UserRepository["User Repository"]:::repository
    end

    Database["Database"]:::database
    ModelsSchemas["Models & Schemas"]:::config
    Utilities["Utilities"]:::config

    %% High-Level Flow
    Client --> ExpressServer
    Container --> ExpressServer
    DeploymentCD --> Container
    DeploymentCD --> DockerFiles
    DeploymentCD --> Kubernetes
    DeploymentCD --> GitHubActions
    ExpressServer --> Configurations
    ExpressServer --> Auth
    Auth --> AdminAuth
    AdminAuth --> ErrorHandler
    ErrorHandler --> AdminController
    ErrorHandler --> DeliveryController
    ErrorHandler --> OrderController
    ErrorHandler --> SwornController
    ErrorHandler --> UserController

    AdminController --> AdminService
    DeliveryController --> DeliveryService
    OrderController --> OrderService
    SwornController --> SwornService
    UserController --> UserService

    AdminService --> AdminRepository
    DeliveryService --> DeliveryRepository
    OrderService --> OrderRepository
    SwornService --> SwornRepository
    UserService --> UserRepository

    AdminRepository --> Database
    DeliveryRepository --> Database
    OrderRepository --> Database
    SwornRepository --> Database
    UserRepository --> Database

    AdminRepository --> ModelsSchemas
    DeliveryRepository --> ModelsSchemas
    OrderRepository --> ModelsSchemas
    SwornRepository --> ModelsSchemas
    UserRepository --> ModelsSchemas

    AdminService --> Utilities
    DeliveryService --> Utilities
    OrderService --> Utilities
    SwornService --> Utilities
    UserService --> Utilities

    %% Click Events
    click ExpressServer "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/server.ts"
    click AdminController "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/controllers/admin.controller.ts"
    click DeliveryController "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/controllers/delivery.controller.ts"
    click OrderController "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/controllers/order.controller.ts"
    click SwornController "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/controllers/sworn.controller.ts"
    click UserController "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/controllers/user.controller.ts"
    click Auth "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/middlewares/isAuth.ts"
    click AdminAuth "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/middlewares/isAdmin.ts"
    click ErrorHandler "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/middlewares/errorHandler.ts"
    click AdminService "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/services/admin.service.ts"
    click DeliveryService "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/services/delivery.service.ts"
    click OrderService "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/services/order.service.ts"
    click SwornService "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/services/sworn.service.ts"
    click UserService "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/services/user.service.ts"
    click AdminRepository "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/repository/admin.repository.ts"
    click DeliveryRepository "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/repository/delivery.repository.ts"
    click OrderRepository "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/repository/order.repository.ts"
    click SwornRepository "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/repository/sworn.repository.ts"
    click UserRepository "https://github.com/julianbesteiro/deliverit-back/blob/develop/src/repository/user.repository.ts"
    click ModelsSchemas "https://github.com/julianbesteiro/deliverit-back/tree/develop/src/models"
    click Configurations "https://github.com/julianbesteiro/deliverit-back/tree/develop/config"
    click Database "https://github.com/julianbesteiro/deliverit-back/tree/develop/db"
    click Utilities "https://github.com/julianbesteiro/deliverit-back/tree/develop/src/utils"
    click DockerFiles "https://github.com/julianbesteiro/deliverit-back/tree/develop/Dockerfile"
    click Kubernetes "https://github.com/julianbesteiro/deliverit-back/tree/develop/eks"
    click GitHubActions "https://github.com/julianbesteiro/deliverit-back/tree/develop/.github/workflows"
    click DeploymentCD "https://github.com/julianbesteiro/deliverit-back/blob/develop/.github/workflows/development.yml"

    %% Styles
    classDef external fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef api fill:#ccf2ff,stroke:#0066cc,stroke-width:2px;
    classDef middleware fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef controller fill:#ffddcc,stroke:#cc6600,stroke-width:2px;
    classDef service fill:#ddffdd,stroke:#009900,stroke-width:2px;
    classDef repository fill:#ddeeff,stroke:#3333cc,stroke-width:2px;
    classDef database fill:#ffebcc,stroke:#cc3300,stroke-width:2px,stroke-dasharray: 5 5;
    classDef config fill:#e6e6e6,stroke:#666666,stroke-width:2px;
    classDef deployment fill:#e6ccff,stroke:#9933cc,stroke-width:2px;
```
