Quickstart & Expanded Project Documentation

This document contains the expanded development, usage, testing, and migration guidance moved out of the top-level README for brevity.

Development

To get started locally:

# Clone the repository
git clone https://git.allucanget.biz/allucanget/calminer.git
cd calminer

# Create and activate a virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Start the development server
uvicorn main:app --reload

Docker-based setup

To build and run the application using Docker instead of a local Python environment:

# Build the application image (multi-stage build keeps runtime small)
docker build -t calminer:latest .

# Start the container on port 8000
docker run --rm -p 8000:8000 calminer:latest

# Supply environment variables (e.g., Postgres connection)
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

If you maintain a Postgres or Redis dependency locally, consider authoring a docker compose stack that pairs them with the app container. The Docker image expects the database to be reachable and migrations executed before serving traffic.

Usage Overview

API base URL: http://localhost:8000/api
Key routes include creating scenarios, parameters, costs, consumption, production, equipment, maintenance, and reporting summaries. See the routes/ directory for full details.

Dashboard Preview

Start the FastAPI server and navigate to /.
Review the headline metrics, scenario snapshot table, and cost/activity charts sourced from the current database state.
Use the "Refresh Dashboard" button to pull freshly aggregated data via /ui/dashboard/data without reloading the page.

Testing

Run the unit test suite:

pytest

E2E tests use Playwright and a session-scoped live_server fixture that starts the app at http://localhost:8001 for browser-driven tests.

Migrations & Currency Backfill

The project includes a referential currency table and migration/backfill tooling to normalize legacy currency fields.

Run migrations and backfill (development)

Configure the granular database settings in your PowerShell session before running migrations.

$env:DATABASE_DRIVER = 'postgresql'
$env:DATABASE_HOST = 'localhost'
$env:DATABASE_PORT = '5432'
$env:DATABASE_USER = 'calminer'
$env:DATABASE_PASSWORD = 's3cret'
$env:DATABASE_NAME = 'calminer'
$env:DATABASE_SCHEMA = 'public'
python scripts/run_migrations.py
python scripts/backfill_currency.py --dry-run
python scripts/backfill_currency.py --create-missing

ℹ️ The application still accepts DATABASE_URL as a fallback if the granular variables are not set.

Use --dry-run first to verify what will change.

Database Objects

The database contains tables such as capex, opex, chemical_consumption, fuel_consumption, water_consumption, scrap_consumption, production_output, equipment_operation, ore_batch, exchange_rate, and simulation_result.

Current implementation status (2025-10-21)

Currency normalization: a currency table and backfill scripts exist; routes accept currency_id and currency_code for compatibility.
Simulation engine: scaffolding in services/simulation.py and /api/simulations/run return in-memory results; persistence to models/simulation_result is planned.
Reporting: services/reporting.py provides summary statistics used by POST /api/reporting/summary.
Tests & coverage: unit and E2E suites exist; recent local coverage is >90%.
Remaining work: authentication, persist simulation runs, CI/CD and containerization.

Where to look next

Architecture overview & chapters: architecture (per-chapter files under docs/architecture/)
Testing & CI
Development setup
Implementation plan & roadmap: Solution strategy
Routes: routes
Services: services
Scripts: scripts (migrations and backfills)

4.3 KiB Raw Blame History Unescape Escape