calminer/docs/architecture/05_building_block_view.md

05 — Building Block View

Status: skeleton

Explain the static structure: modules, components, services and their relationships.

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, leveraging a shared dependency module (routes/dependencies.get_db) for SQLAlchemy session management.
• 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. Relationships connect scenarios to derived domain entities.
• Presentation (templates/, components/): server-rendered views extend a shared base.html layout with a persistent left sidebar, pull global styles from static/css/main.css, and surface data entry (scenario and parameter forms) alongside the Chart.js-powered dashboard.
  • 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 (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.

Architecture overview (migrated)

This overview complements architecture 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
• Request flow & runtime interactions: Runtime View
• Simulation roadmap & strategy: Solution Strategy

Currency normalization and backfill tooling have been added (see backfill_currency.py and related migrations) to support canonical currency lookups across cost tables.