Add comprehensive documentation for CalMiner, including architecture, development setup, MVP features, implementation plan, and testing strategy

README.md

@@ -1,3 +1,71 @@
 # CalMiner
 
 A web application to plan mining projects and estimate costs, returns and profitability.
+
+## Tech Stack
+
+- **Backend**: Python 3.10+ (FastAPI)
+- **Database**: PostgreSQL
+- **Frontend**: (TBD)
+- **Testing**: pytest
+
+## Planned Features
+
+- **Scenario Management**: The database supports different scenarios for what-if analysis, with parent-child relationships between scenarios.
+- **Monte Carlo Simulation**: The system can perform Monte Carlo simulations for risk analysis and probabilistic forecasting.
+- **Stochastic Variables**: The model handles uncertainty by defining variables with probability distributions.
+- **Cost Tracking**: It tracks capital (`capex`) and operational (`opex`) expenditures.
+- **Consumption Tracking**: It monitors the consumption of resources like chemicals, fuel, water, and scrap materials.
+- **Production Output**: The database stores production results, including tons produced, recovery rates, and revenue.
+- **Process Parameters**: It allows for defining and storing various parameters for different processes and scenarios.
+- **Equipment Management**: The system manages equipment and their operational data.
+- **Maintenance Logging**: It includes a log for equipment maintenance events.
+
+## Database Objects
+
+The database is composed of several tables that store different types of information. All tables are under schema `bricsium_platform`. See `structure.sql` for full DDL. Here are some of the most important ones:
+
+- **CAPEX** — `bricsium_platform.capex`: Stores data on capital expenditures.
+- **OPEX** — `bricsium_platform.opex`: Contains information on operational expenditures.
+- **Chemical consumption** — `bricsium_platform.chemical_consumption`: Tracks the consumption of chemical reagents.
+- **Fuel consumption** — `bricsium_platform.fuel_consumption`: Records the amount of fuel consumed.
+- **Water consumption** — `bricsium_platform.water_consumption`: Monitors the use of water.
+- **Scrap consumption** — `bricsium_platform.scrap_consumption`: Tracks the consumption of scrap materials.
+- **Production output** — `bricsium_platform.production_output`: Stores data on production output, such as tons produced and recovery rates.
+- **Equipment operation** — `bricsium_platform.equipment_operation`: Contains operational data for each piece of equipment.
+- **Ore batch** — `bricsium_platform.ore_batch`: Stores information on ore batches, including their grade and other characteristics.
+- **Exchange rate** — `bricsium_platform.exchange_rate`: Contains currency exchange rates.
+- **Simulation result** — `bricsium_platform.simulation_result`: Stores the results of the Monte Carlo simulations.
+
+## Static Parameters
+
+These are values that are not expected to change frequently and are used for configuration purposes. Some examples include:
+
+- **Currencies**: `currency_code`, `currency_name`.
+- **Distribution types**: `distribution_name`.
+- **Units**: `unit_name`, `unit_symbol`, `unit_system`, `conversion_to_base`.
+- **Parameter categories**: `category_name`.
+- **Material types**: `type_name`, `category`.
+- **Chemical reagents**: `reagent_name`, `chemical_formula`.
+- **Fuel**: `fuel_name`.
+- **Water**: `water_type`.
+- **Scrap material**: `scrap_name`.
+
+## Variables
+
+These are dynamic data points that are recorded over time and used in calculations and simulations. Some examples include:
+
+- **CAPEX**: `amount`.
+- **OPEX**: `amount`.
+- **Chemical consumption**: `quantity`, `efficiency`, `waste_factor`.
+- **Fuel consumption**: `quantity`.
+- **Water consumption**: `quantity`.
+- **Scrap consumption**: `quantity`.
+- **Production output**: `tons_produced`, `recovery_rate`, `metal_content`, `metallurgical_loss`, `net_revenue`.
+- **Equipment operation**: `hours_operated`, `downtime_hours`.
+- **Ore batch**: `ore_grade`, `moisture`, `sulfur`, `chlorine`.
+- **Exchange rate**: `rate`.
+- **Parameter values**: `value`.
+- **Simulation result**: NPV (`npv`), IRR (`irr`), EBITDA (`ebitda`), `net_revenue`.
+- **Cementation parameters**: `temperature`, pH (`ph`), `reaction_time`, `copper_concentration`, `iron_surface_area`.
+- **Precipitate product**: `density`, `melting_point`, `boiling_point`.