# gabrielmatsan/fast-feet architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielmatsan/fast-feet
- Repository: https://github.com/gabrielmatsan/fast-feet

## Overview

##### Project type and purpose
- This is a backend‐only, full-stack server application built with NestJS using a Domain-Driven Design (DDD) / Hexagonal (Onion) architecture.
- Purpose: Manage a delivery system (orders, delivery persons, recipients, attachments) and an associated notification system (push notifications on "order delivered/in-transit/returned").

##### File structure
- Top-level “src” folder contains:
- core – generic building blocks (Either, Entities, ValueObjects, DomainEvents).
- domain – two bounded contexts: delivery and notification; each has:
‑ enterprise/entities (rich domain model)
‑ application/use-cases (business logic)
‑ application/repositories (ports/interfaces)
‑ (delivery only) criptography, storage, events
- infra – adapters/drivers:
‑ http/controllers (NestJS REST API)
‑ database/prisma (ORM mappers & repository implementations)
‑ auth (JWT guards/strategies, decorators)
‑ events (NestJS event-bus subscribers & e2e tests)
‑ storage (R2/S3 uploader)
‑ env (configuration)
‑ main.ts & AppModule (composition root)
- Prisma folder holds DB schema, migrations, and generates TypeScript client.
- docker-compose.yml likely spins up Postgres (or other) plus S3 emulator.

##### README
- Confirms a NestJS server app starter: “building efficient and scalable server-side applications.”

