allucanget/calminer-docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add functional requirements for profitability, Monte Carlo simulation, and Capex/Opex management; enhance user guide with planners

Browse Source
This commit is contained in:
zwitschi
2025-11-13 09:20:10 +01:00
parent d3597bc8c9
commit fb6be6d84f
11 changed files with 526 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
architecture/08_concepts.md
View File

@@ -48,10 +48,6 @@ CalMiner aims to provide a comprehensive platform for mining project scenario an
- [Data Synchronization](#data-synchronization)
- [Error Handling](#error-handling)
- [Reporting and Analytics](#reporting-and-analytics)
- [Data Visualization](#data-visualization)
- [Custom Reports](#custom-reports)
- [Real-time Analytics](#real-time-analytics)
- [Historical Analysis](#historical-analysis)
## Multitenancy
@@ -245,20 +241,4 @@ Robust error handling mechanisms are implemented to manage integration failures
## Reporting and Analytics
The Calminer system includes comprehensive reporting and analytics capabilities to support data-driven decision-making.
### Data Visualization
The system provides tools for visualizing data through charts, graphs, and dashboards, making it easier to identify trends and insights.
### Custom Reports
Users can create custom reports based on specific criteria, allowing for tailored analysis of project performance and resource utilization.
### Real-time Analytics
The system supports real-time data processing and analytics, enabling users to access up-to-date information and respond quickly to changing conditions.
### Historical Analysis
The system maintains a history of key metrics and events, allowing for retrospective analysis and identification of long-term trends.
The Calminer system includes comprehensive reporting and analytics capabilities to support data-driven decision-making. Detailed [Reporting and Analytics](08_concepts/11_reporting_analytics.md) documentation is available.

121
architecture/08_concepts/02_data_model.md
View File

@@ -27,11 +27,10 @@ Represents authenticated platform users with optional elevated privileges.
**Relationships:**
- `role_assignments`: Many-to-many with Role via UserRole
- `roles`: Many-to-many with Role (viewonly)
#### Role
Role encapsulating a set of permissions.
Defines user roles for role-based access control (RBAC).
**Table:** `roles`
@@ -143,6 +142,124 @@ Line-item financial assumption attached to a scenario.
- `scenario`: Many-to-one with Scenario
### Project and Scenario Models
#### ProjectCapexSnapshot
Project-level snapshot capturing aggregated initial capital expenditure metrics.
**Table:** `project_capex_snapshots`
| Attribute | Type | Description |
| ---------------------- | --------------------------------- | ------------------------------------------------------- |
| id | Integer (PK) | Primary key |
| project_id | Integer (FK → projects.id) | Associated project |
| created_by_id | Integer (FK → users.id, nullable) | User that triggered persistence |
| calculation_source | String(64), nullable | Originating workflow identifier (UI, API, etc.) |
| calculated_at | DateTime | Timestamp the calculation completed |
| currency_code | String(3), nullable | Currency for totals |
| total_capex | Numeric(18,2), nullable | Aggregated capex before contingency |
| contingency_pct | Numeric(12,6), nullable | Applied contingency percentage |
| contingency_amount | Numeric(18,2), nullable | Monetary contingency amount |
| total_with_contingency | Numeric(18,2), nullable | Capex total after contingency |
| component_count | Integer, nullable | Number of normalized components captured |
| payload | JSON, nullable | Serialized component breakdown and calculation metadata |
| created_at | DateTime | Record creation timestamp |
| updated_at | DateTime | Last update timestamp |
**Relationships:**
- `project`: Many-to-one with Project
- `created_by`: Many-to-one with User (nullable)
#### ScenarioCapexSnapshot
Scenario-level snapshot storing detailed initial capex results.
**Table:** `scenario_capex_snapshots`
| Attribute | Type | Description |
| ---------------------- | --------------------------------- | ------------------------------------------------------- |
| id | Integer (PK) | Primary key |
| scenario_id | Integer (FK → scenarios.id) | Associated scenario |
| created_by_id | Integer (FK → users.id, nullable) | User that triggered persistence |
| calculation_source | String(64), nullable | Originating workflow identifier |
| calculated_at | DateTime | Timestamp the calculation completed |
| currency_code | String(3), nullable | Currency for totals |
| total_capex | Numeric(18,2), nullable | Aggregated capex before contingency |
| contingency_pct | Numeric(12,6), nullable | Applied contingency percentage |
| contingency_amount | Numeric(18,2), nullable | Monetary contingency amount |
| total_with_contingency | Numeric(18,2), nullable | Capex total after contingency |
| component_count | Integer, nullable | Number of normalized components captured |
| payload | JSON, nullable | Serialized component breakdown and calculation metadata |
| created_at | DateTime | Record creation timestamp |
| updated_at | DateTime | Last update timestamp |
**Relationships:**
- `scenario`: Many-to-one with Scenario
- `created_by`: Many-to-one with User (nullable)
#### ProjectProcessingOpexSnapshot
Project-level snapshot persisting recurring processing opex metrics.
**Table:** `project_processing_opex_snapshots`
| Attribute | Type | Description |
| ------------------------ | --------------------------------- | ------------------------------------------------------- |
| id | Integer (PK) | Primary key |
| project_id | Integer (FK → projects.id) | Associated project |
| created_by_id | Integer (FK → users.id, nullable) | User that triggered persistence |
| calculation_source | String(64), nullable | Originating workflow identifier |
| calculated_at | DateTime | Timestamp the calculation completed |
| currency_code | String(3), nullable | Currency for totals |
| overall_annual | Numeric(18,2), nullable | Total annual processing opex |
| escalated_total | Numeric(18,2), nullable | Escalated cost across the evaluation horizon |
| annual_average | Numeric(18,2), nullable | Average annual cost over the horizon |
| evaluation_horizon_years | Integer, nullable | Number of years included in the timeline |
| escalation_pct | Numeric(12,6), nullable | Escalation percentage applied |
| apply_escalation | Boolean | Flag indicating whether escalation was applied |
| component_count | Integer, nullable | Number of normalized components captured |
| payload | JSON, nullable | Serialized component breakdown and calculation metadata |
| created_at | DateTime | Record creation timestamp |
| updated_at | DateTime | Last update timestamp |
**Relationships:**
- `project`: Many-to-one with Project
- `created_by`: Many-to-one with User (nullable)
#### ScenarioProcessingOpexSnapshot
Scenario-level snapshot persisting recurring processing opex metrics.
**Table:** `scenario_processing_opex_snapshots`
| Attribute | Type | Description |
| ------------------------ | --------------------------------- | ------------------------------------------------------- |
| id | Integer (PK) | Primary key |
| scenario_id | Integer (FK → scenarios.id) | Associated scenario |
| created_by_id | Integer (FK → users.id, nullable) | User that triggered persistence |
| calculation_source | String(64), nullable | Originating workflow identifier |
| calculated_at | DateTime | Timestamp the calculation completed |
| currency_code | String(3), nullable | Currency for totals |
| overall_annual | Numeric(18,2), nullable | Total annual processing opex |
| escalated_total | Numeric(18,2), nullable | Escalated cost across the evaluation horizon |
| annual_average | Numeric(18,2), nullable | Average annual cost over the horizon |
| evaluation_horizon_years | Integer, nullable | Number of years included in the timeline |
| escalation_pct | Numeric(12,6), nullable | Escalation percentage applied |
| apply_escalation | Boolean | Flag indicating whether escalation was applied |
| component_count | Integer, nullable | Number of normalized components captured |
| payload | JSON, nullable | Serialized component breakdown and calculation metadata |
| created_at | DateTime | Record creation timestamp |
| updated_at | DateTime | Last update timestamp |
**Relationships:**
- `scenario`: Many-to-one with Scenario
- `created_by`: Many-to-one with User (nullable)
#### SimulationParameter
Probability distribution settings for scenario simulations.

39
architecture/08_concepts/11_reporting_analytics.md Normal file
View File

@@ -0,0 +1,39 @@
# Reporting and Analytics
The Calminer application provides robust reporting and analytics features designed to help users visualize and interpret mining project data effectively.
## Dashboard Generation
Users can create and customize dashboards that display key metrics and performance indicators related to mining projects. Dashboards support various visualization types, including charts, graphs, and tables, and allow users to drill down into specific data points for deeper analysis.
## Report Creation
The system enables users to create detailed reports that summarize project scenarios, financial analyses, and simulation results. Reports can be exported in multiple formats, including PDF and Excel, for easy sharing and presentation.
## Data Visualization Tools
The system provides tools for visualizing data through charts, graphs, and dashboards, making it easier to identify trends and insights. Users can interact with visualizations to explore data in more detail.
## Analytics Engine
The backend analytics engine processes large datasets and performs complex calculations, including Monte Carlo simulations, to provide users with probabilistic assessments of project outcomes.
### Real-time Analytics
The system supports real-time data processing and analytics, enabling users to access up-to-date information and respond quickly to changing conditions.
### Historical Analysis
The system maintains a history of key metrics and events, allowing for retrospective analysis and identification of long-term trends.
## Custom Reports
Users can create custom reports based on specific criteria, allowing for tailored analysis of project performance and resource utilization.
## User-Friendly Interface
The reporting and analytics features are accessible through an intuitive web interface, allowing users to navigate reports and dashboards seamlessly.
## Integration with Scenario Management
Reporting tools are tightly integrated with the scenario management system, enabling users to generate reports directly from specific project scenarios and compare results across different configurations.