Files

zwitschi 4b3a15ed15 Add comprehensive architecture documentation and related scripts

- Introduced multiple architecture documentation files covering building block view, runtime view, deployment view, concepts, architecture decisions, quality requirements, technical risks, glossary, UI and styling, testing, CI, and development setup.
- Migrated existing content from `architecture_overview.md` and `implementation_plan.md` into structured documentation.
- Created scripts for checking broken links in documentation and formatting Markdown files for consistency.
- Updated quickstart guide to provide clearer setup instructions and usage overview.
- Removed outdated MVP features and testing strategy documents to streamline documentation.

2025-10-21 15:39:17 +02:00

3.1 KiB

Raw Blame History

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

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)

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: docs/architecture.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: docs/architecture/04_solution_strategy_extended.md
Routes: routes/ directory
Services: services/ directory
Scripts: scripts/ directory (migrations and backfills)

3.1 KiB Raw Blame History