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.

A range of features are implemented to support these functionalities.

Features

• Scenario Management: Manage multiple mining scenarios with independent parameter sets and outputs.
• Process Parameters: Define and persist process inputs via FastAPI endpoints and template-driven forms.
• Cost Tracking: Capture capital (capex) and operational (opex) expenditures per scenario.
• Consumption Tracking: Record resource consumption (chemicals, fuel, water, scrap) tied to scenarios.
• Production Output: Store production metrics such as tonnage, recovery, and revenue drivers.
• Equipment Management: Register scenario-specific equipment inventories.
• Maintenance Logging: Log maintenance events against equipment with dates and costs.
• Reporting Dashboard: Surface aggregated statistics for simulation outputs with an interactive Chart.js dashboard.
• 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.
• Operations Overview Dashboard: The root route (/) surfaces cross-scenario KPIs, charts, and maintenance reminders with a one-click refresh backed by aggregated loaders.
• Theming Tokens: Shared CSS variables in static/css/main.css centralize the UI color palette for consistent styling and rapid theme tweaks.
• Settings Center: The Settings landing page exposes visual theme controls and links to currency administration, backed by persisted application settings and environment overrides.
• Modular Frontend Scripts: Page-specific interactions in static/js/ modules, keeping templates lean while enabling browser caching and reuse.
• Monte Carlo Simulation (in progress): Services and routes are scaffolded for future stochastic analysis.

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

# Build the image locally
docker build -t calminer:latest .

Push to registry

# Tag and push the image to your registry
docker login your-registry.com -u your-username -p your-password
docker tag calminer:latest your-registry.com/your-namespace/calminer:latest
docker push your-registry.com/your-namespace/calminer:latest

Run container

Expose FastAPI on http://localhost:8000 with database configuration via granular environment variables:

# Provide database configuration via granular environment variables
docker run --rm -p 8000:8000 ^
  -e DATABASE_DRIVER="postgresql" ^
  -e DATABASE_HOST="db.host" ^
  -e DATABASE_PORT="5432" ^
  -e DATABASE_USER="calminer" ^
  -e DATABASE_PASSWORD="s3cret" ^
  -e DATABASE_NAME="calminer" ^
  -e DATABASE_SCHEMA="public" ^
  calminer:latest

Orchestrated Deployment

Use docker compose or an orchestrator of your choice to co-locate PostgreSQL/Redis/Traefik alongside the app when needed. The image expects migrations to be applied before startup.

Production docker-compose workflow

docker-compose.prod.yml covers the API plus optional Traefik (reverse-proxy profile) and on-host Postgres (local-db profile). Commands, health checks, and environment variables are documented in docs/quickstart.md and expanded in docs/architecture/07_deployment_view.md.

Development docker-compose workflow

docker-compose.dev.yml runs FastAPI (with reload) and Postgres in a single stack. See docs/quickstart.md for lifecycle commands and troubleshooting, plus the architecture chapter (docs/architecture/15_development_setup.md) for deeper context.

Test docker-compose workflow

docker-compose.test.yml mirrors the CI pipeline: it provisions Postgres, runs the database bootstrap script, and executes pytest. Usage examples live in docs/quickstart.md.

CI/CD expectations

CalMiner uses Gitea Actions workflows stored in .gitea/workflows/:

• test.yml runs style/unit/e2e suites on every push with cached Python dependencies.
• build-and-push.yml builds the Docker image, reuses cached layers, and pushes to the configured registry.
• deploy.yml pulls the pushed image on the target host and restarts the container.

Pipelines assume the following secrets are provisioned in the Gitea instance: REGISTRY_USERNAME, REGISTRY_PASSWORD, REGISTRY_URL, SSH_HOST, SSH_USERNAME, and SSH_PRIVATE_KEY.