58 lines
3.8 KiB
Markdown
58 lines
3.8 KiB
Markdown
---
|
|
title: "05 — Building Block View"
|
|
description: "Explain the static structure: modules, components, services and their relationships."
|
|
status: draft
|
|
---
|
|
|
|
# 05 — Building Block View
|
|
|
|
## Architecture overview
|
|
|
|
This overview complements [architecture](docs/architecture/README.md) with a high-level map of CalMiner's module layout and request flow.
|
|
|
|
Refer to the detailed architecture chapters in `docs/architecture/`:
|
|
|
|
- Module map & components: [Building Block View](docs/architecture/05_building_block_view.md)
|
|
- Request flow & runtime interactions: [Runtime View](docs/architecture/06_runtime_view.md)
|
|
- Simulation roadmap & strategy: [Solution Strategy](docs/architecture/04_solution_strategy.md)
|
|
|
|
## System Components
|
|
|
|
### Backend
|
|
|
|
- **FastAPI application** (`main.py`): entry point that configures routers, middleware, and startup/shutdown events.
|
|
- **Routers** (`routes/`): modular route handlers for scenarios, parameters, costs, consumption, production, equipment, maintenance, simulations, and reporting. Each router defines RESTful endpoints, request/response schemas, and orchestrates service calls.
|
|
- leveraging a shared dependency module (`routes/dependencies.get_db`) for SQLAlchemy session management.
|
|
- **Models** (`models/`): SQLAlchemy ORM models representing database tables and relationships, encapsulating domain entities like Scenario, CapEx, OpEx, Consumption, ProductionOutput, Equipment, Maintenance, and SimulationResult.
|
|
- **Services** (`services/`): business logic layer that processes data, performs calculations, and interacts with models. Key services include reporting calculations and Monte Carlo simulation scaffolding.
|
|
- **Database** (`config/database.py`): sets up the SQLAlchemy engine and session management for PostgreSQL interactions.
|
|
|
|
### Frontend
|
|
|
|
- **Templates** (`templates/`): Jinja2 templates for server-rendered HTML views, extending a shared base layout with a persistent sidebar for navigation.
|
|
- **Static Assets** (`static/`): CSS and JavaScript files for styling and interactivity. Shared CSS variables in `static/css/main.css` define the color palette, while page-specific JS modules in `static/js/` handle dynamic behaviors.
|
|
- **Reusable partials** (`templates/partials/components.html`): macro library that standardises select inputs, feedback/empty states, and table wrappers so pages remain consistent while keeping DOM hooks stable for existing JavaScript modules.
|
|
|
|
### Middleware & Utilities
|
|
|
|
- **Middleware** (`middleware/validation.py`): applies JSON validation before requests reach routers.
|
|
- **Testing** (`tests/unit/`): pytest suite covering route and service behavior, including UI rendering checks and negative-path router validation tests to ensure consistent HTTP error semantics. Playwright end-to-end coverage is planned for core smoke flows (dashboard load, scenario inputs, reporting) and will attach in CI once scaffolding is completed.
|
|
|
|
## Module Map (code)
|
|
|
|
- `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.
|
|
- `simulation_result.py`: stores Monte Carlo iteration outputs.
|
|
|
|
## Service Layer
|
|
|
|
- `reporting.py`: computes aggregates (count, min/max, mean, median, percentiles, standard deviation, variance, tail-risk metrics) from simulation results.
|
|
- `simulation.py`: scaffolds Monte Carlo simulation logic (currently in-memory; persistence planned).
|
|
- `currency.py`: handles currency normalization for cost tables.
|
|
- `utils.py`: shared helper functions (e.g., statistical calculations).
|
|
- `validation.py`: JSON schema validation middleware.
|
|
- `database.py`: SQLAlchemy engine and session setup.
|
|
- `dependencies.py`: FastAPI dependency injection for DB sessions.
|