# jeissemi123/monokera_service architecture

> Architecture diagram of the GitHub repository jeissemi123/monokera_service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jeissemi123/monokera_service
- Repository: https://github.com/jeissemi123/monokera_service

## Overview

##### Project Type & Purpose
- This is a backend-only, Docker-orchestrated microservices system (“Monokera”) built in Rails.
- It comprises two independent API services:
- order_service – handles order creation and uses the Outbox pattern + Sidekiq to publish events.
- customer_service – exposes customer data, consumes order.created.v1 events to update orders_count.
- Communication between services is synchronous (HTTP) for lookups and asynchronous (RabbitMQ) for events.

##### High-level Architecture & Key Components
A. External Client (e.g., curl or front-end)
B. order_service
1. API Layer
- Rails controller (POST /orders, GET /orders)
2. Hexagonal Layers (app/hex)
- Domain (e.g., Money)
- Application (CreateOrder use case)
- Infrastructure (HTTP client to customer_service, RabbitMQ publisher)
- Interfaces (Sidekiq worker publishing outbox, HTTP serializers)
3. Persistence
- Postgres orders table
- Postgres outbox_events table
4. Background Processing
- Sidekiq
C. RabbitMQ
- Exchange: orders.topic (topic)
- Routing key: order.created.v1
- Queues: customer_service.order_created (+ DLQ)
D. customer_service
1. API Layer (GET /customers/:id)
2. Hexagonal Layers
- Application: HandleOrderCreatedEvent
- Infrastructure: RabbitMQ consumer (Bunny or Sneakers)
- Domain & Persistence: customers and processed_events tables
3. Idempotency store: processed_events
E. Persistence
- Separate Postgres instance for customer_service
F. Docker Compose network
- order_service, customer_service, RabbitMQ, and two Postgres containers

##### Relationships & Data Flows
1. Client → order_service (HTTP POST /orders)
2. order_service → customer_service (HTTP GET /customers/:id)
3. order_service (DB tx) inserts Order + OutboxEvent
4. Sidekiq polls OutboxEvents → publishes message to RabbitMQ
5. RabbitMQ routes to customer_service.order_created queue
6. customer_service consumer → processes event, writes to ProcessedEvents + updates Customer.orders_count
7. Client may GET updated customer via customer_service API

##### Architectural Patterns & Design Principles
- Hexagonal (Ports & Adapters) in both services
- Outbox pattern for guaranteed, eventually consistent event publication
- Idempotent consumer pattern (processed_events)
- Separation of concerns: Controllers ↔ Use Cases ↔ Adapters ↔ Persistence
- Asynchronous message-driven integration

