# 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](#data-model)
  - [Table of Contents](#table-of-contents)
  - [Relationships Diagram](#relationships-diagram)
  - [User](#user)
    - [User Diagram](#user-diagram)
    - [User Roles](#user-roles)
      - [System Administrator](#system-administrator)
      - [Mandator Administrator](#mandator-administrator)
      - [Project Manager](#project-manager)
      - [Standard User](#standard-user)
    - [Permissions](#permissions)
  - [Mandator](#mandator)
  - [Project](#project)
  - [Location](#location)
  - [Currency](#currency)
  - [Unit](#unit)
  - [Mining Technology](#mining-technology)
  - [Product Model](#product-model)
    - [Quality Metrics](#quality-metrics)
  - [Financial Model](#financial-model)
    - [Cost Model](#cost-model)
      - [CAPEX](#capex)
      - [OPEX](#opex)
    - [Revenue Model](#revenue-model)
      - [Revenue Streams](#revenue-streams)
      - [Product Sales](#product-sales)
    - [Investment Model](#investment-model)
    - [Economic Model](#economic-model)
      - [Discounted Cash Flow Metrics](#discounted-cash-flow-metrics)
    - [Risk Model](#risk-model)
  - [Parameter](#parameter)
  - [Scenario](#scenario)

## Relationships Diagram

```mermaid
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

```mermaid
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.

```mermaid
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:

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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](../../specifications/price_calculation.md) for more details.

```mermaid
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.

```mermaid
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.

```mermaid
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](../../specifications/financial_metrics.md). 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](../../specifications/monte_carlo_simulation.md). 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.

```mermaid
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.

```mermaid
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.

```mermaid
erDiagram
    Scenario {
        string ScenarioID PK
        string Name
        string Description
        string AssociatedProjectID FK
    }
```