calminer/docs/architecture/06_runtime_view.md

title, description, status

title	description	status
06 — Runtime View	Describe runtime aspects: request flows, lifecycle of key interactions, and runtime components.	draft

06 — Runtime View

Overview

The runtime view focuses on the dynamic behavior of the CalMiner application during execution. It illustrates how various components interact to fulfill user requests, process data, and generate outputs. Key runtime scenarios include scenario management, parameter input handling, cost tracking, consumption tracking, production output recording, equipment management, maintenance logging, Monte Carlo simulations, and reporting.

Request Flow

1. User Interaction: A user interacts with the web application through the UI, triggering actions such as creating a scenario, inputting parameters, or generating reports.
2. API Request: The frontend sends HTTP requests (GET, POST, PUT, DELETE) to the appropriate API endpoints defined in the routes/ directory.
3. Routing: The FastAPI framework routes the incoming requests to the corresponding route handlers.
4. Service Layer: Route handlers invoke services from the services/ directory to process the business logic.
5. Database Interaction: Services interact with the database via ORM models defined in the models/ directory to perform CRUD operations.
6. Response Generation: After processing, services return data to the route handlers, which format the response (JSON or HTML) and send it back to the frontend.
7. UI Update: The frontend updates the UI based on the response, rendering new data or updating existing views.
8. Reporting Pipeline: For reporting, data is aggregated from various sources, processed to generate statistics, and presented in the dashboard using Chart.js.
9. Monte Carlo Simulations: Stochastic simulations are executed in the backend, generating probabilistic outcomes that are stored temporarily and used for risk analysis in reports.
10. Error Handling: Throughout the process, error handling mechanisms ensure that exceptions are caught and appropriate responses are sent back to the user.

Request flow diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant Service
   participant Database

   User->>Frontend: Interact with UI
   Frontend->>API: Send HTTP Request
   API->>Service: Route to Handler
   Service->>Database: Perform CRUD Operation
   Database-->>Service: Return Data
   Service-->>API: Return Processed Data
   API-->>Frontend: Send Response
   Frontend-->>User: Update UI

   participant Reporting

   Service->>Reporting: Aggregate Data
   Reporting-->>Service: Return Report Data
   Service-->>API: Return Report Response
   API-->>Frontend: Send Report Data
   Frontend-->>User: Render Report

   participant Simulation
   Service->>Simulation: Execute Monte Carlo Simulation
   Simulation-->>Service: Return Simulation Results

   Service-->>API: Return Simulation Data
   API-->>Frontend: Send Simulation Data
   Frontend-->>User: Display Simulation Results

Key Runtime Scenarios

Scenario Management

1. User accesses the scenario list via the UI.
2. The frontend sends a GET request to /api/scenarios.
3. The ScenarioService retrieves scenarios from the database.
4. The response is rendered in the UI.
5. For scenario creation, the user submits a form, triggering a POST request to /api/scenarios, which the ScenarioService processes to create a new scenario in the database.
6. The UI updates to reflect the new scenario.

Scenario management diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant ScenarioService
   participant Database

   User->>Frontend: Access Scenario List
   Frontend->>API: GET /api/scenarios
   API->>ScenarioService: Route to Handler
   ScenarioService->>Database: Retrieve Scenarios
   Database-->>ScenarioService: Return Scenarios
   ScenarioService-->>API: Return Scenario Data
   API-->>Frontend: Send Response
   Frontend-->>User: Render Scenario List

   User->>Frontend: Submit New Scenario Form
   Frontend->>API: POST /api/scenarios
   API->>ScenarioService: Route to Handler
   ScenarioService->>Database: Create New Scenario
   Database-->>ScenarioService: Confirm Creation
   ScenarioService-->>API: Return New Scenario Data
   API-->>Frontend: Send Response
   Frontend-->>User: Update UI with New Scenario

Process Parameter Input

1. User navigates to the parameter input form.
2. The frontend fetches existing parameters via a GET request to /api/parameters.
3. The ParameterService retrieves parameters from the database.
4. The response is rendered in the UI.
5. For parameter updates, the user submits a form, triggering a PUT request to /api/parameters/:id, which the ParameterService processes to update the parameter in the database.
6. The UI updates to reflect the changes.

Parameter input diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant ParameterService
   participant Database

   User->>Frontend: Navigate to Parameter Input Form
   Frontend->>API: GET /api/parameters
   API->>ParameterService: Route to Handler
   ParameterService->>Database: Retrieve Parameters
   Database-->>ParameterService: Return Parameters
   ParameterService-->>API: Return Parameter Data
   API-->>Frontend: Send Response
   Frontend-->>User: Render Parameter Form

   User->>Frontend: Submit Parameter Update Form
   Frontend->>API: PUT /api/parameters/:id
   API->>ParameterService: Route to Handler
   ParameterService->>Database: Update Parameter
   Database-->>ParameterService: Confirm Update
   ParameterService-->>API: Return Updated Parameter Data
   API-->>Frontend: Send Response
   Frontend-->>User: Update UI with Updated Parameter

Cost Tracking