##### Technologies & Frameworks
- Ruby on Rails (API-only mode)
- Sidekiq for background jobs
- RabbitMQ (topic exchange)
- Docker & Docker Compose for local infra
- PostgreSQL for each service
- HTTP clients with Faraday/Net::HTTP within infrastructure adapters
- Hexagonal directory structure under app/hex

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    ExternalClient["External Client"]:::external

    %% Order Service
    subgraph "order_service (port 3000)"
        direction TB
        OC["OrdersController\n(POST /orders, GET /orders)"]:::api
        Serializer["OrderSerializer"]:::infrastructure
        subgraph "Hexagonal Layers"
            direction TB
            CreateOrderUC["CreateOrder Use Case"]:::application
            PublishEventsUC["PublishPendingEvents"]:::application
            Money["Money Domain"]:::domain
            CustomerClient["CustomerServiceClient\n(HTTP Adapter)"]:::infrastructure
            RabbitPublisher["RabbitMQPublisher\n(Messaging Adapter)"]:::infrastructure
            PublishWorker["PublishPendingWorker\n(Sidekiq Job)"]:::job
        end
        subgraph "Persistence"
            direction TB
            OrderModel["Order Model"]:::db
            OutboxModel["OutboxEvent Model"]:::db
        end
    end

    %% RabbitMQ Exchange and Queue
    RabbitMQ["RabbitMQ\nExchange: orders.topic"]:::async
    Queue["customer_service.order_created\nQueue + DLQ"]:::async

    %% Customer Service
    subgraph "customer_service (port 3001)"
        direction TB
        CC["CustomersController\n(GET /customers/:id)"]:::api
        subgraph "Hexagonal Layers"
            direction TB
            HandleOrderEventUC["HandleOrderCreatedEvent"]:::application
            OrderCreatedConsumer["order_created_consumer\n(RabbitMQ Consumer)"]:::infrastructure
        end
        subgraph "Persistence"
            direction TB
            CustomerModel["Customer Model"]:::db
            ProcessedEventModel["ProcessedEvent Model"]:::db
        end
    end

    %% Flows
    ExternalClient -->|POST /orders| OC
    OC -->|"serialize"| Serializer
    Serializer --> CreateOrderUC
    CreateOrderUC --> Money
    CreateOrderUC --> CustomerClient
    CustomerClient -->|HTTP GET /customers/:id| CC
    CreateOrderUC --> OrderModel
    CreateOrderUC --> OutboxModel
    OutboxModel --> PublishWorker
    PublishWorker --> PublishEventsUC
    PublishEventsUC --> RabbitPublisher
    RabbitPublisher -->|AMQP publish| RabbitMQ
    RabbitMQ -->|order.created.v1| Queue
    Queue --> OrderCreatedConsumer
    OrderCreatedConsumer --> HandleOrderEventUC
    HandleOrderEventUC --> CustomerModel
    HandleOrderEventUC --> ProcessedEventModel
    ExternalClient -->|GET /customers/:id| CC

    %% Click Events - order_service
    click OC "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/interfaces/http/orders_controller.rb"
    click Money "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/domain/money.rb"
    click CreateOrderUC "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/application/orders/create_order.rb"
    click PublishEventsUC "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/application/outbox/publish_pending_events.rb"
    click CustomerClient "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/infrastructure/customers/customer_service_client.rb"
    click RabbitPublisher "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/infrastructure/messaging/rabbitmq_publisher.rb"
    click PublishWorker "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/interfaces/jobs/outbox/publish_pending_worker.rb"
    click Serializer "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/hex/interfaces/http/serializers/order_serializer.rb"
    click OrderModel "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/models/order.rb"
    click OutboxModel "https://github.com/jeissemi123/monokera_service/blob/principal/order_service/app/models/outbox_event.rb"

    %% Click Events - customer_service
    click CC "https://github.com/jeissemi123/monokera_service/blob/principal/customer_service/app/hex/interfaces/http/customers_controller.rb"
    click HandleOrderEventUC "https://github.com/jeissemi123/monokera_service/blob/principal/customer_service/app/hex/application/customers/handle_order_created_event.rb"
    click OrderCreatedConsumer "https://github.com/jeissemi123/monokera_service/blob/principal/customer_service/app/hex/interfaces/consumers/order_created_consumer.rb"
    click CustomerModel "https://github.com/jeissemi123/monokera_service/blob/principal/customer_service/app/models/customer.rb"
    click ProcessedEventModel "https://github.com/jeissemi123/monokera_service/blob/principal/customer_service/app/models/processed_event.rb"

    %% Click Event - Docker Compose
    click RabbitMQ "https://github.com/jeissemi123/monokera_service/blob/principal/docker-compose.yml"

    %% Styles
    classDef external fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef application fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
    classDef domain fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef infrastructure fill:#fff3cd,stroke:#856404,stroke-width:1px
    classDef job fill:#ffeeba,stroke:#856404,stroke-width:1px
    classDef async fill:#f8d7da,stroke:#721c24,stroke-width:1px
    classDef db fill:#d1ecf1,stroke:#0c5460,stroke-width:1px
```
