# oshri134/delivery-management-service architecture

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

- Interactive diagram: https://gitdiagram.com/oshri134/delivery-management-service
- Repository: https://github.com/oshri134/delivery-management-service

## Overview

##### Project Type and Purpose
- This is a backend monolithic RESTful service called “Delivery Management Service.”
- Built in TypeScript + Node.js/Express, it handles user authentication, package creation, driver availability, delivery assignment, reporting, metrics, and forecasting.

##### File Structure
- Top-level: configuration files (.env, Dockerfile, docker-compose.yml), docs, scripts, source code under ​src​, and tests.
- src/app.ts boots the Express server.
- src/config holds environment, Swagger and validation setup.
- src/routes ▶ controllers ▶ services ▶ repositories ▶ models form a classic layered architecture.
- src/database contains TypeORM/Sequelize config, migrations, and seeders.
- src/middleware provides cross-cutting concerns (auth, error handling, metrics).
- src/utils includes error definitions, logging, and response formatting.
- Ecosystem config, CI workflow, and Docker compose illustrate deployment readiness.

##### Key Insights from README
- Uses SQL Server (via Docker locally or RDS/Azure SQL in cloud).
- Optional Redis caching for sessions/fast data.
- JWT authentication, Sequelize ORM, Joi validation, Prometheus metrics, Swagger/OpenAPI docs.
- Layered service boundaries for Controllers (HTTP), Services (business logic), Repositories (data access).
- Dockerized for local dev; ECS/Fargate and Azure Container Instances for production.

a. Main Components
– API Gateway/HTTP Server (Express + middleware)
– Authentication Module (JWT, AuthController/AuthService)
– Business Logic Layer (DeliveryService, DriverService, PricingService, NotificationService, ForecastService)
– Data Access Layer (Sequelize ORM, Repositories for User, Package, Delivery, Driver, Address)
– Relational Database (SQL Server)
– Optional Cache (Redis)
– Observability: Prometheus metrics endpoint, SwaggerUI for API docs, Winston logging
– External Services: Secrets Manager (AWS Secrets Manager/Azure Key Vault), Container Registry, CI/CD pipeline

b. Relationships & Data Flows
– Client → HTTP Server → Router → Controller → Service → Repository → Database
– Authenticated requests validated by auth middleware before reaching controllers
– ServiceFactory to instantiate services with appropriate dependencies
– Database migrations/seeders executed via scripts for CI/CD
– Prometheus scraper pulls metrics from /metrics endpoint
– SwaggerUI exposed at /api-docs for API exploration

c. Architectural Patterns & Principles
– Layered (Clean) Architecture: separation of concerns across controllers/services/repositories/models
– Repository Pattern for decoupling business logic from ORM
– Middleware Chain for cross-cutting concerns (validation, security, error handling, metrics)
– Transactional Unit-of-Work for race-condition-safe driver assignment
– Dependency Injection via ServiceFactory and config modules

