# frojasdev/taxi24-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/frojasdev/taxi24-challenge
- Repository: https://github.com/frojasdev/taxi24-challenge

## Overview

##### Project type and purpose
- This is a full-stack REST API built with NestJS (TypeScript), Prisma (ORM) and PostgreSQL.
- Its goal is to provide taxi-fleet management: drivers, passengers, trips and invoices.

##### File structure and layers
- **src/presentation**
Controllers handle incoming HTTP requests and define Nest modules.
- **src/application**
Use-case classes implement business operations (find-drivers, trip-management, invoice-management).
- **src/domain**
Entity definitions and pure domain logic (Driver, Passenger, Trip, Invoice).
- **src/infrastructure**
PrismaService (database client) and repositories mapping domain entities to persistence.
- **src/shared**
DTOs, validation, exception filters, response interceptors (cross-cutting concerns).
- **prisma**
DB schema, migrations, seed script.
- **docker-compose.yml**
Spins up PostgreSQL in Docker.
- **test**
End-to-end tests with Jest.

##### README for insights
- Architecture is layered (presentation → application → domain → infrastructure).
- Uses Nest modules to wire controllers, use cases, repositories, and PrismaService together.
- Exposes endpoints for drivers, passengers, trips, invoices.
- DB migrations & seeding via Prisma.

##### Main components
a. **External clients** (Postman, front-end UI or other services)
- Send HTTP requests (REST).
b. **API Gateway / NestJS Application**
- **Presentation Layer**: Controller classes grouped in Modules.
- **Application Layer**: Use-case classes orchestrating operations.
- **Domain Layer**: Entity models and domain rules.
- **Infrastructure Layer**:
- PrismaService (wraps Prisma Client)
- Repository classes (DriverRepository, TripRepository, etc.)
c. **PostgreSQL Database**
- Deployed via Docker Compose.
- Schema defined in prisma/schema.prisma.
d. **Development Tools** (optional)
- Prisma Studio, migrations, seed scripts.

##### Relationships and interactions
1. Client → HTTP → NestJS Controller
2. Controller → (injects) → Use Case (application/use-cases)
3. Use Case → Domain Entities / Domain Services (pure logic)
4. Use Case → Repository Interface
5. Repository → PrismaService → PostgreSQL
6. Prisma → returns records → Repository → Use Case → Controller → HTTP Response
7. Shared interceptors & filters sit between controller and response/error pipeline.

##### Architectural patterns and design principles
- **Layered (Onion/Clean) Architecture**
- Domain core isolated from infrastructure.
- Application orchestrates domain.
- Presentation merely forwards requests.
- Infrastructure implements repository interfaces.
- **Dependency Injection** (NestJS modules wiring).
- **Separation of Concerns**: DTOs vs Entities vs Database schemas.

##### Technologies, frameworks, libraries
- Runtime & Framework: Node.js, NestJS
- Language: TypeScript
- ORM: Prisma
- Database: PostgreSQL (Docker Compose)
- Testing: Jest
- Validation & Error Handling: class-validator, custom filters/interceptors
- API testing: Postman collection

