calminer/docs/architecture.md

Architecture Documentation

Overview

CalMiner is a FastAPI application that collects mining project inputs, persists scenario-specific records, and surfaces aggregated insights. The platform targets Monte Carlo driven planning, with deterministic CRUD features in place and simulation logic staged for future work.

System Components

• FastAPI backend (main.py, routes/): hosts REST endpoints for scenarios, parameters, costs, consumption, production, equipment, maintenance, simulations, and reporting. Each router encapsulates request/response schemas and DB access patterns.
• Service layer (services/): houses business logic. services/reporting.py produces statistical summaries, while services/simulation.py provides the Monte Carlo integration point.
• Persistence (models/, config/database.py): SQLAlchemy models map to PostgreSQL tables in schema bricsium_platform. Relationships connect scenarios to derived domain entities.
• Presentation (templates/, components/): server-rendered views support data entry (scenario and parameter forms) and the dashboard visualization powered by Chart.js.
• Middleware (middleware/validation.py): applies JSON validation before requests reach routers.
• Testing (tests/unit/): pytest suite covering route and service behavior.

Runtime Flow

1. Users navigate to form templates or API clients to manage scenarios, parameters, and operational data.
2. FastAPI routers validate payloads with Pydantic models, then delegate to SQLAlchemy sessions for persistence.
3. Simulation runs (placeholder services/simulation.py) will consume stored parameters to emit iteration results via /api/simulations/run.
4. Reporting requests POST simulation outputs to /api/reporting/summary; the reporting service calculates aggregates (count, min/max, mean, median, percentiles, standard deviation).
5. templates/Dashboard.html fetches summaries, renders metric cards, and plots distribution charts with Chart.js for stakeholder review.

Data Model Highlights

• scenario: central entity describing a mining scenario; owns relationships to cost, consumption, production, equipment, and maintenance tables.
• capex, opex: monetary tracking linked to scenarios.
• consumption: resource usage entries parameterized by scenario and description.
• production_output: production metrics per scenario.
• equipment and maintenance: equipment inventory and maintenance events with dates/costs.
• simulation_result: staging table for future Monte Carlo outputs (not yet populated by run_simulation).

Foreign keys secure referential integrity between domain tables and their scenarios, enabling per-scenario analytics.

Integrations and Future Work

• Monte Carlo engine: services/simulation.py will incorporate stochastic sampling (e.g., NumPy, SciPy) to populate simulation_result and feed reporting.
• Persistence of results: /api/simulations/run currently returns in-memory results; next iteration should persist to simulation_result and reference scenarios.
• Authentication: not yet implemented; all endpoints are open.
• Deployment: documentation focuses on local development; containerization and CI/CD pipelines remain to be defined.

For extended diagrams and setup instructions reference:

• docs/development_setup.md — environment provisioning and tooling.
• docs/testing.md — pytest workflow and coverage expectations.
• docs/mvp.md — roadmap and milestone scope.
• docs/implementation_plan.md — feature breakdown aligned with the TODO tracker.
• docs/architecture_overview.md — supplementary module map and request flow diagram.