zwitschi
e73a987d25
- Updated README.md to reflect new features and usage instructions. - Removed deprecated Dashboard.html component and integrated dashboard functionality directly into the main application. - Revised architecture documentation for clarity and added module map and request flow diagrams. - Enhanced maintenance model to include equipment association and cost tracking. - Updated requirements.txt to include new dependencies (httpx, pandas, numpy). - Improved consumption, maintenance, production, and reporting routes with better validation and response handling. - Added unit tests for maintenance and production routes, ensuring proper CRUD operations and validation. - Enhanced reporting service to calculate and return detailed summary statistics. - Redesigned Dashboard.html for improved user experience and integrated Chart.js for visualizing simulation results.
49 lines
3.7 KiB
Markdown
49 lines
3.7 KiB
Markdown
# 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](development_setup.md) — environment provisioning and tooling.
|
|
- [docs/testing.md](testing.md) — pytest workflow and coverage expectations.
|
|
- [docs/mvp.md](mvp.md) — roadmap and milestone scope.
|
|
- [docs/implementation_plan.md](implementation_plan.md) — feature breakdown aligned with the TODO tracker.
|
|
- [docs/architecture_overview.md](architecture_overview.md) — supplementary module map and request flow diagram.
|