# fabianosl1/api-plans architecture

> Architecture diagram of the GitHub repository fabianosl1/api-plans, 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/fabianosl1/api-plans
- Repository: https://github.com/fabianosl1/api-plans

## Overview

##### Project type and purpose
- This is a single‐service RESTful API (a backend microservice) for managing “plans” and “products,” built with Nest.js, TypeScript and Prisma.
- It follows a Hexagonal (Ports & Adapters) architecture, keeping the domain model isolated from framework and infrastructure concerns.

##### File structure
- Top-level:
- src/ – application code
- prisma/ – schema and migrations for the database
- docs/ – Postman/Hoppscotch collection
- Dockerfile, docker-compose.yml, entrypoint.sh – containerization and orchestration
- Inside src/: three main modules:
- auth/ – authentication logic
- plans/ – business logic around plans/products
- shared/ – cross-cutting concerns (exceptions, filters, middleware, common services)
- Each module substructure:
- application/ – DTOs and use-case classes
- domain/ – entities and repository interfaces (contracts)
- infra/ – controllers, Nest modules, and concrete repository implementations
- test/ – unit tests for use cases

##### Insights from the README
- Confirms Hexagonal layering: application, domain, infra separated per module
- Tech stack: Nest.js, Prisma, Docker, Jest/Supertest, GitHub Actions, SonarQube
- Endpoints documented in docs/api-collection.json

##### Main components & their interactions
a. Client(s) (Postman, browser, other services)
→ HTTP requests over REST
b. NestJS Application (Docker container)
- Controllers (infra layer) receive HTTP calls
- Controllers invoke Use-Case classes (application layer)
- Use-Cases operate on Domain Entities and depend on Repository interfaces (domain layer)
- Repository implementations (infra/adapters) use PrismaService to talk to the database
- Shared middleware (e.g., auth.jwt middleware) and filters handle cross-cutting concerns
c. Database (PostgreSQL managed by Prisma)
d. External services (JWT provider within shared infra, Render for hosting)

