# rummy43/ai-microservices-platform architecture

> Architecture diagram of the GitHub repository rummy43/ai-microservices-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rummy43/ai-microservices-platform
- Repository: https://github.com/rummy43/ai-microservices-platform

## Overview

This is an event-driven microservices platform whose main workflow creates a user, publishes a transactional outbox event to Kafka, and consumes it to produce an AI-personalized welcome notification with idempotency and dead-letter recovery. The graph emphasizes that workflow, the gateway’s security boundary, and the AI integration. README documentation supports the broader observability capabilities, but the supplied tree and source excerpts do not establish their runtime wiring, so they are not mapped here.

Main entry points: [`notification-service/src/main/java/com/ramesh/notification_service/service/NotificationService.java`](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/service/NotificationService.java) (Notification processing), [`api-gateway/src/main/java/com/ramesh/api_gateway/config/SecurityConfig.java`](https://github.com/rummy43/ai-microservices-platform/blob/main/api-gateway/src/main/java/com/ramesh/api_gateway/config/SecurityConfig.java) (Gateway routes and secures requests), [`user-service/src/main/java/com/ramesh/user_service/service/impl/UserServiceImpl.java`](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/impl/UserServiceImpl.java) (User operations), [`notification-service/src/main/java/com/ramesh/notification_service/kafka/KafkaConsumerService.java`](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/kafka/KafkaConsumerService.java) (Event consumer and retries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["API Gateway"]
  node_gateway["Gateway routes and secures requests"]
  node_identity["Identity propagation"]
end

subgraph group_users["User Service"]
  node_user_controller["User API"]
  node_user_service["User operations"]
  node_user_store[("User database")]
  node_outbox_service["Outbox event capture"]
  node_outbox_store[("Outbox table")]
  node_outbox_publisher["Outbox publisher"]
  node_event_publisher["Kafka event publisher"]
end

subgraph group_notify["Notification Service"]
  node_consumer["Event consumer and retries"]
  node_notification_service["Notification processing"]
  node_processed_store[("Processed-event records")]
  node_notification_store[("Notification audit log")]
  node_ai_client["AI enrichment client"]
  node_dlt_store[("Dead-letter records")]
  node_dlt_reprocessor["Dead-letter reprocessor"]
end

subgraph group_ai["AI Enrichment"]
  node_ai_controller["Enrichment API<br/>[AiController.java]"]
  node_ai_service["Enrichment service"]
end

node_client(("API client"))
node_kafka["Kafka topics"]
node_ollama["Ollama local LLM"]

node_client -->|"sends request"| node_gateway
node_gateway -->|"propagates identity"| node_identity
node_gateway -->|"routes user API"| node_user_controller
node_gateway -->|"routes notification API"| node_notification_service
node_user_controller -->|"invokes"| node_user_service
node_user_service -->|"persists user"| node_user_store
node_user_service -->|"records event"| node_outbox_service
node_outbox_service -->|"writes event"| node_outbox_store
node_outbox_publisher -->|"reads pending events"| node_outbox_store
node_outbox_publisher -->|"publishes event"| node_event_publisher
node_event_publisher -->|"sends event"| node_kafka
node_kafka -->|"delivers event"| node_consumer
node_consumer -->|"processes event"| node_notification_service
node_consumer -->|"records exhausted failures"| node_dlt_store
node_notification_service -->|"checks and records"| node_processed_store
node_notification_service -->|"writes audit log"| node_notification_store
node_notification_service -->|"requests enrichment"| node_ai_client
node_ai_client -->|"calls enrichment API"| node_ai_controller
node_ai_controller -->|"invokes"| node_ai_service
node_ai_service -->|"generates content"| node_ollama
node_dlt_reprocessor -->|"loads and updates"| node_dlt_store
node_dlt_reprocessor -->|"replays event"| node_notification_service

click node_gateway "https://github.com/rummy43/ai-microservices-platform/blob/main/api-gateway/src/main/java/com/ramesh/api_gateway/config/SecurityConfig.java"
click node_identity "https://github.com/rummy43/ai-microservices-platform/blob/main/api-gateway/src/main/java/com/ramesh/api_gateway/filter/IdentityPropagationFilter.java"
click node_user_controller "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/controller/UserController.java"
click node_user_service "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/impl/UserServiceImpl.java"
click node_user_store "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/repository/UserRepository.java"
click node_outbox_service "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/OutboxEventService.java"
click node_outbox_store "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/repository/OutboxEventRepository.java"
click node_outbox_publisher "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/OutboxPublisherService.java"
click node_event_publisher "https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/kafka/EventPublisher.java"
click node_consumer "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/kafka/KafkaConsumerService.java"
click node_notification_service "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/service/NotificationService.java"
click node_processed_store "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/ProcessedEventRepository.java"
click node_notification_store "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/NotificationLogRepository.java"
click node_ai_client "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/ai/AiEnrichmentClient.java"
click node_dlt_store "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/DeadLetterEventRepository.java"
click node_dlt_reprocessor "https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/service/DltReprocessorService.java"
click node_ai_controller "https://github.com/rummy43/ai-microservices-platform/blob/main/ai-service/src/main/java/com/ramesh/ai_service/controller/AiController.java"
click node_ai_service "https://github.com/rummy43/ai-microservices-platform/blob/main/ai-service/src/main/java/com/ramesh/ai_service/service/AiEnrichmentService.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gateway,node_identity,node_client toneBlue
class node_user_controller,node_user_service,node_user_store,node_outbox_service,node_outbox_store,node_outbox_publisher,node_event_publisher toneAmber
class node_consumer,node_notification_service,node_processed_store,node_notification_store,node_ai_client,node_dlt_store,node_dlt_reprocessor toneMint
class node_ai_controller,node_ai_service toneRose
class node_kafka,node_ollama toneIndigo
```

## Components

### API Gateway

- [Gateway routes and secures requests](https://github.com/rummy43/ai-microservices-platform/blob/main/api-gateway/src/main/java/com/ramesh/api_gateway/config/SecurityConfig.java): `api-gateway/src/main/java/com/ramesh/api_gateway/config/SecurityConfig.java`
- [Identity propagation](https://github.com/rummy43/ai-microservices-platform/blob/main/api-gateway/src/main/java/com/ramesh/api_gateway/filter/IdentityPropagationFilter.java): `api-gateway/src/main/java/com/ramesh/api_gateway/filter/IdentityPropagationFilter.java`

### User Service

- [User API](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/controller/UserController.java): `user-service/src/main/java/com/ramesh/user_service/controller/UserController.java`
- [User operations](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/impl/UserServiceImpl.java): `user-service/src/main/java/com/ramesh/user_service/service/impl/UserServiceImpl.java`
- [User database](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/repository/UserRepository.java): `user-service/src/main/java/com/ramesh/user_service/repository/UserRepository.java`
- [Outbox event capture](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/OutboxEventService.java): `user-service/src/main/java/com/ramesh/user_service/service/OutboxEventService.java`
- [Outbox table](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/repository/OutboxEventRepository.java): `user-service/src/main/java/com/ramesh/user_service/repository/OutboxEventRepository.java`
- [Outbox publisher](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/service/OutboxPublisherService.java): `user-service/src/main/java/com/ramesh/user_service/service/OutboxPublisherService.java`
- [Kafka event publisher](https://github.com/rummy43/ai-microservices-platform/blob/main/user-service/src/main/java/com/ramesh/user_service/kafka/EventPublisher.java): `user-service/src/main/java/com/ramesh/user_service/kafka/EventPublisher.java`

### Notification Service

- [Event consumer and retries](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/kafka/KafkaConsumerService.java): `notification-service/src/main/java/com/ramesh/notification_service/kafka/KafkaConsumerService.java`
- [Notification processing](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/service/NotificationService.java): `notification-service/src/main/java/com/ramesh/notification_service/service/NotificationService.java`
- [Processed-event records](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/ProcessedEventRepository.java): `notification-service/src/main/java/com/ramesh/notification_service/repository/ProcessedEventRepository.java`
- [Notification audit log](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/NotificationLogRepository.java): `notification-service/src/main/java/com/ramesh/notification_service/repository/NotificationLogRepository.java`
- [AI enrichment client](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/ai/AiEnrichmentClient.java): `notification-service/src/main/java/com/ramesh/notification_service/ai/AiEnrichmentClient.java`
- [Dead-letter records](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/repository/DeadLetterEventRepository.java): `notification-service/src/main/java/com/ramesh/notification_service/repository/DeadLetterEventRepository.java`
- [Dead-letter reprocessor](https://github.com/rummy43/ai-microservices-platform/blob/main/notification-service/src/main/java/com/ramesh/notification_service/service/DltReprocessorService.java): `notification-service/src/main/java/com/ramesh/notification_service/service/DltReprocessorService.java`

### AI Enrichment

- [Enrichment API](https://github.com/rummy43/ai-microservices-platform/blob/main/ai-service/src/main/java/com/ramesh/ai_service/controller/AiController.java): `ai-service/src/main/java/com/ramesh/ai_service/controller/AiController.java`
- [Enrichment service](https://github.com/rummy43/ai-microservices-platform/blob/main/ai-service/src/main/java/com/ramesh/ai_service/service/AiEnrichmentService.java): `ai-service/src/main/java/com/ramesh/ai_service/service/AiEnrichmentService.java`

### Other components

- **API client**
- **Kafka topics**
- **Ollama local LLM**

## Connections

- API client → Gateway routes and secures requests: sends request
- Gateway routes and secures requests → Identity propagation: propagates identity
- Gateway routes and secures requests → User API: routes user API
- Gateway routes and secures requests → Notification processing: routes notification API
- User API → User operations: invokes
- User operations → User database: persists user
- User operations → Outbox event capture: records event
- Outbox event capture → Outbox table: writes event
- Outbox publisher → Outbox table: reads pending events
- Outbox publisher → Kafka event publisher: publishes event
- Kafka event publisher → Kafka topics: sends event
- Kafka topics → Event consumer and retries: delivers event
- Event consumer and retries → Notification processing: processes event
- Event consumer and retries → Dead-letter records: records exhausted failures
- Notification processing → Processed-event records: checks and records
- Notification processing → Notification audit log: writes audit log
- Notification processing → AI enrichment client: requests enrichment
- AI enrichment client → Enrichment API: calls enrichment API
- Enrichment API → Enrichment service: invokes
- Enrichment service → Ollama local LLM: generates content
- Dead-letter reprocessor → Dead-letter records: loads and updates
- Dead-letter reprocessor → Notification processing: replays event