# xw2781/arcrho architecture

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

- Interactive diagram: https://gitdiagram.com/xw2781/arcrho
- Repository: https://github.com/xw2781/arcrho

## Overview

ArcRho is an actuarial data-automation platform for on-demand loss-reserving analysis. Its main workflow starts with an Excel or web request, resolves project, reserving-class, and dataset definitions against local source tables, builds a triangle or vector, and returns it for review. Actuaries then work with reserving methods, compare assumptions and versions, inspect dependencies, and select results. The graph also preserves documented SQL, scripting, and Excel integrations. Runtime wiring is based on the README and sampled excerpts; unsampled subsystem links are omitted where their callers are not established.

Main entry points: [`frontend/app_server/services/engine_calculation_service.py`](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/engine_calculation_service.py) (Calculation Service), [`frontend/app_server/services/arcrho_runtime_service.py`](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/arcrho_runtime_service.py) (Engine Runtime), [`frontend/app_server/services/dataset_service.py`](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/dataset_service.py) (Dataset Service), [`frontend/ui/shared/dataset/dataset_run_controller.js`](https://github.com/xw2781/arcrho/blob/main/frontend/ui/shared/dataset/dataset_run_controller.js) (Dataset Run)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace Data"]
  node_dataset_run["Dataset Run"]
  node_dataset_api["Dataset API<br/>[dataset_router.py]"]
  node_dataset_service["Dataset Service<br/>[dataset_service.py]"]
  node_source_tables[("CSV Source Tables")]
  node_project_config["Project Definitions"]
  node_dataset_result["Triangle / Vector"]
  node_sidecar["Dataset Metadata"]
end

subgraph group_engine["Calculation Engine"]
  node_engine_calc["Calculation Service"]
  node_engine_contract["Calculation Contract"]
  node_gateway["Calculation Gateway"]
  node_engine_runtime["Engine Runtime"]
end

subgraph group_analysis["Reserving Analysis"]
  node_dfm["Development Factor Method<br/>[dfm_main.js]"]
  node_actuarial_methods["Reserving Methods"]
  node_result_selection["Result Selection"]
  node_dependency_graph["Dependency Review"]
  node_method_compare["Method Version Compare"]
end

subgraph group_integrations["User Integrations"]
  node_excel["Excel Add-in"]
  node_web["ArcRho Web UI"]
  node_sql_editors["SQL Editors<br/>[sql_engines.js]"]
  node_scripting["Scripting &amp; Notebooks<br/>[main.js]"]
end

node_actuary(("Actuary"))
node_sql_databases[("SQL Databases")]

node_actuary -->|"requests data"| node_excel
node_actuary -->|"uses workspace"| node_web
node_excel -->|"requests dataset"| node_dataset_run
node_web -->|"runs dataset"| node_dataset_run
node_dataset_run -->|"posts run"| node_dataset_api
node_dataset_api -->|"dispatches"| node_dataset_service
node_dataset_service -->|"requests calculation"| node_engine_calc
node_engine_calc -->|"validates request"| node_engine_contract
node_engine_calc -.->|"forwards hosted request"| node_gateway
node_gateway -->|"executes hosted exchange"| node_engine_calc
node_engine_calc -->|"publishes request"| node_engine_runtime
node_engine_runtime -->|"reads source data"| node_source_tables
node_engine_runtime -->|"reads definitions"| node_project_config
node_engine_runtime -->|"builds result"| node_dataset_result
node_engine_calc -->|"returns result"| node_dataset_result
node_dataset_service -->|"records dataset metadata"| node_sidecar
node_actuary -->|"reviews factors"| node_dfm
node_actuary -->|"selects method"| node_actuarial_methods
node_actuary -->|"selects results"| node_result_selection
node_actuary -->|"traces dependencies"| node_dependency_graph
node_actuary -->|"compares versions"| node_method_compare
node_actuary -->|"runs SQL"| node_sql_editors
node_sql_editors -.->|"queries"| node_sql_databases
node_actuary -->|"runs scripts"| node_scripting

click node_web "https://github.com/xw2781/arcrho/tree/main/frontend/ui"
click node_dataset_run "https://github.com/xw2781/arcrho/blob/main/frontend/ui/shared/dataset/dataset_run_controller.js"
click node_dataset_api "https://github.com/xw2781/arcrho/blob/main/frontend/app_server/api/dataset_router.py"
click node_dataset_service "https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/dataset_service.py"
click node_engine_calc "https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/engine_calculation_service.py"
click node_engine_contract "https://github.com/xw2781/arcrho/blob/main/python-api/src/arcrho_engine_calculation_contract.py"
click node_gateway "https://github.com/xw2781/arcrho/blob/main/server-components/src/arcrho_gateway/engine_calculations.py"
click node_engine_runtime "https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/arcrho_runtime_service.py"
click node_sidecar "https://github.com/xw2781/arcrho/blob/main/python-api/src/arcrho_api/engine_dataset_sidecar_contract.py"
click node_dfm "https://github.com/xw2781/arcrho/blob/main/frontend/ui/method_pages/dfm/dfm_main.js"
click node_actuarial_methods "https://github.com/xw2781/arcrho/tree/main/frontend/ui/method_pages"
click node_result_selection "https://github.com/xw2781/arcrho/blob/main/frontend/ui/method_pages/result_selection/result_selection_main.js"
click node_dependency_graph "https://github.com/xw2781/arcrho/blob/main/frontend/ui/project_instance/project_instance_dependency_graph.js"
click node_method_compare "https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/method_review_service.py"
click node_sql_editors "https://github.com/xw2781/arcrho/blob/main/frontend/ui/arcode/shared/sql_engines.js"
click node_scripting "https://github.com/xw2781/arcrho/blob/main/frontend/ui/arcode/main.js"

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_dataset_run,node_dataset_api,node_dataset_service,node_source_tables,node_project_config,node_dataset_result,node_sidecar toneBlue
class node_engine_calc,node_engine_contract,node_gateway,node_engine_runtime,node_sql_databases toneAmber
class node_dfm,node_actuarial_methods,node_result_selection,node_dependency_graph,node_method_compare toneMint
class node_excel,node_web,node_sql_editors,node_scripting toneRose
class node_actuary toneIndigo
```

## Components

### Workspace Data

- [Dataset Run](https://github.com/xw2781/arcrho/blob/main/frontend/ui/shared/dataset/dataset_run_controller.js): `frontend/ui/shared/dataset/dataset_run_controller.js`
- [Dataset API](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/api/dataset_router.py): `frontend/app_server/api/dataset_router.py`
- [Dataset Service](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/dataset_service.py): `frontend/app_server/services/dataset_service.py`
- **CSV Source Tables**
- **Project Definitions**
- **Triangle / Vector**
- [Dataset Metadata](https://github.com/xw2781/arcrho/blob/main/python-api/src/arcrho_api/engine_dataset_sidecar_contract.py): `python-api/src/arcrho_api/engine_dataset_sidecar_contract.py`

### Calculation Engine

- [Calculation Service](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/engine_calculation_service.py): `frontend/app_server/services/engine_calculation_service.py`
- [Calculation Contract](https://github.com/xw2781/arcrho/blob/main/python-api/src/arcrho_engine_calculation_contract.py): `python-api/src/arcrho_engine_calculation_contract.py`
- [Calculation Gateway](https://github.com/xw2781/arcrho/blob/main/server-components/src/arcrho_gateway/engine_calculations.py): `server-components/src/arcrho_gateway/engine_calculations.py`
- [Engine Runtime](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/arcrho_runtime_service.py): `frontend/app_server/services/arcrho_runtime_service.py`

### Reserving Analysis

- [Development Factor Method](https://github.com/xw2781/arcrho/blob/main/frontend/ui/method_pages/dfm/dfm_main.js): `frontend/ui/method_pages/dfm/dfm_main.js`
- [Reserving Methods](https://github.com/xw2781/arcrho/tree/main/frontend/ui/method_pages): `frontend/ui/method_pages`
- [Result Selection](https://github.com/xw2781/arcrho/blob/main/frontend/ui/method_pages/result_selection/result_selection_main.js): `frontend/ui/method_pages/result_selection/result_selection_main.js`
- [Dependency Review](https://github.com/xw2781/arcrho/blob/main/frontend/ui/project_instance/project_instance_dependency_graph.js): `frontend/ui/project_instance/project_instance_dependency_graph.js`
- [Method Version Compare](https://github.com/xw2781/arcrho/blob/main/frontend/app_server/services/method_review_service.py): `frontend/app_server/services/method_review_service.py`

### User Integrations

- **Excel Add-in**
- [ArcRho Web UI](https://github.com/xw2781/arcrho/tree/main/frontend/ui): `frontend/ui`
- [SQL Editors](https://github.com/xw2781/arcrho/blob/main/frontend/ui/arcode/shared/sql_engines.js): `frontend/ui/arcode/shared/sql_engines.js`
- [Scripting & Notebooks](https://github.com/xw2781/arcrho/blob/main/frontend/ui/arcode/main.js): `frontend/ui/arcode/main.js`

### Other components

- **Actuary**
- **SQL Databases**

## Connections

- Actuary → Excel Add-in: requests data
- Actuary → ArcRho Web UI: uses workspace
- Excel Add-in → Dataset Run: requests dataset
- ArcRho Web UI → Dataset Run: runs dataset
- Dataset Run → Dataset API: posts run
- Dataset API → Dataset Service: dispatches
- Dataset Service → Calculation Service: requests calculation
- Calculation Service → Calculation Contract: validates request
- Calculation Service → Calculation Gateway: forwards hosted request
- Calculation Gateway → Calculation Service: executes hosted exchange
- Calculation Service → Engine Runtime: publishes request
- Engine Runtime → CSV Source Tables: reads source data
- Engine Runtime → Project Definitions: reads definitions
- Engine Runtime → Triangle / Vector: builds result
- Calculation Service → Triangle / Vector: returns result
- Dataset Service → Dataset Metadata: records dataset metadata
- Actuary → Development Factor Method: reviews factors
- Actuary → Reserving Methods: selects method
- Actuary → Result Selection: selects results
- Actuary → Dependency Review: traces dependencies
- Actuary → Method Version Compare: compares versions
- Actuary → SQL Editors: runs SQL
- SQL Editors → SQL Databases: queries
- Actuary → Scripting & Notebooks: runs scripts