# hskhsmm/1milion-campaign-orchestration-system architecture

> Architecture diagram of the GitHub repository hskhsmm/1milion-campaign-orchestration-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hskhsmm/1milion-campaign-orchestration-system
- Repository: https://github.com/hskhsmm/1milion-campaign-orchestration-system

## Overview

This repository implements a Redis-first, first-come campaign participation system, with asynchronous Kafka persistence and operational recovery/monitoring capabilities. The documented request path atomically validates and reserves stock in Redis, buffers participation, then bridges events to Kafka for batched database handling. Separate batch jobs support aggregation, consistency recovery, and DLQ replay. The MCP server provides monitoring and Slack alerting. Edges follow README statements or shown source references; unsampled implementation details are not assumed.

Main entry points: [`mcp-server/detectors/p1_detector.py`](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/detectors/p1_detector.py) (Alert Detectors), [`mcp-server/tools.py`](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/tools.py) (MCP Tools), [`app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/ParticipationBridge.java`](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/ParticipationBridge.java) (Participation Bridge), [`app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ParticipationService.java`](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ParticipationService.java) (Participation Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_participation["Participation Flow"]
  node_participation_api["Participation API"]
  node_participation_service["Participation Service"]
  node_rate_limit["Rate Limiter"]
  node_redis_stock["Redis Stock"]
  node_redis_queue["Redis Queue"]
  node_bridge["Participation Bridge"]
  node_bridge_queue["Bridge Queue"]
  node_kafka["Kafka"]
  node_consumer["Event Consumer"]
end

subgraph group_operations["Campaign Operations"]
  node_campaign_service["Campaign Service"]
  node_batch_api["Batch API"]
  node_batch_jobs["Batch Jobs"]
  node_stats["Campaign Aggregation"]
end

subgraph group_recovery["Recovery Handling"]
  node_recovery_api["Recovery API"]
  node_consistency["Consistency Recovery"]
  node_dlq_api["DLQ Replay API"]
  node_dlq_replay["DLQ Replay"]
  node_dlq_messages["DLQ Messages"]
end

subgraph group_monitoring["Monitoring"]
  node_mcp_tools["MCP Tools<br/>[tools.py]"]
  node_detectors["Alert Detectors<br/>[p1_detector.py]"]
  node_monitor["Monitor Server<br/>[main.py]"]
  node_alert_state[("Alert State<br/>[state.py]")]
  node_prometheus["Prometheus"]
  node_slack["Slack"]
end

subgraph group_persistence["Persistence"]
  node_database[("MySQL RDS")]
end

node_client(("Client"))
node_operator(("Operator"))

node_client -->|"submits"| node_participation_api
node_participation_api -.->|"delegates to"| node_participation_service
node_participation_service -.->|"checks limit"| node_rate_limit
node_participation_service -->|"reserves stock"| node_redis_stock
node_redis_stock -->|"enqueues"| node_redis_queue
node_bridge -->|"claims queue"| node_redis_queue
node_bridge -->|"publishes"| node_kafka
node_kafka -->|"delivers events"| node_consumer
node_consumer -->|"batch persists"| node_database
node_bridge -.->|"uses queue service"| node_bridge_queue
node_operator -->|"starts jobs"| node_batch_api
node_batch_jobs -.->|"aggregates"| node_stats
node_operator -->|"requests recovery"| node_recovery_api
node_recovery_api -->|"invokes"| node_consistency
node_consistency -->|"reads history"| node_database
node_consistency -->|"checks stock"| node_redis_stock
node_operator -->|"starts replay"| node_dlq_api
node_dlq_api -->|"creates execution"| node_dlq_replay
node_dlq_replay -->|"republishes"| node_kafka
node_dlq_messages -.->|"stores records"| node_database
node_operator -->|"calls tools"| node_mcp_tools
node_monitor -->|"serves tools"| node_mcp_tools
node_mcp_tools -->|"dispatches checks"| node_detectors
node_detectors -->|"queries metrics"| node_prometheus
node_detectors -->|"checks cooldown"| node_alert_state
node_detectors -->|"sends alerts"| node_slack
node_mcp_tools -->|"queries metrics"| node_prometheus

click node_participation_api "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ParticipationController.java"
click node_participation_service "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ParticipationService.java"
click node_rate_limit "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RateLimitService.java"
click node_redis_stock "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisStockService.java"
click node_redis_queue "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisQueueService.java"
click node_bridge "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/ParticipationBridge.java"
click node_bridge_queue "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/BridgeQueueService.java"
click node_consumer "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/consumer/ParticipationEventConsumer.java"
click node_campaign_service "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignService.java"
click node_batch_api "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/BatchController.java"
click node_batch_jobs "https://github.com/hskhsmm/1milion-campaign-orchestration-system/tree/main/app/campaign-core/src/main/java/io/eventdriven/campaign/batch"
click node_stats "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignAggregationService.java"
click node_recovery_api "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ConsistencyRecoveryController.java"
click node_consistency "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ConsistencyRecoveryService.java"
click node_dlq_api "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/DlqReplayController.java"
click node_dlq_replay "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqReplayService.java"
click node_dlq_messages "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqMessageService.java"
click node_mcp_tools "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/tools.py"
click node_detectors "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/detectors/p1_detector.py"
click node_monitor "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/main.py"
click node_alert_state "https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/state.py"

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_participation_api,node_participation_service,node_rate_limit,node_redis_stock,node_redis_queue,node_bridge,node_bridge_queue,node_kafka,node_consumer,node_client toneBlue
class node_campaign_service,node_batch_api,node_batch_jobs,node_stats toneAmber
class node_recovery_api,node_consistency,node_dlq_api,node_dlq_replay,node_dlq_messages toneMint
class node_mcp_tools,node_detectors,node_monitor,node_alert_state,node_prometheus,node_slack toneRose
class node_database,node_operator toneIndigo
```

## Components

### Participation Flow

- [Participation API](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ParticipationController.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ParticipationController.java`
- [Participation Service](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ParticipationService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ParticipationService.java`
- [Rate Limiter](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RateLimitService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RateLimitService.java`
- [Redis Stock](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisStockService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisStockService.java`
- [Redis Queue](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisQueueService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/RedisQueueService.java`
- [Participation Bridge](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/ParticipationBridge.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/ParticipationBridge.java`
- [Bridge Queue](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/BridgeQueueService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/bridge/BridgeQueueService.java`
- **Kafka**
- [Event Consumer](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/consumer/ParticipationEventConsumer.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/consumer/ParticipationEventConsumer.java`

### Campaign Operations

- [Campaign Service](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignService.java`
- [Batch API](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/BatchController.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/BatchController.java`
- [Batch Jobs](https://github.com/hskhsmm/1milion-campaign-orchestration-system/tree/main/app/campaign-core/src/main/java/io/eventdriven/campaign/batch): `app/campaign-core/src/main/java/io/eventdriven/campaign/batch`
- [Campaign Aggregation](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignAggregationService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/CampaignAggregationService.java`

### Recovery Handling

- [Recovery API](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ConsistencyRecoveryController.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ConsistencyRecoveryController.java`
- [Consistency Recovery](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ConsistencyRecoveryService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ConsistencyRecoveryService.java`
- [DLQ Replay API](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/DlqReplayController.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/DlqReplayController.java`
- [DLQ Replay](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqReplayService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqReplayService.java`
- [DLQ Messages](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqMessageService.java): `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqMessageService.java`

### Monitoring

- [MCP Tools](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/tools.py): `mcp-server/tools.py`
- [Alert Detectors](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/detectors/p1_detector.py): `mcp-server/detectors/p1_detector.py`
- [Monitor Server](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/main.py): `mcp-server/main.py`
- [Alert State](https://github.com/hskhsmm/1milion-campaign-orchestration-system/blob/main/mcp-server/state.py): `mcp-server/state.py`
- **Prometheus**
- **Slack**

### Persistence

- **MySQL RDS**

### Other components

- **Client**
- **Operator**

## Connections

- Client → Participation API: submits (evidence: `README.md`)
- Participation API → Participation Service: delegates to (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ParticipationController.java`)
- Participation Service → Rate Limiter: checks limit
- Participation Service → Redis Stock: reserves stock (evidence: `README.md`)
- Redis Stock → Redis Queue: enqueues (evidence: `README.md`)
- Participation Bridge → Redis Queue: claims queue (evidence: `README.md`)
- Participation Bridge → Kafka: publishes (evidence: `README.md`)
- Kafka → Event Consumer: delivers events (evidence: `README.md`)
- Event Consumer → MySQL RDS: batch persists (evidence: `README.md`)
- Participation Bridge → Bridge Queue: uses queue service
- Operator → Batch API: starts jobs (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/BatchController.java`)
- Batch Jobs → Campaign Aggregation: aggregates
- Operator → Recovery API: requests recovery (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ConsistencyRecoveryController.java`)
- Recovery API → Consistency Recovery: invokes (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/ConsistencyRecoveryController.java`)
- Consistency Recovery → MySQL RDS: reads history (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ConsistencyRecoveryService.java`)
- Consistency Recovery → Redis Stock: checks stock (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/ConsistencyRecoveryService.java`)
- Operator → DLQ Replay API: starts replay (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/DlqReplayController.java`)
- DLQ Replay API → DLQ Replay: creates execution (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/api/controller/DlqReplayController.java`)
- DLQ Replay → Kafka: republishes (evidence: `app/campaign-core/src/main/java/io/eventdriven/campaign/application/service/DlqReplayService.java`)
- DLQ Messages → MySQL RDS: stores records
- Operator → MCP Tools: calls tools (evidence: `mcp-server/tools.py`)
- Monitor Server → MCP Tools: serves tools (evidence: `mcp-server/main.py`)
- MCP Tools → Alert Detectors: dispatches checks (evidence: `mcp-server/tools.py`)
- Alert Detectors → Prometheus: queries metrics (evidence: `mcp-server/detectors/p1_detector.py`)
- Alert Detectors → Alert State: checks cooldown (evidence: `mcp-server/detectors/p1_detector.py`)
- Alert Detectors → Slack: sends alerts (evidence: `mcp-server/detectors/p1_detector.py`)
- MCP Tools → Prometheus: queries metrics (evidence: `mcp-server/tools.py`)