# luansmelo/e-paper architecture

> Architecture diagram of the GitHub repository luansmelo/e-paper, 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/luansmelo/e-paper
- Repository: https://github.com/luansmelo/e-paper

## Overview

##### Project type and purpose
- e-paper is a Dockerized NestJS backend service for document management, exposing a REST API documented via Swagger and storing metadata in PostgreSQL and files in MinIO.

##### File structure
- Top-level orchestration: Dockerfile, docker-compose.yml, start.sh
- src/main.ts + app.module.ts: application bootstrap & global config (Swagger, Zod)
- src/presentation: Controllers (HTTP endpoints), filters, interceptors, OpenAPI schemas
- src/application: Use-case classes, DTOs, ts-rest contracts, Zod schemas
- src/domain: Core entities and repository interfaces (hexagonal core)
- src/infrastructure:
- database/drizzle: Drizzle ORM service + repository implementations
- database/in-memory: In-memory repos for testing
- migrations: SQL and snapshots
- ioc modules: NestJS DI for database & document modules
- Configuration: src/config (global, Swagger, Multer-S3)

##### Diagramming the architecture
a. Main components (top-level “containers”)
- API Service (NestJS application)
- PostgreSQL database
- MinIO object storage
- (Optional) API client / Swagger UI

b. Layers inside the API Service
- Presentation Layer: HTTP Controllers → Validation (nestjs-zod)
- Application Layer: Use Cases (add, load, update, delete, upload)
- Domain Layer: Entities + Repository Interfaces (ports)
- Infrastructure Layer:
– Repository Adapters (Drizzle/Postgres, In-Memory)
– File Storage Adapter (Multer-S3 → MinIO)
- Bootstrapping & Configuration Modules

c. Data flow & interactions
- HTTP Request → Controller → DTO/Zod Validation → Use Case
- Use Case → Domain Entity Logic → Repository Interface → Drizzle Adapter → PostgreSQL
- File Upload Use Case → File Validation Interceptor → Multer-S3 Config → MinIO → URL returned → persisted in DB
- Swagger Module serves OpenAPI at `/api` via ts-rest contracts

d. Architectural patterns & technologies
- Hexagonal (Onion) Architecture: clear separation of concerns by layer
- Dependency Injection via NestJS modules
- Drizzle ORM for type-safe DB access
- Zod & nestjs-zod for runtime validation + type inference
- ts-rest for synchronized contracts + API docs

