zwitschi
29f16139a3
- Completed export workflow implementation (query builders, CSV/XLSX serializers, streaming API endpoints, UI modals, automated tests). - Added export modal UI and client script to trigger downloads directly from dashboard. - Documented import/export field mapping and usage guidelines in FR-008. - Updated installation guide with export environment variables, dependencies, and CLI/CI usage instructions.
16 KiB
Data Model
The data model for the system is designed to capture the essential entities and their relationships involved in mining projects. Each entity is represented as a table in the relational database, with attributes defining their properties and foreign keys establishing relationships between them.
Table of Contents
- Data Model
Relationships Diagram
erDiagram
User ||--o{ UserRole : has
UserRole ||--o{ RolePermission : has
Permission ||--o{ RolePermission : assigned_to
User ||--o{ Mandator : belongs_to
Mandator ||--o{ Project : has_many
Project ||--|| Location : located_at
Project ||--o{ MiningTechnology : uses
Project ||--o{ FinancialModel : has_many
Project ||--o{ Parameter : has_many
Project ||--o{ Scenario : has_many
ProductModel ||--o{ QualityMetric : has
FinancialModel ||--o{ CostModel : includes
FinancialModel ||--o{ RevenueModel : includes
FinancialModel ||--o{ InvestmentModel : includes
FinancialModel ||--o{ EconomicModel : includes
FinancialModel ||--o{ RiskModel : includes
MiningTechnology ||--o{ Parameter : has_many
MiningTechnology ||--o{ QualityMetric : has_many
CostModel ||--|| CAPEX : has
CostModel ||--|| OPEX : has
RevenueModel ||--o{ RevenueStream : has
RevenueModel ||--o{ ProductSale : has
Currency ||--o{ CAPEX : used_in
Currency ||--o{ OPEX : used_in
Currency ||--o{ RevenueStream : used_in
Currency ||--o{ ProductSale : used_in
Unit ||--o{ ProductModel : used_in
Unit ||--o{ QualityMetric : used_in
Unit ||--o{ Parameter : used_in
MiningTechnology ||--o{ Parameter : has_many
MiningTechnology ||--o{ QualityMetric : has_many
MiningTechnology ||--o{ MonteCarloSimulation : has_many
User
Users are individuals who have access to the Calminer system.
Each User is associated with a single Mandator and can be assigned to multiple Projects under that Mandator. Users have specific roles and permissions that determine their level of access within the system.
User Diagram
erDiagram
User {
string UserID PK
string Name
string Email
string PasswordHash
datetime CreatedAt
datetime UpdatedAt
datetime LastLogin
boolean IsActive
}
User Roles
Users can have different roles within the Calminer system, which define their permissions and access levels.
erDiagram
User ||--o{ UserRole : has
UserRole {
string RoleID PK
string RoleName
string Description
}
System Administrator
The System Administrator role is a special user role that has elevated privileges across the entire Calminer system. This role is responsible for managing system settings, configurations, managing Mandators, user accounts, and overall system maintenance.
Mandator Administrator
The Mandator Administrator role is a special user role assigned to individuals who manage a specific Mandator. This role has the authority to oversee Users and Projects within their Mandator, including user assignments and project configurations.
Project Manager
The Project Manager role is responsible for overseeing specific Projects within a Mandator. This role has permissions to manage project settings, assign Users to the Project, and monitor project progress.
Standard User
The Standard User role can participate in Projects assigned to them but has limited access to administrative functions.
Permissions
Permissions are defined based on user roles, determining what actions a user can perform within the system. Permissions include:
- View Projects
- Edit Projects
- Manage Users
- Configure System Settings
- Access Reports
- Run Simulations
- Manage Financial Models
- Export Data
- Import Data
- View Logs
- Manage Notifications
- Access API
Permissions are assigned to roles, and users inherit permissions based on their assigned roles. For this purpose, a helper entity RolePermission is defined to map roles to their respective permissions.
The Permissions entity (and RolePermission entity) is defined as follows:
erDiagram
RolePermission {
string RoleID FK
string PermissionID FK
}
Permission {
string PermissionID PK
string PermissionName
string Description
}
UserRole ||--o{ RolePermission : has
Permission ||--o{ RolePermission : assigned_to
Mandator
The Mandator entity represents organizational units or clients using the system. A Mandator can have multiple Users and Projects associated with it.
erDiagram
Mandator {
string MandatorID PK
string Name
string ContactInfo
datetime CreatedAt
datetime UpdatedAt
boolean IsActive
}
Project
The Project entity encapsulates the details of mining projects. Attributes include ProjectID, ProjectName, Description, LocationID (linking to the Location entity), CreationDate, and OwnerID (linking to the User entity). Projects can have multiple Datasets associated with them.
erDiagram
Project {
string ProjectID PK
string ProjectName
string Description
string LocationID FK
datetime CreationDate
string OwnerID FK
string Status
datetime StartDate
}
Location
The Location entity represents the geographical context of the data being mined. Locations can be linked to multiple Projects.
erDiagram
Location {
string LocationID PK
string Name
string Description
string Coordinates
string Region
string Country
}
Currency
The Currency entity defines the monetary units used in the system. Currency is used when dealing with any monetary values in Projects or Results.
erDiagram
Currency {
string CurrencyID PK
string Code
string Name
string Symbol
datetime CreatedAt
datetime UpdatedAt
boolean IsActive
}
Unit
The Unit entity defines measurement units used in the system. Units are essential for standardizing data representation across mining projects, financial models, and results.
erDiagram
Unit {
string UnitID PK
string Name
string Symbol
string Description
}
Mining Technology
The Mining Technology entity encompasses the various tools and techniques used in data mining projects. A Mining Project typically utilizes one specific Mining Technology.
erDiagram
MiningTechnology {
string TechnologyID PK
string Name
string Description
}
Product Model
The Product Model entity captures the details of products extracted or processed in mining projects. It includes attributes such as ProductID, Name, Type and UnitID (linking to the Unit entity). A Product Model can have multiple Quality Metrics associated with it.
erDiagram
ProductModel {
string ProductID PK
string Name
string Type
string UnitID FK
}
ProductModel ||--o{ QualityMetric : has
Unit ||--o{ ProductModel : used_in
Unit ||--o{ QualityMetric : used_in
Quality Metrics
Quality Metrics define the standards and specifications for products derived from mining projects. These metrics ensure that products meet industry and regulatory requirements.
For example, Quality Metrics for a mineral product may include:
- Purity Level
- Moisture Content
- Impurity Levels
- Grain Size Distribution
- Chemical Composition
- Physical Properties
These metrics are essential for assessing the value and usability of the products in various applications and markets.
erDiagram
QualityMetric {
string MetricID PK
string Name
string Description
float MinValue
float MaxValue
string UnitID FK
string AssociatedProductID FK
}
ProductModel ||--o{ QualityMetric : has
Unit ||--o{ QualityMetric : used_in
Financial Model
The Financial Model entity captures the economic aspects of mining projects. The Financial Model includes various sub-models and components that detail costs, revenues, investments, and risks associated with mining projects. Financial Models are the basis for Scenario analyses within Projects.
erDiagram
FinancialModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
Cost Model
The Cost Model details the expenses associated with mining projects, including capital expenditures (CAPEX) and operational expenditures (OPEX).
- CAPEX: Initial costs for equipment, infrastructure, and setup.
- OPEX: Ongoing costs for labor, maintenance, and operations.
erDiagram
CostModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
CAPEX {
string CAPEXID PK
float EquipmentCost
float InfrastructureCost
float SetupCost
float ContingencyCost
float TotalCAPEX
string CurrencyID FK
}
OPEX {
string OPEXID PK
float LaborCost
float MaterialsCost
float EquipmentRentalCost
float UtilitiesCost
float MaintenanceCost
float TotalOPEX
string CurrencyID FK
}
FinancialModel ||--o{ CostModel : includes
CostModel ||--|| CAPEX : has
CostModel ||--|| OPEX : has
Currency ||--o{ CAPEX : used_in
Currency ||--o{ OPEX : used_in
CAPEX
For a calculation of Capital Expenditures (CAPEX), the following attributes are included:
- EquipmentCost
- InfrastructureCost
- SetupCost
- ContingencyCost
- TotalCAPEX
- CurrencyID (Foreign Key to Currency)
OPEX
For a calculation of Operational Expenditures (OPEX), the following attributes are included:
- LaborCost
- MaterialsCost
- EquipmentRentalCost
- UtilitiesCost
- MaintenanceCost
- TotalOPEX
- CurrencyID (Foreign Key to Currency)
Revenue Model
The Revenue Model outlines the income generated from mining projects. It includes various revenue streams and product sales.
erDiagram
RevenueModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ RevenueModel : includes
RevenueStream {
string RevenueStreamID PK
string Name
string Description
float Amount
string CurrencyID FK
string AssociatedRevenueModelID FK
string Frequency
datetime StartDate
datetime EndDate
boolean IsRecurring
}
FinancialModel ||--o{ RevenueModel : includes
RevenueModel ||--o{ RevenueStream : has
Currency ||--o{ RevenueStream : used_in
Revenue Streams
Revenue streams can include product sales, service fees, and other income sources related to the mining project.
erDiagram
RevenueStream {
string RevenueStreamID PK
string Name
string Description
float Amount
string CurrencyID FK
string AssociatedRevenueModelID FK
string Frequency
datetime StartDate
datetime EndDate
boolean IsRecurring
}
Product Sales
Mining product sales represent the primary revenue stream for most mining projects. Product sales revenue is calculated based on the quantity of product sold, price per unit, and any applicable adjustments for quality or other factors like penalties for impurities. Also see Price Calculation for more details.
erDiagram
ProductSale {
string SaleID PK
string ProductID FK
float QuantitySold
float PricePerUnit
float TotalRevenue
string CurrencyID FK
datetime SaleDate
}
ProductModel ||--o{ ProductSale : has
Currency ||--o{ ProductSale : used_in
Investment Model
The Investment Model focuses on the funding and financial backing of mining projects. It includes details about investors, investment amounts, and dates.
erDiagram
InvestmentModel {
string InvestmentID PK
string InvestorID FK
string ProjectID FK
float Amount
datetime InvestmentDate
}
FinancialModel ||--o{ InvestmentModel : includes
Economic Model
The Economic Model assesses the overall economic viability and impact of mining projects. Economic indicators such as Net Present Value (NPV), Internal Rate of Return (IRR), and Payback Period are calculated within this model.
erDiagram
EconomicModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ EconomicModel : includes
Discounted Cash Flow Metrics
CalMiner standardises the computation of NPV, IRR, and Payback Period through the shared helpers in services/financial.py. The detailed algorithms, assumptions (compounding frequency, period anchoring, residual handling), and regression coverage are documented in Financial Metrics Specification. Scenario evaluation services and downstream analytics should rely on these helpers to ensure consistency across API, UI, and reporting features.
Monte Carlo Simulation
Stochastic profitability analysis builds on the deterministic helpers by sampling cash-flow distributions defined per scenario. The configuration contracts, supported distributions, and result schema are described in Monte Carlo Simulation Specification. Scenario evaluation flows should call services/simulation.py to generate iteration summaries and percentile data for reporting and visualisation features.
Risk Model
The Risk Model identifies and evaluates potential risks associated with mining projects. It includes risk factors, their probabilities, and potential impacts on project outcomes.
erDiagram
RiskModel {
string ModelID PK
string Name
string Description
string AssociatedProjectID FK
}
FinancialModel ||--o{ RiskModel : includes
Parameter
Parameters are configurable inputs used within Financial Models to simulate different economic conditions and scenarios for mining projects. Each Parameter has a name, type, default value, and is linked to a specific Technology.
erDiagram
Parameter {
string ParameterID PK
string Name
string Type
string DefaultValue
string Description
string AssociatedTechnologyID FK
}
Scenario
A Scenario represents a specific configuration or analysis case within a Project. Scenarios utilize various Financial Models and Parameters to simulate different outcomes for mining projects.
erDiagram
Scenario {
string ScenarioID PK
string Name
string Description
string AssociatedProjectID FK
}