# angelmerlino/api-hexagonal-optime architecture

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

- Interactive diagram: https://gitdiagram.com/angelmerlino/api-hexagonal-optime
- Repository: https://github.com/angelmerlino/api-hexagonal-optime

## Overview

##### Project Type and Purpose
- The project is a full-stack, microservices-oriented API platform built using a Hexagonal Architecture (also called Ports and Adapters) with Vertical Slicing and Screaming Architecture principles.
- It is divided into separate bounded contexts or microservices (e.g., Activities, Notifications, Payments, Schedules, Users, and channels-based services) with each service organized into domain-, application-, and infrastructure-related layers.
- The README emphasizes that the domain is the core and dominant part of the design, ensuring that business rules are kept independent from technical implementation.

##### Analyzing the File Structure
- At the top level, you have several directories each representing a different service or microservice (Activities, Chanels, Notifications, Payments, Schedules, Users, etc.).
- Each service typically contains:
- A “domain” folder holding the entities, repository interfaces, and custom exceptions.
- An “application” folder that defines use cases and service orchestration logic.
- An “infrastructure” or “infraestructure” folder, providing concrete implementations for databases, ORM models, external APIs (e.g., RabbitMQ, Mercado Pago, Email/WhatsApp services), and API routes.
- There are also additional folders related to migration scripts (using Alembic) and configuration files (such as database connection scripts, environment configurations, etc.) which indicate that each service is independently maintaining its own persistence logic.
- Notice also Node.js-based “Chanels” which implements messaging capabilities via RabbitMQ adapters.

##### Key Architecture Principles Reflected
- Vertical Slicing: Each microservice is built by slicing through the typical layers—domain, application, and infrastructure—instead of organizing strictly by technical layers across the entire project.
- Screaming Architecture: The domain and business use cases are clearly identifiable and act as the primary drivers of the application design.

To represent this project accurately:
a. Main Components:
- Within each microservice, subdivide the container into three main segments:
▪ Domain Layer (entities, domain models, repository interfaces, and exceptions)
▪ Application Layer (use cases, services, application logic)
▪ Infrastructure Layer (ORM, adapters to databases, external services, HTTP/API controllers/routes)
- External Integrations: Include components for external services (e.g., MySQL database, RabbitMQ message broker, Mercado Pago API, email/WhatsApp notification services, ngrok tunnels for exposure, and serverless functions such as those under Optime-aws-services and Optime-azure-fuctions).

b. Relationships and Interactions:
- Within each microservice, display communication between layers. For instance, the API controller in the infrastructure layer calls into the application layer use cases, which in turn invoke domain logic.
- Interactions that occur between microservices (such as message-publishing from the Payments or Notifications service to a RabbitMQ broker, or how the Channels service subscribes to these events).

c. Important Patterns or Design Principles:
- Hexagonal design – show the domain model surrounded by “ports” (interfaces) and “adapters” implemented in the infrastructure.
- Vertical slicing by grouping all layers for each service together rather than mixing layers across services.
- That each microservice is designed to be independently deployable, making it clear that external API calls, message queues, and database connections are isolated per context.