##### Elements
- “Controllers” (HTTP Layer)
- “Use-Cases” (Application Layer)
- “Entities & Domain Events” (Domain Layer)
- “Repositories” (Interfaces) & “Prisma Repositories” (Infra)
- “Storage Adapter”, “Cryptography Adapter”, “Event Bus”
- “PostgreSQL” and “Cloud Storage” as external systems
- Request/response flow
- Domain event emission & subscription
- Adapter calls to external systems
- Blue for core/domain elements
- Green for application/use-cases
- Orange for infra/adapters
- Grey for external services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% HTTP Layer
    subgraph "HTTP Layer"
        Controllers["HTTP Controllers"]:::infra
    end

    %% Application Layer
    subgraph "Application Layer"
        subgraph Delivery_Context
            UC_Delivery["Delivery Use-Cases"]:::application
        end
        subgraph Notification_Context
            UC_Notification["Notification Use-Cases"]:::application
            Sub_Subscriber["Event Subscribers"]:::application
        end
    end

    %% Domain Layer
    subgraph "Domain Layer"
        subgraph Delivery_Domain
            Entities_Delivery["Entities & Value Objects"]:::domain
            Events_Delivery["Domain Events"]:::domain
        end
        subgraph Notification_Domain
            Entities_Notification["Notification Entities"]:::domain
        end
        RepoPorts_Delivery["Delivery Repository Ports"]:::domain
        RepoPorts_Notification["Notification Repository Ports"]:::domain
        StoragePort["Storage Port (Uploader)"]:::domain
        EncrypterPort["Encrypter & Hash Ports"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        subgraph Persistence
            Prisma_Mappers["Prisma Mappers"]:::infra
            Prisma_Repos["Prisma Repositories"]:::infra
            Prisma_Service["Prisma Service"]:::infra
            DB_Module["Database Module"]:::infra
        end
        Storage_Adapter["R2 Storage Adapter"]:::infra
        Crypto_Bcrypt["Bcrypt Hasher"]:::infra
        Crypto_JWT["JWT Encrypter"]:::infra
        Crypto_Module["Cryptography Module"]:::infra
        Auth_Strategy["JWT Strategy"]:::infra
        Auth_Guard["Auth Guard"]:::infra
        Current_User["Current-User Decorator"]:::infra
        HTTP_Module["HTTP Module"]:::infra
        Validation_Pipe["Zod Validation Pipe"]:::infra
        EventBus["Event Bus & E2E Tests"]:::infra
        AppModule["App Module"]:::infra
        Main["Main Entry"]:::infra
        Env["Env Module"]:::infra
    end

    %% External Systems
    Postgres["PostgreSQL"]:::external
    CloudStorage["Cloud Storage (R2/S3)"]:::external
    DockerCompose["docker-compose.yml"]:::external

    %% Connections
    Main --> AppModule
    AppModule --> HTTP_Module
    HTTP_Module --> Controllers
    Controllers --> Validation_Pipe
    Controllers -->|calls| UC_Delivery
    Controllers -->|calls| UC_Notification
    Controllers --> Auth_Guard
    Auth_Guard --> Auth_Strategy
    Auth_Strategy --> Crypto_JWT

    UC_Delivery -->|uses| Entities_Delivery
    UC_Notification -->|uses| Entities_Notification
    UC_Delivery -->|calls| RepoPorts_Delivery
    UC_Notification -->|calls| RepoPorts_Notification
    UC_Delivery -->|uploads| StoragePort
    StoragePort --> Storage_Adapter
    Storage_Adapter --> CloudStorage
    UC_Delivery -->|encrypts| EncrypterPort
    EncrypterPort --> Crypto_Bcrypt
    EncrypterPort --> Crypto_JWT
    Crypto_Module --> Crypto_Bcrypt
    Crypto_Module --> Crypto_JWT

    RepoPorts_Delivery -->|implemented by| Prisma_Repos
    RepoPorts_Notification -->|implemented by| Prisma_Repos
    Prisma_Repos --> Prisma_Mappers
    Prisma_Repos -->|connects to| Postgres
    DB_Module --> Prisma_Service
    Prisma_Service --> Prisma_Repos
    Prisma_Mappers --> Prisma_Repos

    Entities_Delivery --> Events_Delivery
    Events_Delivery -. emits .-> EventBus
    EventBus --> Sub_Subscriber
    Sub_Subscriber --> UC_Notification

    Env --> AppModule
    DockerCompose --> Postgres
    DockerCompose --> CloudStorage

    %% Click Events
    click Controllers "https://github.com/gabrielmatsan/fast-feet/tree/master/src/infra/http/controllers"
    click UC_Delivery "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/delivery/application/use-cases"
    click UC_Notification "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/notification/application/use-cases"
    click Sub_Subscriber "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/notification/application/subscribers"
    click Entities_Delivery "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/delivery/enterprise/entities"
    click Events_Delivery "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/delivery/enterprise/events"
    click Entities_Notification "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/notification/enterprise/entities"
    click RepoPorts_Delivery "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/delivery/application/repositories"
    click RepoPorts_Notification "https://github.com/gabrielmatsan/fast-feet/tree/master/src/domain/notification/application/repositories"
    click Prisma_Repos "https://github.com/gabrielmatsan/fast-feet/tree/master/src/infra/database/prisma/repositories"
    click Prisma_Mappers "https://github.com/gabrielmatsan/fast-feet/tree/master/src/infra/database/prisma/mappers"
    click Prisma_Service "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/database/prisma/prisma.service.ts"
    click DB_Module "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/database/database.module.ts"
    click Storage_Adapter "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/storage/r2-storage.ts"
    click StoragePort "https://github.com/gabrielmatsan/fast-feet/blob/master/src/domain/delivery/storage/uploader.ts"
    click Crypto_Bcrypt "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/criptography/bcrypt-hasher.ts"
    click Crypto_JWT "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/criptography/jwt-encripter.ts"
    click Crypto_Module "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/criptography/criptography.module.ts"
    click EncrypterPort "https://github.com/gabrielmatsan/fast-feet/blob/master/src/domain/delivery/criptography/encrypter.ts"
    click Auth_Strategy "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/auth/jwt-strategy.ts"
    click Auth_Guard "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/auth/jwt-auth-guard.ts"
    click Current_User "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/auth/current-user-decorator.ts"
    click HTTP_Module "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/http/http.module.ts"
    click Validation_Pipe "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/http/pipes/zod-validation-pipe.ts"
    click EventBus "https://github.com/gabrielmatsan/fast-feet/tree/master/src/infra/events"
    click AppModule "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/app.module.ts"
    click Main "https://github.com/gabrielmatsan/fast-feet/blob/master/src/infra/main.ts"
    click Env "https://github.com/gabrielmatsan/fast-feet/tree/master/src/infra/env"
    click DockerCompose "https://github.com/gabrielmatsan/fast-feet/blob/master/docker-compose.yml"

    %% Styles
    classDef domain fill:#cce5ff,stroke:#4a90e2,color:#000;
    classDef application fill:#d4edda,stroke:#28a745,color:#000;
    classDef infra fill:#fff3cd,stroke:#ffcd39,color:#000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#000;
```
