289 lines
12 KiB
Markdown
289 lines
12 KiB
Markdown
---
|
||
title: "06 — Runtime View"
|
||
description: "Describe runtime aspects: request flows, lifecycle of key interactions, and runtime components."
|
||
status: 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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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:
|
||
|
||
```mermaid
|
||
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
|
||
```
|