d. Relevant Technologies, Frameworks, and Libraries:
- Python (for most microservices) and Node.js (for the Channels service).
- Frameworks such as FastAPI (indicated by uvicorn), SQLAlchemy/ORM, and Alembic for migrations.
- RabbitMQ as the messaging broker, MySQL for the database.
- External dependencies as described in the README (e.g., Mercado Pago, third-party notification services, ngrok for tunneling, etc.).

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["API Client"]:::client

    subgraph "Activities Microservice"
        activities_infra["Infra: API Routes, MySqlActivitiesRepository"]:::infra
        activities_app["App: UseCases, Services"]:::app
        activities_domain["Domain: Entities, Repositories, Exceptions"]:::domain

        activities_infra -->|"calls"| activities_app
        activities_app -->|"executes"| activities_domain
    end

    subgraph "Chanels Microservice"
        chanels_infra["Infra: Routes, RabbitMQPublisher, Repositories"]:::infra
        chanels_app["App: UseCases"]:::app
        chanels_domain["Domain: Entities"]:::domain

        chanels_infra -->|"calls"| chanels_app
        chanels_app -->|"executes"| chanels_domain
    end

    subgraph "Notifications Microservice"
        notifications_infra["Infra: Routes, MySqlNotificationRepository, NotificationConsumer, External Services"]:::infra
        notifications_app["App: UseCases, Services"]:::app
        notifications_domain["Domain: Entities, Factories, Repositories, Exceptions"]:::domain

        notifications_infra -->|"calls"| notifications_app
        notifications_app -->|"executes"| notifications_domain
    end

    subgraph "Payments Microservice"
        payments_infra["Infra: Routes, MercadoPagoService, MySqlPaymentRepository, RabbitMQ Components, ORM"]:::infra
        payments_app["App: UseCases, Services, Event Handlers"]:::app
        payments_domain["Domain: Entities, Repositories, EventPublisher, Timestamps, Exceptions"]:::domain

        payments_infra -->|"calls"| payments_app
        payments_app -->|"executes"| payments_domain
    end

    subgraph "Schedules Microservice"
        schedules_infra["Infra: Routes, MySqlScheduleRepository, ORM"]:::infra
        schedules_app["App: UseCases, Services"]:::app
        schedules_domain["Domain: Entities, Repositories, Exceptions"]:::domain

        schedules_infra -->|"calls"| schedules_app
        schedules_app -->|"executes"| schedules_domain

        subgraph "Subject Bounded Context"
            subject_infra["Infra: Routes, MySqlSubjectRepository"]:::infra
            subject_app["App: UseCases"]:::app
            subject_domain["Domain: Entities, Repositories"]:::domain

            subject_infra -->|"calls"| subject_app
            subject_app -->|"executes"| subject_domain
        end
    end

    subgraph "Users Microservice"
        users_infra["Infra: Routes, MySqlUserRepository, RabbitMQ Components"]:::infra
        users_app["App: UseCases, Services, Event Handlers"]:::app
        users_domain["Domain: Entities, Repositories, Timestamps, Exceptions"]:::domain

        users_infra -->|"calls"| users_app
        users_app -->|"executes"| users_domain

        subgraph "Contact Subdomain"
            contact_infra["Infra: Routes, MySqlContactRepository, RabbitMQ Integration"]:::infra
            contact_app["App: UseCases"]:::app
            contact_domain["Domain: Entities, Repositories"]:::domain

            contact_infra -->|"calls"| contact_app
            contact_app -->|"executes"| contact_domain
        end
    end

    %% Connections from API Client to Microservices
    Client --> activities_infra
    Client --> chanels_infra
    Client --> notifications_infra
    Client --> payments_infra
    Client --> schedules_infra
    Client --> users_infra

    %% External Integrations
    mysql_db["MySQL Database"]:::database
    rabbitmq["RabbitMQ Broker"]:::database
    mercadopago["MercadoPago API"]:::external
    email_service["Email/WhatsApp Service"]:::external
    aws_services["AWS Serverless Functions"]:::external
    azure_functions["Azure Serverless Functions"]:::external

    %% MySQL Integrations
    activities_infra ---|dashed| mysql_db
    notifications_infra ---|dashed| mysql_db
    payments_infra ---|dashed| mysql_db
    schedules_infra ---|dashed| mysql_db
    users_infra ---|dashed| mysql_db

    %% RabbitMQ Integrations
    chanels_infra ---|dashed| rabbitmq
    payments_infra ---|dashed| rabbitmq
    users_infra ---|dashed| rabbitmq

    %% Other External Connections
    payments_infra ---|dashed| mercadopago
    notifications_infra ---|dashed| email_service

    %% Serverless Functions Connections
    Client ---|dashed| aws_services
    Client ---|dashed| azure_functions

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef domain fill:#bbf,stroke:#333,stroke-width:1px;
    classDef app fill:#bfb,stroke:#333,stroke-width:1px;
    classDef infra fill:#fbf,stroke:#333,stroke-width:1px;
    classDef external fill:#ff9,stroke:#333,stroke-width:1px;
    classDef database fill:#9ff,stroke:#333,stroke-width:1px;

    %% Click Events for Activities Microservice
    click activities_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Activities/src/activities/domain"
    click activities_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Activities/src/activities/application"
    click activities_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Activities/src/activities/infraestructure"

    %% Click Events for Chanels Microservice
    click chanels_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Chanels/src/domain/entities"
    click chanels_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Chanels/src/application/useCases"
    click chanels_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Chanels/src/infrastructure"

    %% Click Events for Notifications Microservice
    click notifications_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Notifications/src/notifications/domain"
    click notifications_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Notifications/src/notifications/application"
    click notifications_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Notifications/src/notifications/infrastructure"

    %% Click Events for Payments Microservice
    click payments_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Payments/src/payments/domain"
    click payments_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Payments/src/payments/application"
    click payments_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Payments/src/payments/infrastructure"

    %% Click Events for Schedules Microservice
    click schedules_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/schedules/domain"
    click schedules_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/schedules/application"
    click schedules_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/schedules/infraestructure"

    %% Click Events for Subject Bounded Context in Schedules
    click subject_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/subject/domain"
    click subject_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/subject/useCases"
    click subject_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Schedules/src/subject/infraestructure"

    %% Click Events for Users Microservice
    click users_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/users/domain"
    click users_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/users/application"
    click users_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/users/infrastructure"

    %% Click Events for Contact Subdomain in Users
    click contact_domain "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/contact/domain"
    click contact_app "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/contact/useCases"
    click contact_infra "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Users/src/contact/infrastructure"

    %% Click Events for External Serverless Functions
    click aws_services "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Optime-aws-services"
    click azure_functions "https://github.com/angelmerlino/api-hexagonal-optime/tree/main/Optime-azure-fuctions"
```
