# Architecture Overview

This overview complements `docs/architecture.md` with a high-level map of CalMiner's module layout and request flow.

## Module Map

- `main.py`: FastAPI entry point bootstrapping routers and middleware.
- `models/`: SQLAlchemy declarative models for all database tables. Key modules:
  - `scenario.py`: central scenario entity with relationships to cost, consumption, production, equipment, maintenance, and simulation results.
  - `capex.py`, `opex.py`: financial expenditures tied to scenarios.
  - `consumption.py`, `production_output.py`: operational data tables.
  - `equipment.py`, `maintenance.py`: asset management models.
- `routes/`: REST endpoints grouped by domain (scenarios, parameters, costs, consumption, production, equipment, maintenance, reporting, simulations, UI).
- `services/`: business logic abstractions. `reporting.py` supplies summary statistics; `simulation.py` hosts the Monte Carlo extension point.
- `middleware/validation.py`: request JSON validation prior to hitting routers.
- `templates/`: Jinja2 templates for UI (scenario form, parameter input, dashboard).

## Request Flow

```mermaid
graph TD
    A[Browser / API Client] -->|HTTP| B[FastAPI Router]
    B --> C[Dependency Injection]
    C --> D[SQLAlchemy Session]
    B --> E[Service Layer]
    E --> D
    E --> F[Reporting / Simulation Logic]
    D --> G[PostgreSQL]
    F --> H[Summary Response]
    G --> H
    H --> A
```

## Dashboard Interaction

1. User loads `/dashboard`, served by `templates/Dashboard.html`.
2. Template fetches `/api/reporting/summary` with sample or user-provided simulation outputs.
3. Response metrics populate the summary grid and Chart.js visualization.

## Simulation Roadmap

- Implement stochastic sampling in `services/simulation.py` (e.g., NumPy random draws based on parameter distributions).
- Store iterations in `models/simulation_result.py` via `/api/simulations/run`.
- Feed persisted results into reporting for downstream analytics and historical comparisons.