zwitschi
5b1322ddbc
Some checks failed
Run Tests / test (push) Failing after 1m51s
- Introduced a new table `application_setting` to store configurable application options. - Implemented functions to manage CSS color settings, including loading, updating, and reading environment overrides. - Added a new settings view to render and manage theme colors. - Updated UI to include a settings page with theme color management and environment overrides display. - Enhanced CSS styles for the settings page and sidebar navigation. - Created unit and end-to-end tests for the new settings functionality and CSS management.
63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
---
|
|
title: "05 — Building Block View"
|
|
description: "Explain the static structure: modules, components, services and their relationships."
|
|
status: draft
|
|
---
|
|
|
|
<!-- markdownlint-disable-next-line MD025 -->
|
|
# 05 — Building Block View
|
|
|
|
## Architecture overview
|
|
|
|
This overview complements [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](05_building_block_view.md)
|
|
- Request flow & runtime interactions: [Runtime View](06_runtime_view.md)
|
|
- Simulation roadmap & strategy: [Solution Strategy](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.
|
|
- `services/settings.py`: manages application settings backed by the `application_setting` table, including CSS variable defaults, persistence, and environment-driven overrides that surface in both the API and UI.
|
|
- **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.
|
|
- `templates/settings.html`: Settings hub that renders theme controls and environment override tables using metadata provided by `routes/ui.py`.
|
|
- `static/js/settings.js`: applies client-side validation, form submission, and live CSS updates for theme changes, respecting environment-managed variables returned by the API.
|
|
|
|
### 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.
|
|
- `application_setting.py`: persists editable application configuration, currently focused on theme variables but designed to store future settings categories.
|
|
|
|
## 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.
|