##### Essential elements
- Clear labels for containers, layers, modules, external services
- Call out the bootstrap sequence (`main.ts` → app.module → modules)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Client["API Client"]:::external
    SwaggerUI["Swagger UI"]:::external
    click SwaggerUI "https://github.com/luansmelo/e-paper/blob/main/src/config/swagger.config.ts"

    %% Docker Compose Orchestration
    subgraph "Docker Compose"
        direction TB
        APIService["API Service (NestJS)"]:::frontend
        Postgres[(PostgreSQL)]:::storage
        MinIO[(MinIO Object Storage)]:::object
        click APIService "https://github.com/luansmelo/e-paper/tree/main/Dockerfile"
        click APIService "https://github.com/luansmelo/e-paper/blob/main/docker-compose.yml"
        click APIService "https://github.com/luansmelo/e-paper/blob/main/start.sh"
    end

    %% API Service Layers
    subgraph "API Service (NestJS)"
        direction TB
        %% Bootstrapping & Configuration
        subgraph "Boot & Config"
            direction TB
            MainTS["main.ts"]:::infra
            AppModule["app.module.ts"]:::infra
            GlobalConfig["global.config.ts"]:::infra
            SwaggerConfig["swagger.config.ts"]:::infra
            MulterConfig["multer-s3.config.ts"]:::infra
            click MainTS "https://github.com/luansmelo/e-paper/blob/main/src/main.ts"
            click AppModule "https://github.com/luansmelo/e-paper/blob/main/src/app.module.ts"
            click GlobalConfig "https://github.com/luansmelo/e-paper/blob/main/src/config/global.config.ts"
            click SwaggerConfig "https://github.com/luansmelo/e-paper/blob/main/src/config/swagger.config.ts"
            click MulterConfig "https://github.com/luansmelo/e-paper/blob/main/src/config/multer-s3.config.ts"
        end

        %% Presentation Layer
        subgraph "Presentation Layer" 
            direction TB
            Controller["document.controller.ts"]:::frontend
            Filter["zod-validation.exception.filter.ts"]:::frontend
            Interceptor["file-validation.interceptor.ts"]:::frontend
            OAPI["document.openapi.ts"]:::frontend
            click Controller "https://github.com/luansmelo/e-paper/blob/main/src/presentation/controllers/document.controller.ts"
            click Filter "https://github.com/luansmelo/e-paper/blob/main/src/presentation/filters/zod-validation.exception.filter.ts"
            click Interceptor "https://github.com/luansmelo/e-paper/blob/main/src/presentation/interceptos/file-validation.interceptor.ts"
            click OAPI "https://github.com/luansmelo/e-paper/blob/main/src/presentation/openapi/document.openapi.ts"
        end

        %% Application Layer
        subgraph "Application Layer"
            direction TB
            Contract["document.contract.ts"]:::app
            ZodSchema["document.schema.ts"]:::app
            UseCases["use-cases"]:::app
            DTOs["DTOs"]:::app
            click Contract "https://github.com/luansmelo/e-paper/blob/main/src/application/contracts/document.contract.ts"
            click ZodSchema "https://github.com/luansmelo/e-paper/blob/main/src/application/schemas/document.schema.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/add-document.usecase.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/load-document.usecase.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/load-documents.usecase.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/update-document.usecase.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/delete-document.usecase.ts"
            click UseCases "https://github.com/luansmelo/e-paper/blob/main/src/application/usecases/upload-file.usecase.ts"
            click DTOs "https://github.com/luansmelo/e-paper/blob/main/src/application/dtos/request/add-document.dto.ts"
            click DTOs "https://github.com/luansmelo/e-paper/blob/main/src/application/dtos/request/filter.document.dto.ts"
            click DTOs "https://github.com/luansmelo/e-paper/blob/main/src/application/dtos/request/update-document.dto.ts"
            click DTOs "https://github.com/luansmelo/e-paper/blob/main/src/application/dtos/request/upload-file.dto.ts"
            click DTOs "https://github.com/luansmelo/e-paper/blob/main/src/application/dtos/response/document.response.dto.ts"
        end

        %% Domain Layer
        subgraph "Domain Layer"
            direction TB
            Entity["document.entity.ts"]:::domain
            RepositoryIFs["Repository Interfaces"]:::domain
            click Entity "https://github.com/luansmelo/e-paper/blob/main/src/domain/entities/document.entity.ts"
            click RepositoryIFs "https://github.com/luansmelo/e-paper/blob/main/src/domain/repositories/add-document.ts"
            click RepositoryIFs "https://github.com/luansmelo/e-paper/blob/main/src/domain/repositories/load-document-by-id.ts"
            click RepositoryIFs "https://github.com/luansmelo/e-paper/blob/main/src/domain/repositories/load-documents.ts"
            click RepositoryIFs "https://github.com/luansmelo/e-paper/blob/main/src/domain/repositories/update-document.ts"
            click RepositoryIFs "https://github.com/luansmelo/e-paper/blob/main/src/domain/repositories/delete-document.ts"
        end

        %% Infrastructure Layer
        subgraph "Infrastructure Layer"
            direction TB
            subgraph "Database Adapters"
                direction TB
                DrizzleService["drizzle.service.ts"]:::infra
                DrizzleRepo["document.repository.impl.ts"]:::infra
                InMemoryRepo["in-memory.document.repository.ts"]:::infra
                click DrizzleService "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/drizzle/drizzle.service.ts"
                click DrizzleRepo "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/drizzle/repositories/document.repository.impl.ts"
                click InMemoryRepo "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/in-memory/repositories/in-memory.document.repository.ts"
            end
            subgraph "Migrations"
                direction TB
                M1["0000_document.sql"]:::infra
                M2["0001_narrow_johnny_storm.sql"]:::infra
                MS1["meta/0000_snapshot.json"]:::infra
                MS2["meta/0001_snapshot.json"]:::infra
                click M1 "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/migrations/0000_document.sql"
                click M2 "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/migrations/0001_narrow_johnny_storm.sql"
                click MS1 "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/migrations/meta/0000_snapshot.json"
                click MS2 "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/database/migrations/meta/0001_snapshot.json"
            end
            subgraph "DI Modules"
                direction TB
                DBModule["database.module.ts"]:::infra
                DocModule["document.module.ts"]:::infra
                click DBModule "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/ioc/database.module.ts"
                click DocModule "https://github.com/luansmelo/e-paper/blob/main/src/infrastructure/ioc/document.module.ts"
            end
        end
    end

    %% External Services
    APIService -->|HTTP /api| SwaggerUI
    Client -->|HTTP| Controller
    Controller -->|validate→| Filter
    Filter -->|intercept→| Interceptor
    Interceptor -->|validated request| Contract
    Contract -->|typed DTOs| UseCases
    UseCases -->|domain logic| Entity
    Entity -->|persist via| RepositoryIFs
    RepositoryIFs -->|calls| DrizzleRepo
    DrizzleRepo -->|SQL| Postgres
    UseCases -->|upload file| MulterConfig
    MulterConfig -->|S3 API| MinIO
    UseCases -->|return URL| DTOs
    GlobalConfig --> MainTS
    AppModule --> Controller
    AppModule --> DBModule
    AppModule --> DocModule

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B9A,color:#003F6B
    classDef app fill:#E0F7F1,stroke:#00897B,color:#004D40
    classDef domain fill:#FFF9C4,stroke:#FBC02D,color:#F57F17
    classDef infra fill:#F1F8E9,stroke:#689F38,color:#33691E
    classDef storage fill:#E8F5E9,stroke:#2E7D32,color:#1B5E20
    classDef object fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#263238
```
