# justice-ma/rotdb architecture

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

- Interactive diagram: https://gitdiagram.com/justice-ma/rotdb
- Repository: https://github.com/justice-ma/rotdb

## Overview

rot_db is a RuneScape 3 combat-damage calculator: users configure an ability and combat setup, then request detailed damage or batch comparisons. The documented calculation stages are represented by request mapping, context construction, and ordered damage pipelines; the React setup and API client are shown as the user-facing entry. Other documented capabilities include local saved presets and lightweight session analytics. Source excerpts establish the batch-to-engine path and selected UI/API links; other documented or tree-visible links are marked unverified where their callers were not sampled.

Main entry points: [`src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java) (Calculation engine), [`frontend/src/api/api.js`](https://github.com/justice-ma/rotdb/blob/main/frontend/src/api/api.js) (API client), [`src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java`](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java) (Batch calculation), [`frontend/src/App.jsx`](https://github.com/justice-ma/rotdb/blob/main/frontend/src/App.jsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Calculator UI"]
  node_app["App shell<br/>[App.jsx]"]
  node_calcpage["Ability calculator"]
  node_settings["Combat setup<br/>[CombatSettings.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_preset_ui["Preset selector<br/>[PresetSelector.jsx]"]
end

subgraph group_api["Application API"]
  node_damage_api["Damage endpoints"]
  node_batch_service["Batch calculation"]
  node_request_map["Request mapping"]
  node_equipment_store[("Equipment data")]
end

subgraph group_engine["Damage calculation"]
  node_damage_request["Calculation request<br/>[DamageRequest.java]"]
  node_context["Combat context"]
  node_engine_core["Calculation engine"]
  node_pre_pipeline["Pre-critical stages"]
  node_post_pipeline["Post-critical stages"]
  node_damage_result["Damage results<br/>[DamageResult.java]"]
  node_ability_catalog["Ability catalog<br/>[AbilityId.java]"]
end

subgraph group_support["User services"]
  node_preset_api["Preset endpoints"]
  node_preset_service["Preset service<br/>[PresetService.java]"]
  node_preset_store[("Saved presets")]
  node_auth_service["Authentication<br/>[AuthService.java]"]
  node_auth_store[("User records")]
  node_heartbeat_api["Analytics endpoints"]
  node_heartbeat_service["Activity tracking"]
  node_activity_memory[("Active sessions")]
end

node_user(("Calculator user"))

node_user -.->|"uses"| node_app
node_app -->|"renders"| node_calcpage
node_calcpage -->|"configures"| node_settings
node_settings -->|"loads options"| node_api_client
node_calcpage -->|"requests calculations"| node_api_client
node_api_client -.->|"posts requests"| node_damage_api
node_damage_api -.->|"dispatches batch"| node_batch_service
node_batch_service -->|"maps request"| node_request_map
node_batch_service -->|"calculates each"| node_engine_core
node_request_map -.->|"creates request"| node_damage_request
node_engine_core -->|"builds context"| node_context
node_engine_core -->|"runs stages"| node_pre_pipeline
node_engine_core -->|"runs stages"| node_post_pipeline
node_engine_core -->|"maps result"| node_damage_result
node_ability_catalog -->|"identifies abilities"| node_batch_service
node_user -.->|"selects setup"| node_preset_ui
node_preset_ui -.->|"manages presets"| node_preset_api
node_preset_api -->|"delegates"| node_preset_service
node_preset_service -->|"gets current user"| node_auth_service
node_preset_service -->|"reads and writes"| node_preset_store
node_auth_service -->|"reads and writes"| node_auth_store
node_app -->|"sends heartbeat"| node_api_client
node_api_client -->|"posts heartbeat"| node_heartbeat_api
node_heartbeat_api -.->|"records activity"| node_heartbeat_service
node_heartbeat_service -->|"tracks clients"| node_activity_memory
node_engine_core -.->|"loads equipment"| node_equipment_store

click node_app "https://github.com/justice-ma/rotdb/blob/main/frontend/src/App.jsx"
click node_calcpage "https://github.com/justice-ma/rotdb/blob/main/frontend/src/pages/AbilityCalculation.jsx"
click node_settings "https://github.com/justice-ma/rotdb/blob/main/frontend/src/components/CombatSettings.jsx"
click node_api_client "https://github.com/justice-ma/rotdb/blob/main/frontend/src/api/api.js"
click node_damage_api "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/api/controller/DamageController.java"
click node_batch_service "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java"
click node_request_map "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/api/mapper/DamageRequestMapper.java"
click node_damage_request "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/DamageRequest.java"
click node_context "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/context/ContextBuilder.java"
click node_engine_core "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java"
click node_pre_pipeline "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/PreCriticalPipeline.java"
click node_post_pipeline "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/PostCriticalPipeline.java"
click node_damage_result "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/DamageResult.java"
click node_ability_catalog "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/shared/ability/AbilityId.java"
click node_equipment_store "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/persistence/repository/EquipmentRepository.java"
click node_preset_ui "https://github.com/justice-ma/rotdb/blob/main/frontend/src/components/PresetSelector.jsx"
click node_preset_api "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/api/PresetController.java"
click node_preset_service "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/application/PresetService.java"
click node_preset_store "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/persistence/UserPresetRepository.java"
click node_auth_service "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/auth/application/AuthService.java"
click node_auth_store "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/auth/persistence/UserRepository.java"
click node_heartbeat_api "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/api/AnalyticsController.java"
click node_heartbeat_service "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/application/HeartbeatService.java"
click node_activity_memory "https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/application/HeartbeatService.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_app,node_calcpage,node_settings,node_api_client,node_preset_ui,node_user toneBlue
class node_damage_api,node_batch_service,node_request_map,node_equipment_store toneAmber
class node_damage_request,node_context,node_engine_core,node_pre_pipeline,node_post_pipeline,node_damage_result,node_ability_catalog toneMint
class node_preset_api,node_preset_service,node_preset_store,node_auth_service,node_auth_store,node_heartbeat_api,node_heartbeat_service,node_activity_memory toneRose
```

## Components

### Calculator UI

- [App shell](https://github.com/justice-ma/rotdb/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Ability calculator](https://github.com/justice-ma/rotdb/blob/main/frontend/src/pages/AbilityCalculation.jsx): `frontend/src/pages/AbilityCalculation.jsx`
- [Combat setup](https://github.com/justice-ma/rotdb/blob/main/frontend/src/components/CombatSettings.jsx): `frontend/src/components/CombatSettings.jsx`
- [API client](https://github.com/justice-ma/rotdb/blob/main/frontend/src/api/api.js): `frontend/src/api/api.js`
- [Preset selector](https://github.com/justice-ma/rotdb/blob/main/frontend/src/components/PresetSelector.jsx): `frontend/src/components/PresetSelector.jsx`

### Application API

- [Damage endpoints](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/api/controller/DamageController.java): `src/main/java/com/rotdb/calculation/api/controller/DamageController.java`
- [Batch calculation](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java): `src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java`
- [Request mapping](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/api/mapper/DamageRequestMapper.java): `src/main/java/com/rotdb/calculation/api/mapper/DamageRequestMapper.java`
- [Equipment data](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/persistence/repository/EquipmentRepository.java): `src/main/java/com/rotdb/calculation/persistence/repository/EquipmentRepository.java`

### Damage calculation

- [Calculation request](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/DamageRequest.java): `src/main/java/com/rotdb/calculation/domain/model/DamageRequest.java`
- [Combat context](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/context/ContextBuilder.java): `src/main/java/com/rotdb/calculation/domain/model/context/ContextBuilder.java`
- [Calculation engine](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java): `src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`
- [Pre-critical stages](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/PreCriticalPipeline.java): `src/main/java/com/rotdb/calculation/domain/engine/PreCriticalPipeline.java`
- [Post-critical stages](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/engine/PostCriticalPipeline.java): `src/main/java/com/rotdb/calculation/domain/engine/PostCriticalPipeline.java`
- [Damage results](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/calculation/domain/model/DamageResult.java): `src/main/java/com/rotdb/calculation/domain/model/DamageResult.java`
- [Ability catalog](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/shared/ability/AbilityId.java): `src/main/java/com/rotdb/shared/ability/AbilityId.java`

### User services

- [Preset endpoints](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/api/PresetController.java): `src/main/java/com/rotdb/presets/api/PresetController.java`
- [Preset service](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/application/PresetService.java): `src/main/java/com/rotdb/presets/application/PresetService.java`
- [Saved presets](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/presets/persistence/UserPresetRepository.java): `src/main/java/com/rotdb/presets/persistence/UserPresetRepository.java`
- [Authentication](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/auth/application/AuthService.java): `src/main/java/com/rotdb/auth/application/AuthService.java`
- [User records](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/auth/persistence/UserRepository.java): `src/main/java/com/rotdb/auth/persistence/UserRepository.java`
- [Analytics endpoints](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/api/AnalyticsController.java): `src/main/java/com/rotdb/analytics/api/AnalyticsController.java`
- [Activity tracking](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/application/HeartbeatService.java): `src/main/java/com/rotdb/analytics/application/HeartbeatService.java`
- [Active sessions](https://github.com/justice-ma/rotdb/blob/main/src/main/java/com/rotdb/analytics/application/HeartbeatService.java): `src/main/java/com/rotdb/analytics/application/HeartbeatService.java`

### Other components

- **Calculator user**

## Connections

- Calculator user → App shell: uses
- App shell → Ability calculator: renders (evidence: `frontend/src/App.jsx`)
- Ability calculator → Combat setup: configures (evidence: `frontend/src/pages/AbilityCalculation.jsx`)
- Combat setup → API client: loads options (evidence: `frontend/src/components/CombatSettings.jsx`)
- Ability calculator → API client: requests calculations (evidence: `frontend/src/pages/AbilityCalculation.jsx`)
- API client → Damage endpoints: posts requests (evidence: `README.md`)
- Damage endpoints → Batch calculation: dispatches batch (evidence: `src/main/java/com/rotdb/calculation/api/controller/DamageController.java`)
- Batch calculation → Request mapping: maps request (evidence: `src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java`)
- Batch calculation → Calculation engine: calculates each (evidence: `src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java`)
- Request mapping → Calculation request: creates request (evidence: `src/main/java/com/rotdb/calculation/api/mapper/DamageRequestMapper.java`)
- Calculation engine → Combat context: builds context (evidence: `src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`)
- Calculation engine → Pre-critical stages: runs stages (evidence: `src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`)
- Calculation engine → Post-critical stages: runs stages (evidence: `src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`)
- Calculation engine → Damage results: maps result (evidence: `src/main/java/com/rotdb/calculation/domain/engine/CalculationEngine.java`)
- Ability catalog → Batch calculation: identifies abilities (evidence: `src/main/java/com/rotdb/calculation/application/service/DamageBatchService.java`)
- Calculator user → Preset selector: selects setup
- Preset selector → Preset endpoints: manages presets
- Preset endpoints → Preset service: delegates (evidence: `src/main/java/com/rotdb/presets/api/PresetController.java`)
- Preset service → Authentication: gets current user (evidence: `src/main/java/com/rotdb/presets/application/PresetService.java`)
- Preset service → Saved presets: reads and writes (evidence: `src/main/java/com/rotdb/presets/application/PresetService.java`)
- Authentication → User records: reads and writes (evidence: `src/main/java/com/rotdb/auth/application/AuthService.java`)
- App shell → API client: sends heartbeat (evidence: `frontend/src/App.jsx`)
- API client → Analytics endpoints: posts heartbeat (evidence: `frontend/src/api/api.js`)
- Analytics endpoints → Activity tracking: records activity
- Activity tracking → Active sessions: tracks clients (evidence: `src/main/java/com/rotdb/analytics/application/HeartbeatService.java`)
- Calculation engine → Equipment data: loads equipment (evidence: `README.md`)