# jgdev/clean-architecture-backend architecture

> Architecture diagram of the GitHub repository jgdev/clean-architecture-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jgdev/clean-architecture-backend
- Repository: https://github.com/jgdev/clean-architecture-backend

## Overview

##### Main Components
- Client / Request Source: This could be a UI application (or any HTTP client) that sends requests to the API. Additionally, there’s a CLI tool (src/bin/create-user.ts) used for user creation.
- API Gateway / HTTP Server:
– The API layer is handled in the “src/infrastructure/api” directory, which contains bootstrap files, controllers, middlewares, and route definitions (with different versions in the routes/v1 and routes/v2 directories).
– Include the serverless configuration (serverless.yml) for deployments on AWS, plus the HTTP server (npm run dev:http) when running in development mode.
- Business Logic / Core Layer:
– Found in “src/core”, this layer encapsulates domain entities (User, Record, Operation), error handling and primary use-cases (such as CreateRecordUseCase, CreateUserSessionUseCase, etc.).
– This layer forms the heart of the calculator functionality and the cost deduction mechanism.
- Data Persistence Layer:
– The “prisma” directory contains schema definitions and migrations that set up the database structure.
– In “src/infrastructure/database”, repositories integrate with the database using Prisma (for operations, records, and users).
- Caching Layer:
– Redis is used for caching, with a specific implementation found in “src/infrastructure/database/RedisCacheRepository.ts”. This can be illustrated as a separate component to support faster data retrieval.
- Operation Services:
– Located in “src/lib/services/operations”, these components (such as OperationAdditionImpl, OperationDivisionImpl, etc.) encapsulate the specific logic for each calculator operation and are wired into the business logic side.
- Optional External Services:
– If any operations (for instance, the random string generation) rely on external APIs (like RandomORG), highlight those integration points.

##### Relationships and Interactions
- Clients send HTTP requests to the API Gateway/HTTP Server.
- The API layer (controllers) processes requests, delegates to the corresponding use-cases in the core layer, and makes calls to the repositories (data persistence) or cache as needed.
- The core layer enforces business rules (e.g., checking user credit before performing an operation) and orchestrates the necessary operations.
- When persistence is required, the core interacts with the database layer, and caching can be used to optimize frequent lookups.
- For the serverless deployment, note that the API layer is wrapped with serverless functions — indicating that the same interactions occur but in the context of AWS Lambda (or equivalent) via the serverless framework.

##### Architectural Patterns and Design Principles
- Layered Architecture: Clear separation into API/infrastructure, domain/business logic (core), and data access (prisma/database).
- Dependency Inversion: The “src/core” defines interfaces and domain contracts while the “src/infrastructure” provides concrete implementations (e.g., for repositories and caching).
- Microservice-readiness: Although currently a single service, its components (API, business logic, database, and caching) are modular enough to be separated if needed.
- Serverless Deployment: A flexible design to run locally or on AWS with minimal changes.

##### Relevant Technologies and Frameworks
- Node.js with TypeScript as the programming platform.
- Prisma for database migration and ORM.
- Redis for caching operations.
- Docker Compose for easy local setup (as described in the README).
- Serverless Framework for AWS deployments.
- Testing frameworks (jest, as indicated by jest.config.js and the tests structure).

##### Detailed Component Separation
- API Layer:
– Controllers (e.g., CreateRecordController, RemoveRecordController)
– Routes (v1, v2)
– Middlewares (e.g., errorHandler, logger, session)
– HTTP bootstrapping and serverless integration.
- Business Logic/Core:
– Domain Entities (User, Record, Operation)
– Use-Cases (CreateRecord, ListRecords, etc.)
– Error handling (ValidationError, AuthorizationError, etc.)
- Infrastructure / Data:
– Database connectivity through Prisma (database migrations, schema.prisma)
– Redis caching (RedisCacheRepository)
– Repositories wrapping data access.
- Operations Library:
– A set of implementations to process each arithmetic operation, providing clear operation-specific logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client / Request Source"
        A1("HTTP Client"):::client
        A2("CLI Tool (create-user.ts)"):::client
    end

    %% API Layer
    subgraph "API Gateway / HTTP Server"
        B1("Controllers"):::api
        B2("Middlewares"):::api
        B3("Routes & Bootstrapping"):::api
        B4("Serverless Integration"):::api
        B5("API Gateway / HTTP Server"):::api
    end

    %% Business Logic / Core Layer
    subgraph "Business Logic Layer"
        C1("Domain Entities (User, Record, Operation)"):::core
        C2("Use-Cases & Error Handling"):::core
        C3("Business Logic / Core Layer"):::core
    end

    %% Data Persistence and Caching Layer
    subgraph "Data & Persistence Layer"
        D1("Prisma ORM / Database"):::db
        D2("Database Repositories"):::db
        D3("Caching (Redis)"):::cache
    end

    %% Operation Services Layer
    subgraph "Operation Services Layer"
        E1("Arithmetic Operations Implementation"):::ops
        E2("External Service: RandomORG"):::external
    end

    %% Deployment & Infrastructure Layer
    subgraph "Deployment & Infrastructure"
        F1("Local Deployment (Docker Compose)"):::deployment
        F2("Serverless on AWS"):::deployment
    end

    %% Connections between layers
    %% Clients -> API
    A1 -->|"HTTP-request"| B5
    A2 -->|"CLI-userCreation"| B5

    %% API -> Business Logic
    B5 -->|"Invokes Use-Cases"| C3

    %% Business Logic -> Data Persistence & Caching
    C3 -->|"Calls Repositories"| D2
    C3 -->|"Cache Lookups"| D3

    %% Data Repositories use ORM
    D2 -->|"Uses ORM"| D1

    %% Business Logic -> Operation Services
    C3 -->|"Delegates Calculation"| E1
    E1 -->|"Fetches RandomString"| E2

    %% API Deployment channels
    F1 -->|"Runs API Locally"| B5
    F2 -->|"Runs API as Lambda"| B5

    %% Click Events
    click A2 "https://github.com/jgdev/clean-architecture-backend/blob/main/src/bin/create-user.ts"
    click B5 "https://github.com/jgdev/clean-architecture-backend/tree/main/src/infrastructure/api"
    click C3 "https://github.com/jgdev/clean-architecture-backend/tree/main/src/core"
    click D2 "https://github.com/jgdev/clean-architecture-backend/tree/main/src/infrastructure/database"
    click D3 "https://github.com/jgdev/clean-architecture-backend/blob/main/src/infrastructure/database/RedisCacheRepository.ts"
    click D1 "https://github.com/jgdev/clean-architecture-backend/tree/main/prisma"
    click E1 "https://github.com/jgdev/clean-architecture-backend/tree/main/src/lib/services/operations"

    %% Class Definitions for Colors
    classDef client fill:#f9c2ff,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef db fill:#ffe5b4,stroke:#333,stroke-width:2px;
    classDef cache fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef ops fill:#e6ccff,stroke:#333,stroke-width:2px;
    classDef external fill:#ddf,stroke:#333,stroke-width:2px;
    classDef deployment fill:#c6f6d5,stroke:#333,stroke-width:2px;
```
