# 3pslcca/3pslcca-core architecture

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

- Interactive diagram: https://gitdiagram.com/3pslcca/3pslcca-core
- Repository: https://github.com/3pslcca/3pslcca-core

## Overview

3psLCCA Core is a Python library for life-cycle cost analysis of bridge structures. The principal workflow starts with an engineer supplying project, traffic, and optional WPI data to `run_full_lcc_analysis`: inputs are normalized and validated, road-user costs are calculated (or supplied in global mode), and those results feed the life-cycle stage calculator. The returned analysis separates initial, use, reconstruction, and end-of-life costs. The sampled sources show the RUC orchestration and some stage-calculation internals; stage-specific formulas and several RUC implementations are represented only at their supported module paths.

Main entry points: [`src/three_ps_lcca_core/core/main.py`](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/main.py) (LCC entry point), [`src/three_ps_lcca_core/core/road_user_cost/main.py`](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/main.py) (RUC coordinator), [`src/three_ps_lcca_core/core/road_user_cost/carriage_width_info/carriagewayStandards.py`](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/carriage_width_info/carriagewayStandards.py) (Roadway standards), [`src/three_ps_lcca_core/core/utils/input_validator.py`](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/utils/input_validator.py) (Input validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Analysis orchestration"]
  node_analysis_api["LCC entry point<br/>[main.py]"]
  node_validation["Input validation<br/>[input_validator.py]"]
  node_analysis_result["LCC result<br/>[main.py]"]
end

subgraph group_inputs["Input contracts"]
  node_project_inputs["Project input models<br/>[input.py]"]
  node_global_inputs["Global input model<br/>[input_global.py]"]
  node_wpi_inputs["WPI input model<br/>[wpi.py]"]
end

subgraph group_ruc["Road-user costs"]
  node_ruc_coordinator["RUC coordinator<br/>[main.py]"]
  node_accident_cost["Accident costs<br/>[core.py]"]
  node_voc["Vehicle operation<br/>[core.py]"]
  node_congestion["Congestion adjustment<br/>[core.py]"]
  node_vot["Value of time<br/>[main.py]"]
  node_emissions["Carbon emissions<br/>[core.py]"]
  node_road_standards["Roadway standards"]
  node_ruc_total["Daily RUC total"]
end

subgraph group_lifecycle["Life-cycle costs"]
  node_stage_cost["Stage cost calculator<br/>[stage_cost.py]"]
  node_present_worth["Present-worth factors"]
end

node_engineer(("Engineer"))

node_engineer -->|"submits inputs"| node_analysis_api
node_analysis_api -->|"validates inputs"| node_validation
node_analysis_api -->|"parses project data"| node_project_inputs
node_analysis_api -->|"parses global data"| node_global_inputs
node_analysis_api -->|"validates WPI"| node_wpi_inputs
node_validation -->|"checks road codes"| node_road_standards
node_analysis_api -->|"requests RUC"| node_ruc_coordinator
node_ruc_coordinator -->|"calculates accidents"| node_accident_cost
node_ruc_coordinator -->|"calculates base VOC"| node_voc
node_ruc_coordinator -->|"adjusts VOC"| node_congestion
node_ruc_coordinator -->|"calculates time cost"| node_vot
node_ruc_coordinator -->|"calculates emissions"| node_emissions
node_congestion -->|"gets velocity class"| node_road_standards
node_vot -->|"gets velocity class"| node_road_standards
node_ruc_coordinator -->|"aggregates components"| node_ruc_total
node_analysis_api -->|"runs stage costs"| node_stage_cost
node_stage_cost -->|"gets discount factors"| node_present_worth
node_analysis_api -->|"returns stage results"| node_analysis_result

click node_analysis_api "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/main.py"
click node_validation "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/utils/input_validator.py"
click node_project_inputs "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/input.py"
click node_global_inputs "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/input_global.py"
click node_wpi_inputs "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/wpi.py"
click node_ruc_coordinator "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/main.py"
click node_accident_cost "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/accident_cost/core.py"
click node_voc "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/vehicle_operation_cost/core.py"
click node_congestion "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/congestion/core.py"
click node_vot "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/value_of_time/main.py"
click node_emissions "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/total_carbon_emission/core.py"
click node_road_standards "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/carriage_width_info/carriagewayStandards.py"
click node_ruc_total "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/calculate_total_ruc_per_day.py"
click node_stage_cost "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/stage_cost/stage_cost.py"
click node_present_worth "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/stage_cost/utils/present_worth_factor.py"
click node_analysis_result "https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/main.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_analysis_api,node_validation,node_analysis_result toneBlue
class node_project_inputs,node_global_inputs,node_wpi_inputs toneAmber
class node_ruc_coordinator,node_accident_cost,node_voc,node_congestion,node_vot,node_emissions,node_road_standards,node_ruc_total toneMint
class node_stage_cost,node_present_worth toneRose
class node_engineer toneIndigo
```

## Components

### Analysis orchestration

- [LCC entry point](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/main.py): `src/three_ps_lcca_core/core/main.py`
- [Input validation](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/utils/input_validator.py): `src/three_ps_lcca_core/core/utils/input_validator.py`
- [LCC result](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/main.py): `src/three_ps_lcca_core/core/main.py`

### Input contracts

- [Project input models](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/input.py): `src/three_ps_lcca_core/inputs/input.py`
- [Global input model](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/input_global.py): `src/three_ps_lcca_core/inputs/input_global.py`
- [WPI input model](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/inputs/wpi.py): `src/three_ps_lcca_core/inputs/wpi.py`

### Road-user costs

- [RUC coordinator](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/main.py): `src/three_ps_lcca_core/core/road_user_cost/main.py`
- [Accident costs](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/accident_cost/core.py): `src/three_ps_lcca_core/core/road_user_cost/accident_cost/core.py`
- [Vehicle operation](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/vehicle_operation_cost/core.py): `src/three_ps_lcca_core/core/road_user_cost/vehicle_operation_cost/core.py`
- [Congestion adjustment](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/congestion/core.py): `src/three_ps_lcca_core/core/road_user_cost/congestion/core.py`
- [Value of time](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/value_of_time/main.py): `src/three_ps_lcca_core/core/road_user_cost/value_of_time/main.py`
- [Carbon emissions](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/total_carbon_emission/core.py): `src/three_ps_lcca_core/core/road_user_cost/total_carbon_emission/core.py`
- [Roadway standards](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/carriage_width_info/carriagewayStandards.py): `src/three_ps_lcca_core/core/road_user_cost/carriage_width_info/carriagewayStandards.py`
- [Daily RUC total](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/road_user_cost/calculate_total_ruc_per_day.py): `src/three_ps_lcca_core/core/road_user_cost/calculate_total_ruc_per_day.py`

### Life-cycle costs

- [Stage cost calculator](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/stage_cost/stage_cost.py): `src/three_ps_lcca_core/core/stage_cost/stage_cost.py`
- [Present-worth factors](https://github.com/3pslcca/3pslcca-core/blob/main/src/three_ps_lcca_core/core/stage_cost/utils/present_worth_factor.py): `src/three_ps_lcca_core/core/stage_cost/utils/present_worth_factor.py`

### Other components

- **Engineer**

## Connections

- Engineer → LCC entry point: submits inputs
- LCC entry point → Input validation: validates inputs
- LCC entry point → Project input models: parses project data
- LCC entry point → Global input model: parses global data
- LCC entry point → WPI input model: validates WPI
- Input validation → Roadway standards: checks road codes
- LCC entry point → RUC coordinator: requests RUC
- RUC coordinator → Accident costs: calculates accidents
- RUC coordinator → Vehicle operation: calculates base VOC
- RUC coordinator → Congestion adjustment: adjusts VOC
- RUC coordinator → Value of time: calculates time cost
- RUC coordinator → Carbon emissions: calculates emissions
- Congestion adjustment → Roadway standards: gets velocity class
- Value of time → Roadway standards: gets velocity class
- RUC coordinator → Daily RUC total: aggregates components
- LCC entry point → Stage cost calculator: runs stage costs
- Stage cost calculator → Present-worth factors: gets discount factors
- LCC entry point → LCC result: returns stage results