d. Major Technologies
– Node.js, Express, TypeScript
– Sequelize ORM targeting SQL Server
– Joi for request validation
– Redis for optional caching/session storage
– Docker & docker-compose for containerization
– Swagger/OpenAPI for API documentation
– Prometheus for metrics, Winston for structured logging
– GitHub Actions for CI, Amazon ECS/Azure Container Instances for CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Server Layer
    subgraph "API Server" 
        direction TB
        Server["Express HTTP Server"]:::http
        subgraph "Middleware Pipeline"
            direction TB
            AuthMW["Auth Middleware"]:::middleware
            ValidationMW["Validation Middleware"]:::middleware
            MetricsMW["Metrics Middleware"]:::middleware
            SecurityMW["Security Middleware"]:::middleware
            ErrorMW["Error Handling Middleware"]:::middleware
            AsyncMW["Async Handler Middleware"]:::middleware
        end
        subgraph "Routes"
            direction TB
            IndexRoutes["index.ts"]:::http
            AuthRoutes["auth.routes.ts"]:::http
            DeliveryRoutes["delivery.routes.ts"]:::http
            DriverRoutes["driver.routes.ts"]:::http
            PackageRoutes["package.routes.ts"]:::http
        end
    end

    %% Controllers Layer
    subgraph "Controllers" 
        direction TB
        AuthController["AuthController"]:::http
        DeliveryController["DeliveryController"]:::http
        DriverController["DriverController"]:::http
        PackageController["PackageController"]:::http
    end

    %% Services Layer
    subgraph "Services" 
        direction TB
        AuthService["AuthService"]:::service
        DeliveryService["DeliveryService"]:::service
        DriverService["DriverService"]:::service
        DriverForecastService["DriverForecastService"]:::service
        PackageService["PackageService"]:::service
        PricingService["PricingService"]:::service
        NotificationService["NotificationService"]:::service
        UserService["UserService"]:::service
        AddressService["AddressService"]:::service
        ServiceFactory["ServiceFactory"]:::service
    end

    %% Repositories Layer
    subgraph "Repositories" 
        direction TB
        BaseRepo["BaseRepository"]:::repo
        UserRepo["UserRepository"]:::repo
        PackageRepo["PackageRepository"]:::repo
        DeliveryRepo["DeliveryRepository"]:::repo
        DriverRepo["DriverRepository"]:::repo
        AddressRepo["AddressRepository"]:::repo
    end

    %% Database & Cache
    SQLDB["SQL Server Database"]:::db
    Redis["Redis Cache"]:::cache

    %% Observability & Docs
    Prometheus["Prometheus"]:::obs
    SwaggerUI["Swagger UI"]:::obs
    Logger["Winston Logger"]:::obs

    %% External Infrastructure
    Secrets["Secrets Manager"]:::cloud
    CI_CD["CI/CD Pipeline"]:::cloud
    ContainerRegistry["Container Registry"]:::cloud

    %% Flows
    Server --> AuthMW --> ValidationMW --> MetricsMW --> SecurityMW --> ErrorMW --> AsyncMW --> IndexRoutes
    IndexRoutes --> AuthController
    IndexRoutes --> DeliveryController
    IndexRoutes --> DriverController
    IndexRoutes --> PackageController

    AuthController --> AuthService
    DeliveryController --> DeliveryService
    DriverController --> DriverService
    PackageController --> PackageService

    DeliveryService --> PackageRepo
    DeliveryService --> DeliveryRepo
    DriverService --> DriverRepo
    DriverForecastService --> DriverRepo
    PackageService --> PackageRepo
    UserService --> UserRepo
    AddressService --> AddressRepo
    PricingService --> BaseRepo
    NotificationService --> BaseRepo

    PackageRepo --> SQLDB
    DeliveryRepo --> SQLDB
    UserRepo --> SQLDB
    DriverRepo --> SQLDB
    AddressRepo --> SQLDB

    %% Cache usage
    AuthService --> Redis
    DriverService --> Redis

    %% Observability & Docs
    MetricsMW --> Prometheus
    Server --> SwaggerUI
    Server --> Logger

    %% External Services
    Server --> Secrets
    CI_CD -->|Deploy| Server
    CI_CD -->|Push| ContainerRegistry

    %% Click events
    click Server "https://github.com/oshri134/delivery-management-service/blob/main/src/app.ts"
    click AuthMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/auth.ts"
    click ValidationMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/validation.ts"
    click MetricsMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/metrics.ts"
    click SecurityMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/security.ts"
    click ErrorMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/errorHandler.ts"
    click AsyncMW "https://github.com/oshri134/delivery-management-service/blob/main/src/middleware/asyncHandler.ts"
    click IndexRoutes "https://github.com/oshri134/delivery-management-service/blob/main/src/routes/index.ts"
    click AuthRoutes "https://github.com/oshri134/delivery-management-service/blob/main/src/routes/auth.routes.ts"
    click DeliveryRoutes "https://github.com/oshri134/delivery-management-service/blob/main/src/routes/delivery.routes.ts"
    click DriverRoutes "https://github.com/oshri134/delivery-management-service/blob/main/src/routes/driver.routes.ts"
    click PackageRoutes "https://github.com/oshri134/delivery-management-service/blob/main/src/routes/package.routes.ts"
    click AuthController "https://github.com/oshri134/delivery-management-service/blob/main/src/controllers/AuthController.ts"
    click DeliveryController "https://github.com/oshri134/delivery-management-service/blob/main/src/controllers/DeliveryController.ts"
    click DriverController "https://github.com/oshri134/delivery-management-service/blob/main/src/controllers/DriverController.ts"
    click PackageController "https://github.com/oshri134/delivery-management-service/blob/main/src/controllers/PackageController.ts"
    click AuthService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/AuthService.ts"
    click DeliveryService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/DeliveryService.ts"
    click DriverService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/DriverService.ts"
    click DriverForecastService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/DriverForecastService.ts"
    click PackageService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/PackageService.ts"
    click PricingService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/PricingService.ts"
    click NotificationService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/NotificationService.ts"
    click UserService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/UserService.ts"
    click AddressService "https://github.com/oshri134/delivery-management-service/blob/main/src/services/AddressService.ts"
    click ServiceFactory "https://github.com/oshri134/delivery-management-service/blob/main/src/services/ServiceFactory.ts"
    click BaseRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/BaseRepository.ts"
    click UserRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/UserRepository.ts"
    click PackageRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/PackageRepository.ts"
    click DeliveryRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/DeliveryRepository.ts"
    click DriverRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/DriverRepository.ts"
    click AddressRepo "https://github.com/oshri134/delivery-management-service/blob/main/src/repositories/AddressRepository.ts"
    click SQLDB "https://github.com/oshri134/delivery-management-service/blob/main/src/database/config/database.ts"

    %% Styles
    classDef http fill:#a8e6cf,stroke:#379683,stroke-width:1px
    classDef middleware fill:#dcedc1,stroke:#8acb88,stroke-width:1px
    classDef service fill:#a0c4ff,stroke:#3d5a80,stroke-width:1px
    classDef repo fill:#ffb3ba,stroke:#ff6961,stroke-width:1px
    classDef db fill:#d3d3d3,stroke:#a9a9a9,stroke-width:1px
    classDef cache fill:#ffdfa4,stroke:#ffa500,stroke-width:1px
    classDef obs fill:#f0efeb,stroke:#c9ba9b,stroke-width:1px
    classDef cloud fill:#e0e0e0,stroke:#b0b0b0,stroke-width:1px
```
