calminer/docs/architecture/05_building_block_view.md

title, description, status

title	description	status
05 — Building Block View	Explain the static structure: modules, components, services and their relationships.	draft

05 — Building Block View

Architecture overview

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

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.