# kavinkumarandroiddev/waroracle architecture

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

- Interactive diagram: https://gitdiagram.com/kavinkumarandroiddev/waroracle
- Repository: https://github.com/kavinkumarandroiddev/waroracle

## Overview

WarOracle is a Spring backend for forecasting Clash of Clans wars and producing tactical attack assignments. The main workflow accepts REST requests, gathers live war/player history, builds performance models, runs a Monte Carlo forecast, and returns predictions; a separate strategy workflow computes assignments and contingency briefings. Feedback and persistence are supporting capabilities. The README documents several architecture links; sampled source confirms key modeling, simulation, API-client, and persistence behavior, but strategy implementation and some service wiring were not excerpted.

Main entry points: [`src/main/java/com/kkdev/waroracle/service/WarOracleService.java`](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/WarOracleService.java) (War Orchestrator), [`src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java`](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java) (Performance Modeling), [`src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java`](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java) (Strategy Planner), [`src/main/java/com/kkdev/waroracle/client/ClashApiClient.java`](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/client/ClashApiClient.java) (Clash API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_player_api["Player API"]
  node_strategy_api["Strategy API"]
  node_feedback_api["Feedback API"]
  node_feedback_service["Feedback Service"]
  node_feedback_dto["Feedback DTOs"]
end

subgraph group_analysis["War Analytics"]
  node_war_oracle["War Orchestrator"]
  node_performance["Performance Modeling"]
  node_hero_power["Hero Equipment Power"]
  node_prior_calibration["Prior Calibration"]
  node_monte_carlo["Monte Carlo Engine"]
  node_performance_dtos["Performance Models"]
  node_simulation_dtos["Simulation Results"]
end

subgraph group_strategy["Strategy Planning"]
  node_strategy_service["Strategy Planner"]
  node_optimizer["Assignment Optimizer"]
  node_strategy_dtos["Strategy Briefings"]
end

subgraph group_integration["Data and Integrations"]
  node_player_service["Player Data Service<br/>[PlayerService.java]"]
  node_clan_service["Clan Data Service<br/>[ClanService.java]"]
  node_clash_client["Clash API Client"]
  node_cache[("API Cache")]
  node_persistence["War Persistence"]
  node_repositories["JPA Repositories"]
end

node_client(("REST Client"))
node_clash_api{{"Supercell Clash API"}}
node_mysql[("MySQL Store")]

node_client -->|"requests"| node_player_api
node_client -->|"requests"| node_strategy_api
node_client -->|"submits"| node_feedback_api
node_player_api -->|"delegates"| node_war_oracle
node_strategy_api -->|"delegates"| node_strategy_service
node_feedback_api -->|"delegates"| node_feedback_service
node_feedback_api -->|"accepts and returns"| node_feedback_dto
node_war_oracle -->|"builds models"| node_performance
node_performance -->|"uses"| node_hero_power
node_performance -->|"gets priors"| node_prior_calibration
node_performance -->|"produces"| node_performance_dtos
node_war_oracle -->|"runs forecast"| node_monte_carlo
node_monte_carlo -->|"returns predictions"| node_simulation_dtos
node_war_oracle -->|"fetches player data"| node_player_service
node_war_oracle -.->|"fetches clan data"| node_clan_service
node_war_oracle -->|"persists war data"| node_persistence
node_war_oracle -.->|"coordinates planning"| node_strategy_service
node_strategy_service -->|"optimizes assignments"| node_optimizer
node_strategy_service -->|"returns plan"| node_strategy_dtos
node_player_service -.->|"requests data"| node_clash_client
node_clan_service -.->|"requests data"| node_clash_client
node_clash_client -->|"reads and writes"| node_cache
node_clash_client -->|"calls"| node_clash_api
node_persistence -->|"reads and writes"| node_repositories
node_repositories -.->|"stores records"| node_mysql

click node_player_api "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/PlayerController.java"
click node_strategy_api "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/WarStrategyController.java"
click node_feedback_api "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/FeedbackController.java"
click node_war_oracle "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/WarOracleService.java"
click node_performance "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java"
click node_hero_power "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/HeroEquipmentPowerCalculator.java"
click node_prior_calibration "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/EmpiricalPriorCalibrationService.java"
click node_monte_carlo "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/MonteCarloSimulationService.java"
click node_performance_dtos "https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/model"
click node_simulation_dtos "https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/simulation"
click node_strategy_service "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java"
click node_optimizer "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/strategy/KuhnBipartiteOptimizer.java"
click node_strategy_dtos "https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/strategy"
click node_feedback_service "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/impl/FeedbackServiceImpl.java"
click node_player_service "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/PlayerService.java"
click node_clan_service "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/ClanService.java"
click node_clash_client "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/client/ClashApiClient.java"
click node_cache "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/ClashApiCacheService.java"
click node_persistence "https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/WarPersistenceService.java"
click node_repositories "https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/repository"
click node_feedback_dto "https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/feedback"

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_player_api,node_strategy_api,node_feedback_api,node_feedback_service,node_feedback_dto,node_client toneBlue
class node_war_oracle,node_performance,node_hero_power,node_prior_calibration,node_monte_carlo,node_performance_dtos,node_simulation_dtos,node_mysql toneAmber
class node_strategy_service,node_optimizer,node_strategy_dtos,node_clash_api toneMint
class node_player_service,node_clan_service,node_clash_client,node_cache,node_persistence,node_repositories toneRose
```

## Components

### REST API

- [Player API](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/PlayerController.java): `src/main/java/com/kkdev/waroracle/controller/PlayerController.java`
- [Strategy API](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/WarStrategyController.java): `src/main/java/com/kkdev/waroracle/controller/WarStrategyController.java`
- [Feedback API](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/controller/FeedbackController.java): `src/main/java/com/kkdev/waroracle/controller/FeedbackController.java`
- [Feedback Service](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/impl/FeedbackServiceImpl.java): `src/main/java/com/kkdev/waroracle/service/impl/FeedbackServiceImpl.java`
- [Feedback DTOs](https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/feedback): `src/main/java/com/kkdev/waroracle/dto/feedback`

### War Analytics

- [War Orchestrator](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/WarOracleService.java): `src/main/java/com/kkdev/waroracle/service/WarOracleService.java`
- [Performance Modeling](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java): `src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java`
- [Hero Equipment Power](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/HeroEquipmentPowerCalculator.java): `src/main/java/com/kkdev/waroracle/service/HeroEquipmentPowerCalculator.java`
- [Prior Calibration](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/EmpiricalPriorCalibrationService.java): `src/main/java/com/kkdev/waroracle/service/EmpiricalPriorCalibrationService.java`
- [Monte Carlo Engine](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/MonteCarloSimulationService.java): `src/main/java/com/kkdev/waroracle/service/MonteCarloSimulationService.java`
- [Performance Models](https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/model): `src/main/java/com/kkdev/waroracle/dto/model`
- [Simulation Results](https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/simulation): `src/main/java/com/kkdev/waroracle/dto/simulation`

### Strategy Planning

- [Strategy Planner](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java): `src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java`
- [Assignment Optimizer](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/strategy/KuhnBipartiteOptimizer.java): `src/main/java/com/kkdev/waroracle/service/strategy/KuhnBipartiteOptimizer.java`
- [Strategy Briefings](https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/dto/strategy): `src/main/java/com/kkdev/waroracle/dto/strategy`

### Data and Integrations

- [Player Data Service](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/PlayerService.java): `src/main/java/com/kkdev/waroracle/service/PlayerService.java`
- [Clan Data Service](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/ClanService.java): `src/main/java/com/kkdev/waroracle/service/ClanService.java`
- [Clash API Client](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/client/ClashApiClient.java): `src/main/java/com/kkdev/waroracle/client/ClashApiClient.java`
- [API Cache](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/ClashApiCacheService.java): `src/main/java/com/kkdev/waroracle/service/ClashApiCacheService.java`
- [War Persistence](https://github.com/kavinkumarandroiddev/waroracle/blob/main/src/main/java/com/kkdev/waroracle/service/WarPersistenceService.java): `src/main/java/com/kkdev/waroracle/service/WarPersistenceService.java`
- [JPA Repositories](https://github.com/kavinkumarandroiddev/waroracle/tree/main/src/main/java/com/kkdev/waroracle/repository): `src/main/java/com/kkdev/waroracle/repository`

### Other components

- **REST Client**
- **Supercell Clash API**
- **MySQL Store**

## Connections

- REST Client → Player API: requests (evidence: `src/main/java/com/kkdev/waroracle/controller/PlayerController.java`)
- REST Client → Strategy API: requests (evidence: `src/main/java/com/kkdev/waroracle/controller/WarStrategyController.java`)
- REST Client → Feedback API: submits (evidence: `src/main/java/com/kkdev/waroracle/controller/FeedbackController.java`)
- Player API → War Orchestrator: delegates (evidence: `src/main/java/com/kkdev/waroracle/controller/PlayerController.java`)
- Strategy API → Strategy Planner: delegates (evidence: `src/main/java/com/kkdev/waroracle/controller/WarStrategyController.java`)
- Feedback API → Feedback Service: delegates (evidence: `src/main/java/com/kkdev/waroracle/controller/FeedbackController.java`)
- Feedback API → Feedback DTOs: accepts and returns (evidence: `src/main/java/com/kkdev/waroracle/controller/FeedbackController.java`)
- War Orchestrator → Performance Modeling: builds models (evidence: `README.md`)
- Performance Modeling → Hero Equipment Power: uses (evidence: `src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java`)
- Performance Modeling → Prior Calibration: gets priors (evidence: `src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java`)
- Performance Modeling → Performance Models: produces (evidence: `src/main/java/com/kkdev/waroracle/service/PerformanceModelingService.java`)
- War Orchestrator → Monte Carlo Engine: runs forecast (evidence: `README.md`)
- Monte Carlo Engine → Simulation Results: returns predictions (evidence: `src/main/java/com/kkdev/waroracle/service/MonteCarloSimulationService.java`)
- War Orchestrator → Player Data Service: fetches player data (evidence: `src/main/java/com/kkdev/waroracle/service/WarOracleService.java`)
- War Orchestrator → Clan Data Service: fetches clan data (evidence: `src/main/java/com/kkdev/waroracle/service/WarOracleService.java`)
- War Orchestrator → War Persistence: persists war data (evidence: `src/main/java/com/kkdev/waroracle/service/WarOracleService.java`)
- War Orchestrator → Strategy Planner: coordinates planning (evidence: `src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java`)
- Strategy Planner → Assignment Optimizer: optimizes assignments (evidence: `README.md`)
- Strategy Planner → Strategy Briefings: returns plan (evidence: `src/main/java/com/kkdev/waroracle/service/strategy/WarStrategyServiceImpl.java`)
- Player Data Service → Clash API Client: requests data (evidence: `src/main/java/com/kkdev/waroracle/service/PlayerService.java`)
- Clan Data Service → Clash API Client: requests data (evidence: `src/main/java/com/kkdev/waroracle/service/ClanService.java`)
- Clash API Client → API Cache: reads and writes (evidence: `src/main/java/com/kkdev/waroracle/client/ClashApiClient.java`)
- Clash API Client → Supercell Clash API: calls (evidence: `src/main/java/com/kkdev/waroracle/client/ClashApiClient.java`)
- War Persistence → JPA Repositories: reads and writes (evidence: `src/main/java/com/kkdev/waroracle/service/WarPersistenceService.java`)
- JPA Repositories → MySQL Store: stores records
