CalMiner
A web application to plan mining projects and estimate costs, returns and profitability.
Focuses on ore mining operations and covering parameters such as capital and operational expenditures, resource consumption, production output, and Monte Carlo simulations for risk analysis.
The system is designed to help mining companies make informed decisions by simulating various scenarios and analyzing potential outcomes based on stochastic variables.
Current Features
Tip
TODO: Update this section to reflect the current feature set.
| Feature | Category | Description | Status |
|---|---|---|---|
| Scenario Management | Core | Manage multiple mining scenarios with independent parameter sets and outputs. | Done |
| Parameter Definition | Core | Define and manage various parameters for each scenario. | Done |
| Cost Tracking | Financial | Capture and analyze capital and operational expenditures. | Done |
| Consumption Tracking | Operational | Record resource consumption tied to scenarios. | Done |
| Production Output | Operational | Store and analyze production metrics such as tonnage, recovery, and revenue drivers. | Done |
| Equipment Management | Operational | Manage equipment inventories and specifications for each scenario. | Done |
| Maintenance Logging | Operational | Log maintenance events and costs associated with equipment. | Started |
| Reporting Dashboard | Analytics | View aggregated statistics and visualizations for scenario outputs. | In Progress |
| Monte Carlo Simulation | Analytics | Run stochastic simulations to assess risk and variability in outcomes. | Started |
| Application Settings | Core | Manage global application settings such as themes and currency options. | Done |
Key UI/UX Features
- Unified UI Shell: Server-rendered templates extend a shared base layout with a persistent left sidebar linking scenarios, parameters, costs, consumption, production, equipment, maintenance, simulations, and reporting views.
- Modular Frontend Scripts: Page-specific interactions in
static/js/modules, keeping templates lean while enabling browser caching and reuse.
Planned Features
See Roadmap for details on planned features and enhancements.
Documentation & quickstart
This repository contains detailed developer and architecture documentation in the docs/ folder.
Settings overview
The Settings page (/ui/settings) lets administrators adjust global theme colors stored in the application_setting table. Changes are instantly applied across the UI. Environment variables prefixed with CALMINER_THEME_ (for example, CALMINER_THEME_COLOR_PRIMARY) automatically override individual CSS variables and render as read-only in the form, ensuring deployment-time overrides take precedence while remaining visible to operators.
Quickstart contains developer quickstart, migrations, testing and current status.
Key architecture documents: see architecture for the arc42-based architecture documentation.
For contributors: the routes/, models/ and services/ folders contain the primary application code. Tests and E2E specs are in tests/.
Run with Docker
The repository ships with a multi-stage Dockerfile that produces a slim runtime image.
Build container
docker build -t calminer .
Push to registry
To push the image to a registry, tag it appropriately and push:
docker tag calminer your-registry/calminer:latest
docker push your-registry/calminer:latest
Run container
To run the container, ensure PostgreSQL is available and set environment variables:
docker run -p 8000:8000 \
-e DATABASE_HOST=your-postgres-host \
-e DATABASE_PORT=5432 \
-e DATABASE_USER=calminer \
-e DATABASE_PASSWORD=your-password \
-e DATABASE_NAME=calminer_db \
calminer
Development with Docker Compose
For local development, use docker-compose.yml which includes the app and PostgreSQL services.
# Start services
docker-compose up
# Or run in background
docker-compose up -d
# Stop services
docker-compose down
The app will be available at http://localhost:8000, PostgreSQL at localhost:5432.
CI/CD
CalMiner uses Gitea Actions workflows stored in .gitea/workflows/:
ci.yml: Runs on push and PR to main/develop branches. Sets up Python, installs dependencies, runs tests with coverage, and builds the Docker image.