1. User accesses the cost tracking view.
2. The frontend sends a GET request to /api/costs to fetch existing cost records.
3. The CostService retrieves cost data from the database.
4. The response is rendered in the UI.
5. For cost updates, the user submits a form, triggering a PUT request to /api/costs/:id, which the CostService processes to update the cost record in the database.
6. The UI updates to reflect the changes.

Cost tracking diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant CostService
   participant Database

   User->>Frontend: Access Cost Tracking View
   Frontend->>API: GET /api/costs
   API->>CostService: Route to Handler
   CostService->>Database: Retrieve Cost Records
   Database-->>CostService: Return Cost Data
   CostService-->>API: Return Cost Data
   API-->>Frontend: Send Response
   Frontend-->>User: Render Cost Tracking View

   User->>Frontend: Submit Cost Update Form
   Frontend->>API: PUT /api/costs/:id
   API->>CostService: Route to Handler
   CostService->>Database: Update Cost Record
   Database-->>CostService: Confirm Update
   CostService-->>API: Return Updated Cost Data
   API-->>Frontend: Send Response
   Frontend-->>User: Update UI with Updated Cost Data

Reporting Pipeline and UI Integration

1. Data Sources

   • Scenario-linked calculations (costs, consumption, production) produce raw figures stored in dedicated tables (capex, opex, consumption, production_output).
   • Monte Carlo simulations (currently transient) generate arrays of { "result": float } tuples that the dashboard or downstream tooling passes directly to reporting endpoints.

2. API Contract

   • POST /api/reporting/summary accepts a JSON array of result objects and validates shape through _validate_payload in routes/reporting.py.
   • On success it returns a structured payload (ReportSummary) containing count, mean, median, min/max, standard deviation, and percentile values, all as floats.

3. Service Layer

   • services/reporting.generate_report converts the sanitized payload into descriptive statistics using Python’s standard library (statistics module) to avoid external dependencies.
   • The service remains stateless; no database read/write occurs, which keeps summary calculations deterministic and idempotent.
   • Extended KPIs (surfaced in the API and dashboard):
     • variance: population variance computed as the square of the population standard deviation.
     • percentile_5 and percentile_95: lower and upper tail interpolated percentiles for sensitivity bounds.
     • value_at_risk_95: 5th percentile threshold representing the minimum outcome within a 95% confidence band.
     • expected_shortfall_95: mean of all outcomes at or below the value_at_risk_95, highlighting tail exposure.

4. UI Consumption

   • templates/Dashboard.html posts the user-provided dataset to the summary endpoint, renders metric cards for each field, and charts the distribution using Chart.js.
   • SUMMARY_FIELDS now includes variance, 5th/10th/90th/95th percentiles, and tail-risk metrics (VaR/Expected Shortfall at 95%); tooltip annotations surface the tail metrics alongside the percentile line chart.
   • Error handling surfaces HTTP failures inline so users can address malformed JSON or backend availability issues without leaving the page.

Reporting pipeline diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant ReportingService

   User->>Frontend: Input Data for Reporting
   Frontend->>API: POST /api/reporting/summary
   API->>ReportingService: Route to Handler
   ReportingService->>ReportingService: Validate Payload
   ReportingService->>ReportingService: Compute Statistics
   ReportingService-->>API: Return Report Summary
   API-->>Frontend: Send Report Summary
   Frontend-->>User: Render Report Metrics and Charts

Monte Carlo Simulation Execution

1. User initiates a Monte Carlo simulation via the UI.
2. The frontend sends a POST request to /api/simulations/run with simulation parameters.
3. The SimulationService executes the Monte Carlo logic, generating stochastic results.
4. The results are temporarily stored and returned to the frontend.
5. The UI displays the simulation results and allows users to trigger reporting based on these outcomes.
6. The reporting pipeline processes the simulation results as described above.
7. Error handling ensures that any issues during simulation execution are communicated back to the user.
8. Monte Carlo simulation diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant SimulationService

   User->>Frontend: Input Simulation Parameters
   Frontend->>API: POST /api/simulations/run
   API->>SimulationService: Route to Handler
   SimulationService->>SimulationService: Execute Monte Carlo Logic
   SimulationService-->>API: Return Simulation Results
   API-->>Frontend: Send Simulation Results
   Frontend-->>User: Render Simulation Results

Error Handling

Throughout the runtime processes, error handling mechanisms are implemented to catch exceptions and provide meaningful feedback to users. Common error scenarios include:

• Invalid input data
• Database connection issues
• Simulation execution errors
• Reporting calculation failures
• API endpoint unavailability
• Timeouts during long-running operations
• Unauthorized access attempts
• Data validation failures
• Resource not found errors

Error handling diagram:

sequenceDiagram
   participant User
   participant Frontend
   participant API
   participant Service

   User->>Frontend: Perform Action
   Frontend->>API: Send Request
   API->>Service: Route to Handler
   Service->>Service: Process Request
   alt Success
       Service-->>API: Return Data
       API-->>Frontend: Send Response
       Frontend-->>User: Update UI
   else Error
       Service-->>API: Return Error
       API-->>Frontend: Send Error Response
       Frontend-->>User: Display Error Message
   end