zwitschi
1af654de1f
- Create .gitignore to exclude specific project files and directories. - Add CONTRIBUTING.md with guidelines for contributing to the project. - Update README.md to reflect changes in usage section and contact information. - Introduce 08_concepts.md outlining cross-cutting concepts in the architecture. - Add 02_data_model.md detailing the data model and relationships. - Implement 03_security.md to describe security measures and practices. - Establish 08_ui_design.md for user interface design principles. - Document quality requirements in 10_quality_requirements.md. - Identify risks and technical debts in 11_technical_risks.md. - Create a glossary in 12_glossary.md for project-specific terms. - Include about-arc42.md to explain the arc42 documentation template. - Define price calculation variables and formula in price_calculation.md. - Introduce ADR template in adr.md for documenting architecture decisions.
530 lines
15 KiB
Markdown
530 lines
15 KiB
Markdown
# 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)
|
|
- [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
|
|
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
### 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
|
|
}
|
|
```
|