# 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:

```powershell
# 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:

```powershell
# 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_URL="postgresql://user:pass@host/db" 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

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:

```powershell
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.

```powershell
$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](docs/architecture/README.md) (per-chapter files under `docs/architecture/`)
- [Testing & CI](docs/architecture/14_testing_ci.md)
- [Development setup](docs/architecture/15_development_setup.md)
- Implementation plan & roadmap: [Solution strategy](docs/architecture/04_solution_strategy_extended.md)
- Routes: [routes](routes/)
- Services: [services](services/)
- Scripts: [scripts](scripts/) (migrations and backfills)