How jeissemi123/monokera_service works
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