calminer/docs/architecture/08_concepts.md

title, description, status

title	description	status
08 — Concepts	Document key concepts, domain models, and terminology used throughout the architecture documentation.	draft

08 — Concepts

Key Concepts

Scenario

A scenario represents a distinct mining project configuration, encapsulating all relevant parameters, costs, consumption, production outputs, equipment, maintenance logs, and simulation results. Each scenario is independent, allowing users to model and analyze different mining strategies.

Parameterization

Parameters are defined for each scenario to capture inputs such as resource consumption rates, production targets, cost factors, and equipment specifications. Parameters can have fixed values or be linked to probability distributions for stochastic simulations.

Monte Carlo Simulation

The Monte Carlo simulation engine allows users to perform risk analysis by running multiple iterations of a scenario with varying input parameters based on defined probability distributions. This helps in understanding the range of possible outcomes and their associated probabilities.

Domain Model

The domain model consists of the following key entities:

• Scenario: Represents a mining project configuration.
• Parameter: Input values for scenarios, which can be fixed or probabilistic.
• Cost: Tracks capital and operational expenditures.
• Consumption: Records resource usage.
• ProductionOutput: Captures production metrics.
• Equipment: Represents mining equipment associated with a scenario.
• Maintenance: Logs maintenance events for equipment.
• SimulationResult: Stores results from Monte Carlo simulations.
• Distribution: Defines probability distributions for stochastic parameters.
• User: Represents application users and their roles.
• Report: Generated reports summarizing scenario analyses.
• Dashboard: Visual representation of key performance indicators and metrics.
• AuditLog: Tracks changes and actions performed within the application.
• Notification: Alerts and messages related to scenario events and updates.
• Tag: Labels for categorizing scenarios and other entities.
• Attachment: Files associated with scenarios, such as documents or images.
• Version: Tracks different versions of scenarios and their configurations.

Detailed Domain Models

See Domain Models document for detailed class diagrams and entity relationships.

Data Model Highlights

• scenario: central entity describing a mining scenario; owns relationships to cost, consumption, production, equipment, and maintenance tables.
• capex, opex: monetary tracking linked to scenarios.
• consumption: resource usage entries parameterized by scenario and description.
• parameter: scenario inputs with base value and optional distribution linkage via distribution_id, distribution_type, and JSON distribution_parameters to support simulation sampling.
• production_output: production metrics per scenario.
• equipment and maintenance: equipment inventory and maintenance events with dates/costs.
• simulation_result: staging table for future Monte Carlo outputs (not yet populated by run_simulation).

Foreign keys secure referential integrity between domain tables and their scenarios, enabling per-scenario analytics.

Detailed Data Models

See Data Models document for detailed ER diagrams and table descriptions.