calminer/docs/architecture/01_introduction_and_goals.md

01 — Introduction and Goals

Status: skeleton

Describe the system purpose, stakeholders, and high-level goals. Fill this file with project introduction and business/technical goals.

Overview

CalMiner is a FastAPI application that collects mining project inputs, persists scenario-specific records, and surfaces aggregated insights. The platform targets Monte Carlo driven planning, with deterministic CRUD features in place and simulation logic staged for future work.

Frontend components are server-rendered Jinja2 templates, with Chart.js powering the dashboard visualization. The backend leverages SQLAlchemy for ORM mapping to a PostgreSQL database.

Runtime Flow

1. Users navigate to form templates or API clients to manage scenarios, parameters, and operational data.
2. FastAPI routers validate payloads with Pydantic models, then delegate to SQLAlchemy sessions for persistence.
3. Simulation runs (placeholder services/simulation.py) will consume stored parameters to emit iteration results via /api/simulations/run.
4. Reporting requests POST simulation outputs to /api/reporting/summary; the reporting service calculates aggregates (count, min/max, mean, median, percentiles, standard deviation, variance, and tail-risk metrics at the 95% confidence level).
5. templates/Dashboard.html fetches summaries, renders metric cards, and plots distribution charts with Chart.js for stakeholder review.

Current implementation status (summary)

• Currency normalization, simulation scaffold, and reporting service exist; see quickstart for full status and migration instructions.

MVP Features (migrated)

The following MVP features and priorities were defined during initial planning.

Prioritized Features

1. Scenario Creation and Management (High Priority): Allow users to create, edit, and delete scenarios. Rationale: Core functionality for what-if analysis.
2. Parameter Input and Validation (High Priority): Input process parameters with validation. Rationale: Ensures data integrity for simulations.
3. Monte Carlo Simulation Run (High Priority): Execute simulations and store results. Rationale: Key differentiator for risk analysis.
4. Basic Reporting (Medium Priority): Display NPV, IRR, EBITDA from simulation results. Rationale: Essential for decision-making.
5. Cost Tracking Dashboard (Medium Priority): Visualize CAPEX and OPEX. Rationale: Helps monitor expenses.
6. Consumption Monitoring (Low Priority): Track resource consumption. Rationale: Useful for optimization.
7. User Authentication (Medium Priority): Basic login/logout. Rationale: Security for multi-user access.
8. Export Results (Low Priority): Export simulation data to CSV/PDF. Rationale: For external analysis.

Rationale for Prioritization

• High: Core simulation and scenario features first.
• Medium: Reporting and auth for usability.
• Low: Nice-to-haves after basics.