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.
4.5 KiB
4.5 KiB
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.
- leveraging a shared dependency module (
- 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 theapplication_settingtable, 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 instatic/css/main.cssdefine the color palette, while page-specific JS modules instatic/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 byroutes/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.