##### Essential elements
- All four layers with their main components.
- External client(s) invoking REST endpoints.
- Prisma migrations/seed script as part of Infrastructure or DevOps.
- Cross‐cutting filters/interceptors attached to controller layer.
- Docker Compose node for PostgreSQL.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalClients["External Clients"]:::external
    click ExternalClients "https://github.com/frojasdev/taxi24-challenge/blob/master/Taxi24.postman_collection.json"

    subgraph "NestJS API"
        direction TB

        Entry["App Entry Point"]:::presentation
        click Entry "https://github.com/frojasdev/taxi24-challenge/blob/master/src/main.ts"
        click Entry "https://github.com/frojasdev/taxi24-challenge/blob/master/src/app.module.ts"

        subgraph "Presentation Layer"
            direction TB
            DC["DriverController"]:::presentation
            PC["PassengerController"]:::presentation
            TC["TripController"]:::presentation
            IC["InvoiceController"]:::presentation
            DM["DriverModule"]:::presentation
            PM["PassengerModule"]:::presentation
            TM["TripModule"]:::presentation
            IM["InvoiceModule"]:::presentation
            click DC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/controllers/driver.controller.ts"
            click PC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/controllers/passenger.controller.ts"
            click TC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/controllers/trip.controller.ts"
            click IC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/controllers/invoice.controller.ts"
            click DM "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/modules/driver.module.ts"
            click PM "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/modules/passenger.module.ts"
            click TM "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/modules/trip.module.ts"
            click IM "https://github.com/frojasdev/taxi24-challenge/blob/master/src/presentation/modules/invoice.module.ts"
        end

        subgraph "Application Layer"
            direction TB
            FDUC["FindDriversUseCase"]:::application
            FPUC["FindPassengersUseCase"]:::application
            TMUC["TripManagementUseCase"]:::application
            IMUC["InvoiceManagementUseCase"]:::application
            click FDUC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/application/use-cases/driver/find-drivers.use-case.ts"
            click FPUC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/application/use-cases/passenger/find-passengers.use-case.ts"
            click TMUC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/application/use-cases/trip/trip-management.use-case.ts"
            click IMUC "https://github.com/frojasdev/taxi24-challenge/blob/master/src/application/use-cases/invoice/invoice-management.use-case.ts"
        end

        subgraph "Domain Layer"
            direction TB
            DE["Driver Entity"]:::domain
            PE["Passenger Entity"]:::domain
            TE["Trip Entity"]:::domain
            IE["Invoice Entity"]:::domain
            EI["Entities Index"]:::domain
            click DE "https://github.com/frojasdev/taxi24-challenge/blob/master/src/domain/entities/driver.entity.ts"
            click PE "https://github.com/frojasdev/taxi24-challenge/blob/master/src/domain/entities/passenger.entity.ts"
            click TE "https://github.com/frojasdev/taxi24-challenge/blob/master/src/domain/entities/trip.entity.ts"
            click IE "https://github.com/frojasdev/taxi24-challenge/blob/master/src/domain/entities/invoice.entity.ts"
            click EI "https://github.com/frojasdev/taxi24-challenge/blob/master/src/domain/entities/index.ts"
        end

        subgraph "Infrastructure Layer"
            direction TB
            PS["PrismaService"]:::infrastructure
            DR["DriverRepository"]:::infrastructure
            PR["PassengerRepository"]:::infrastructure
            TR["TripRepository"]:::infrastructure
            IR["InvoiceRepository"]:::infrastructure
            click PS "https://github.com/frojasdev/taxi24-challenge/blob/master/src/infrastructure/database/prisma.service.ts"
            click DR "https://github.com/frojasdev/taxi24-challenge/blob/master/src/infrastructure/repositories/driver.repository.ts"
            click PR "https://github.com/frojasdev/taxi24-challenge/blob/master/src/infrastructure/repositories/passenger.repository.ts"
            click TR "https://github.com/frojasdev/taxi24-challenge/blob/master/src/infrastructure/repositories/trip.repository.ts"
            click IR "https://github.com/frojasdev/taxi24-challenge/blob/master/src/infrastructure/repositories/invoice.repository.ts"
        end

        subgraph "Shared Layer"
            direction TB
            DTOs["DTOs"]:::shared
            EF["Exception Filter"]:::shared
            RI["Response Interceptor"]:::shared
            click DTOs "https://github.com/frojasdev/taxi24-challenge/blob/master/src/shared/dto/validation.dto.ts"
            click EF "https://github.com/frojasdev/taxi24-challenge/blob/master/src/shared/filters/all-exceptions.filter.ts"
            click RI "https://github.com/frojasdev/taxi24-challenge/blob/master/src/shared/interceptors/response.interceptor.ts"
        end
    end

    subgraph "DevOps/DB Setup"
        direction TB
        DCMP["docker-compose.yml"]:::devops
        PSCH["schema.prisma"]:::devops
        MIG["migrations/20250825035601_init"]:::devops
        SEED["seed.ts"]:::devops
        click DCMP "https://github.com/frojasdev/taxi24-challenge/blob/master/docker-compose.yml"
        click PSCH "https://github.com/frojasdev/taxi24-challenge/blob/master/prisma/schema.prisma"
        click MIG "https://github.com/frojasdev/taxi24-challenge/tree/master/prisma/migrations/20250825035601_init"
        click SEED "https://github.com/frojasdev/taxi24-challenge/blob/master/prisma/seed.ts"
    end

    subgraph "Tests"
        direction TB
        E2E["app.e2e-spec.ts"]:::test
        JCFG["jest-e2e.json"]:::test
        click E2E "https://github.com/frojasdev/taxi24-challenge/blob/master/test/app.e2e-spec.ts"
        click JCFG "https://github.com/frojasdev/taxi24-challenge/blob/master/test/jest-e2e.json"
    end

    ExternalClients --> DC
    ExternalClients --> PC
    ExternalClients --> TC
    ExternalClients --> IC

    Entry --> DM
    Entry --> PM
    Entry --> TM
    Entry --> IM

    DC -->|"calls"| FDUC
    PC -->|"calls"| FPUC
    TC -->|"calls"| TMUC
    IC -->|"calls"| IMUC

    FDUC --> DE
    FPUC --> PE
    TMUC --> TE
    IMUC --> IE
    FDUC --> DR
    FPUC --> PR
    TMUC --> TR
    IMUC --> IR

    DR --> PS
    PR --> PS
    TR --> PS
    IR --> PS

    PS --> DB["PostgreSQL (taxi24_db)"]:::database

    DC -. uses filters .-> EF
    DC -. uses interceptors .-> RI

    DCMP --> DB
    PSCH --> PS
    MIG --> PS
    SEED --> PS

    E2E --> DC
    E2E --> DB

    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef presentation fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
    classDef application fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
    classDef domain fill:#fff9c4,stroke:#f9a825,stroke-width:1px
    classDef infrastructure fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef shared fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
    classDef database fill:#b2ebf2,stroke:#00acc1,stroke-width:1px
    classDef devops fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px
    classDef test fill:#fbe9e7,stroke:#d84315,stroke-width:1px
```
