calminer/docs/quickstart.md

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

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

1. Start the FastAPI server and navigate to /.
2. Review the headline metrics, scenario snapshot table, and cost/activity charts sourced from the current database state.
3. 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)

Ensure DATABASE_URL is set in your PowerShell session to point at a development Postgres instance.

$env:DATABASE_URL = 'postgresql://user:pass@host/db'
python scripts/run_migrations.py
python scripts/backfill_currency.py --dry-run
python scripts/backfill_currency.py --create-missing

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)