# juanpabloleonf/microservice-album-song architecture

> Architecture diagram of the GitHub repository juanpabloleonf/microservice-album-song, 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/juanpabloleonf/microservice-album-song
- Repository: https://github.com/juanpabloleonf/microservice-album-song

## Overview

##### Main Components
- API / REST Entry Point: Represent the REST controllers responsible for accepting HTTP requests. In this project, these are in the infrastructure layer under “app/src/infrastructure/inputs/rest/controllers” (album_controller.py and song_controller.py). Also include the REST DTO mappers.
- Application Layer: Represent the “app/src/application” directory which contains the business logic, including DTOs (data transfer objects), handlers, mappers, and utility functions. This is where the incoming request data is processed.
- Domain Layer: Capture the core of the business logic, including the domain models (album_model.py, song_model.py), the persistence interfaces (i_persistence_album.py, i_persistence_song.py), and the use cases (use_case_album.py, use_case_song.py). This layer is independent of external systems.
- Infrastructure / Output Layer: Represent the MySQL adapter layer found under “app/src/infrastructure/outputs/mysql”, which includes entities, repositories, and mappers that transform domain objects to database representations. This emphasizes the separation from business logic.
- Configuration & Deployment: Include the configuration settings (CORS, Swagger, environment variables, middleware) in “app/configuration” and the project’s deployment aspects – note the Dockerfile, docker-compose.yml, and main.py that bootstraps the FastAPI server using uvicorn.

##### Relationships and Interactions
- Present a clear interaction between the application layer and the domain layer. Emphasize that business rules are enforced by use cases and domain services, using interfaces (ports).
- That the domain layer interfaces into persistence by calling the interfaces defined for repositories, which the infrastructure layer actually implements.
- That the infrastructure layer uses adapters and mappers to convert objects between the domain and the database (MySQL) representations.
- Finally, include configuration components feeding into all layers (e.g., dependency injection and environment configurations), ensuring that global error handling and security (CORS, encryption) are also represented.

##### Architectural Patterns and Design Principles
- Hexagonal architecture (ports and adapters) pattern. Group the layers around the central domain logic.
- Separation of concerns—controllers handle I/O, the application layer encapsulates business processing and coordination, and the domain layer remains free of external dependencies.
- Dependency injection, which is used to decouple implementations from abstractions, evidenced by the Injector modules in “app/configuration”.

##### Relevant Technologies
- Docker and docker-compose, which are essential for containerizing and deploying the microservice.
- Usage of Cryptography for sensitive data handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    EC("External Client/API Consumer"):::external

    %% API/REST Layer
    subgraph "API/REST Layer"
        AC1("Controller: album_controller.py"):::api
        AC2("Controller: song_controller.py"):::api
        REST_DTO("REST DTO & Mappers"):::api
    end

    %% Application Layer
    subgraph "Application Layer"
        APP_DTO("DTOs"):::application
        HANDLERS("Handlers"):::application
        APP_MAPPERS("Mappers"):::application
        UTILS("Utility Functions"):::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        MODELS("Models (album_model.py, song_model.py)"):::domain
        USECASES("Use Cases"):::domain
        PERSIST_IFACE("Persistence Interfaces"):::domain
        SERVICES("Domain Services"):::domain
    end

    %% Infrastructure / Output Layer
    subgraph "Infrastructure Layer"
        ADAPTERS("MySQL Adapters"):::infrastructure
        ENTITIES("Entities"):::infrastructure
        INFRA_MAPPERS("MySQL Mappers"):::infrastructure
        REPOSITORIES("Repositories"):::infrastructure
        SETTINGS("MySQL Settings"):::infrastructure
    end

    %% Configuration & Deployment
    subgraph "Configuration & Deployment"
        CONFIG("Global Config & DI"):::config
        DOCKER("Docker: Dockerfile & docker-compose"):::config
        MAIN("Main Bootstrapping (main.py)"):::config
    end

    %% External Systems
    DB("MySQL Database"):::external

    %% Connections
    EC -->|"HTTP_Request"| AC1
    EC -->|"HTTP_Request"| AC2

    AC1 -->|"validate_request"| HANDLERS
    AC2 -->|"validate_request"| HANDLERS
    REST_DTO -->|"maps_data"| HANDLERS

    HANDLERS -->|"invokes"| USECASES
    APP_DTO -->|"transforms_to_domain"| MODELS
    APP_MAPPERS -->|"maps_to_domain"| MODELS
    UTILS -->|"assists"| USECASES

    USECASES -->|"calls_interface"| PERSIST_IFACE

    PERSIST_IFACE -->|"implemented_by"| REPOSITORIES
    REPOSITORIES -->|"uses_mapper"| INFRA_MAPPERS
    INFRA_MAPPERS -->|"maps_to_entity"| ENTITIES
    ENTITIES -->|"configured_by"| SETTINGS
    REPOSITORIES -->|"CRUD_operations"| DB

    CONFIG -->|"injects_into"| HANDLERS
    CONFIG -->|"injects_into"| REPOSITORIES
    MAIN -->|"bootstraps_server"| AC1
    MAIN -->|"bootstraps_server"| AC2
    DOCKER -->|"containerizes"| MAIN

    %% Styling Classes
    classDef external fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef api fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef application fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef domain fill:#fff5cc,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#ffe0cc,stroke:#333,stroke-width:2px;
    classDef config fill:#e6e6e6,stroke:#333,stroke-width:2px;

    %% Click Events
    click AC1 "https://github.com/juanpabloleonf/microservice-album-song/blob/main/app/src/infrastructure/inputs/rest/controllers/album_controller.py"
    click AC2 "https://github.com/juanpabloleonf/microservice-album-song/blob/main/app/src/infrastructure/inputs/rest/controllers/song_controller.py"
    click REST_DTO "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/inputs/rest/dto"

    click APP_DTO "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/application/dto"
    click HANDLERS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/application/handlers"
    click APP_MAPPERS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/application/mappers"
    click UTILS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/application/utils"

    click MODELS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/domain/models"
    click PERSIST_IFACE "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/domain/persistence"
    click USECASES "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/domain/useCases"
    click SERVICES "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/domain/services"

    click ADAPTERS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/outputs/mysql/adapters"
    click ENTITIES "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/outputs/mysql/entities"
    click INFRA_MAPPERS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/outputs/mysql/mappers"
    click REPOSITORIES "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/outputs/mysql/repositories"
    click SETTINGS "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/src/infrastructure/outputs/mysql/settings"

    click CONFIG "https://github.com/juanpabloleonf/microservice-album-song/tree/main/app/configuration"
    click MAIN "https://github.com/juanpabloleonf/microservice-album-song/blob/main/main.py"
    click DOCKER "https://github.com/juanpabloleonf/microservice-album-song/tree/main/docker/Dockerfile"
```