##### Architectural patterns & design principles
- Hexagonal Architecture (Ports & Adapters)
- Clear separation of concerns: controllers ⟷ use-cases ⟷ domain ⟷ adapters
- Dependency Inversion: use-cases depend on abstract repository interfaces
- Module‐based organization: auth, plans, shared

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    Client["Clients (Postman, Browser, Other Services)"]:::client

    %% NestJS Service Container
    subgraph "NestJS Service (Docker Container)" 
        direction TB

        %% Shared Module Band
        subgraph "Shared Module"
            direction TB
            Exceptions["Exceptions"]:::infra
            Filters["Filters"]:::infra
            Middleware["Middleware"]:::infra
            SharedJWT["JWT Service"]:::infra
            PrismaService["Prisma Service"]:::infra
        end

        %% Auth Module
        subgraph "Auth Module" 
            direction TB
            AuthController["AuthController"]:::controller
            AuthUseCase["AuthUseCase"]:::application
            UserEntity["User Entity"]:::domain
            UserRepoInterface["UserRepository Interface"]:::domain
            PrismaUserRepo["PrismaUserRepository"]:::infra
        end

        %% Plans Module
        subgraph "Plans Module"
            direction TB
            PlanController["PlanController"]:::controller
            ProductController["ProductController"]:::controller
            CreatePlanUC["CreatePlanUseCase"]:::application
            CreateProductUC["CreateProductUseCase"]:::application
            GetPlanUC["GetPlanUseCase"]:::application
            PlanEntity["Plan Entity"]:::domain
            ProductEntity["Product Entity"]:::domain
            PlanRepoInterface["PlanRepository Interface"]:::domain
            ProductRepoInterface["ProductRepository Interface"]:::domain
            PrismaPlanRepo["PrismaPlanRepository"]:::infra
            PrismaProductRepo["PrismaProductRepository"]:::infra
        end

        %% Wiring Controllers to Middleware and Filters
        Middleware --> AuthController
        Middleware --> PlanController
        Middleware --> ProductController
        AuthController --> Filters
        PlanController --> Filters
        ProductController --> Filters
    end

    %% Database and External Services
    PrismaService -->|SQL Queries| Database[(PostgreSQL)]:::database
    SharedJWT -->|JWT Operations| AuthModule[Auth Module]:::infra
    Database ---|Managed by Prisma| prismaSchema["schema.prisma & migrations"]:::database

    %% Data Flows
    Client -->|REST over HTTP| AuthController
    Client -->|REST over HTTP| PlanController
    Client -->|REST over HTTP| ProductController

    AuthController -->|"invoke"| AuthUseCase
    AuthUseCase -->|"depends on"| UserRepoInterface
    UserRepoInterface -->|"implemented by"| PrismaUserRepo
    PrismaUserRepo -->|"uses"| PrismaService

    PlanController -->|"invoke"| CreatePlanUC
    PlanController -->|"invoke"| CreateProductUC
    PlanController -->|"invoke"| GetPlanUC
    ProductController -->|"invoke"| CreateProductUC

    CreatePlanUC -->|"depends on"| PlanRepoInterface
    CreateProductUC -->|"depends on"| ProductRepoInterface
    GetPlanUC -->|"depends on"| PlanRepoInterface

    PlanRepoInterface -->|"implemented by"| PrismaPlanRepo
    ProductRepoInterface -->|"implemented by"| PrismaProductRepo

    PrismaPlanRepo -->|"uses"| PrismaService
    PrismaProductRepo -->|"uses"| PrismaService

    %% Click Events for Component Mapping
    click prismaSchema "https://github.com/fabianosl1/api-plans/blob/main/prisma/schema.prisma"
    click prismaSchema "https://github.com/fabianosl1/api-plans/tree/main/prisma/migrations/"
    click UserEntity "https://github.com/fabianosl1/api-plans/blob/main/src/auth/domain/entities/user.entity.ts"
    click UserRepoInterface "https://github.com/fabianosl1/api-plans/blob/main/src/auth/domain/repositories/userRepositories.ts"
    click SharedJWT "https://github.com/fabianosl1/api-plans/blob/main/src/shared/infra/services/jwt.service.ts"
    click AuthUseCase "https://github.com/fabianosl1/api-plans/blob/main/src/auth/application/use-cases/auth.ts"
    click PrismaUserRepo "https://github.com/fabianosl1/api-plans/blob/main/src/auth/infra/repositories/prisma-user.repository.ts"
    click AuthController "https://github.com/fabianosl1/api-plans/blob/main/src/auth/infra/controller/auth.controller.ts"
    click AuthModule "https://github.com/fabianosl1/api-plans/blob/main/src/auth/infra/auth.module.ts"
    click PlanController "https://github.com/fabianosl1/api-plans/blob/main/src/plans/infra/controllers/plan.controller.ts"
    click ProductController "https://github.com/fabianosl1/api-plans/blob/main/src/plans/infra/controllers/product.controller.ts"
    click PrismaPlanRepo "https://github.com/fabianosl1/api-plans/blob/main/src/plans/infra/repositories/prisma-plan.repository.ts"
    click PrismaProductRepo "https://github.com/fabianosl1/api-plans/blob/main/src/plans/infra/repositories/prisma-product.repository.ts"
    click PlanEntity "https://github.com/fabianosl1/api-plans/blob/main/src/plans/domain/entites/plan.entity.ts"
    click ProductEntity "https://github.com/fabianosl1/api-plans/blob/main/src/plans/domain/entites/product.entity.ts"
    click PlanRepoInterface "https://github.com/fabianosl1/api-plans/blob/main/src/plans/domain/repositories/plan.repository.ts"
    click ProductRepoInterface "https://github.com/fabianosl1/api-plans/blob/main/src/plans/domain/repositories/product.repository.ts"
    click Exceptions "https://github.com/fabianosl1/api-plans/blob/main/src/shared/exceptions/invalidInput.ts"
    click Filters "https://github.com/fabianosl1/api-plans/blob/main/src/shared/infra/filters/custom.filter.ts"
    click Middleware "https://github.com/fabianosl1/api-plans/blob/main/src/shared/infra/middleware/auth.middleware.ts"
    click PrismaService "https://github.com/fabianosl1/api-plans/blob/main/src/shared/infra/services/prisma.service.ts"

    %% Styles
    classDef client fill:#CCE5FF,stroke:#004085,color:#004085,shape:ellipse;
    classDef controller fill:#D4EDDA,stroke:#155724,color:#155724;
    classDef application fill:#FFF3CD,stroke:#856404,color:#856404;
    classDef domain fill:#FFF5F5,stroke:#721C24,color:#721C24;
    classDef infra fill:#E2E3E5,stroke:#383D41,color:#383D41;
    classDef database fill:#E2F0CB,stroke:#6B8E23,color:#6B8E23,shape:cylinder;
```
