How angelmerlino/api-hexagonal-optime works
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.).