Refactor architecture documentation and enhance security features

- Updated architecture constraints documentation to include detailed sections on technical, organizational, regulatory, environmental, and performance constraints. - Created separate markdown files for each type of constraint for better organization and clarity. - Revised the architecture scope section to provide a clearer overview of the system's key areas. - Enhanced the solution strategy documentation with detailed explanations of the client-server architecture, technology choices, trade-offs, and future considerations. - Added comprehensive descriptions of backend and frontend components, middleware, and utilities in the architecture documentation. - Migrated UI, templates, and styling notes to a dedicated section for better structure. - Updated requirements.txt to include missing dependencies. - Refactored user authentication logic in the users.py and security.py files to improve code organization and maintainability, including the integration of OAuth2 password bearer token handling.
2025-10-27 12:46:51 +01:00
parent 7f4cd33b65
commit ef4fb7dcf0
23 changed files with 271 additions and 400 deletions
--- a/docs/architecture/05_building_block_view.md
+++ b/docs/architecture/05_building_block_view.md
@@ -1,6 +1,6 @@
 ---
-title: '05 — Building Block View'
-description: 'Explain the static structure: modules, components, services and their relationships.'
+title: "05 — Building Block View"
+description: "Explain the static structure: modules, components, services and their relationships."
 status: draft
 ---

@@ -8,257 +8,9 @@ status: draft

 # 05 — Building Block View

-## Architecture overview
+## Building Block 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.
-
-### Level 1 Overview
-
-```mermaid
-graph LR
-  U["User (Browser)"]
-
-  subgraph FE[Frontend]
-    FE_TPL["Templates (Jinja2)"]
-    FE_STATIC["Static Assets (CSS/JS)"]
-    FE_PARTS["Reusable Partials"]
-    FE_SETTINGS["Settings View & JS"]
-  end
-
-  subgraph BE[Backend — FastAPI]
-    BE_APP["FastAPI App (main.py)"]
-    BE_ROUTES["Routers"]
-    BE_SERVICES["Services"]
-    BE_MODELS["Models (SQLAlchemy)"]
-    BE_DB["Database Layer"]
-  end
-
-  subgraph MW[Middleware & Utilities]
-    MW_VAL["JSON Validation Middleware"]
-  end
-
-  subgraph QA[Testing]
-    QA_UNIT["Unit Tests (pytest)"]
-    QA_E2E["E2E (Playwright, planned)"]
-  end
-
-  %% High-level flows
-  U -->|HTTP| BE_APP
-  U --> FE
-  FE --> BE_ROUTES
-  BE_APP --> BE_ROUTES
-  BE_ROUTES --> BE_SERVICES
-  BE_SERVICES --> BE_MODELS
-  BE_MODELS --> BE_DB
-
-  MW_VAL --> BE_APP
-
-  QA_UNIT --> BE_ROUTES
-  QA_UNIT --> BE_SERVICES
-  QA_UNIT --> FE
-  QA_UNIT --> MW_VAL
-  QA_E2E --> U
-  QA_E2E --> BE_APP
-```
-
-### Level 2 Overview
-
-```mermaid
-graph LR
-  %% Direction
-  %% LR = left-to-right for a wide architecture view
-
-  %% === Clients ===
-  U["User (Browser)"]
-
-  %% === Frontend ===
-  subgraph FE[Frontend]
-    TPL["Jinja2 Templates
-(templates/)
-• base layout + sidebar"]
-    PARTS["Reusable Partials
-(templates/partials/components.html)
-• inputs • empty states • table wrappers"]
-    STATIC["Static Assets
-(static/)
-• CSS: static/css/main.css (palette via CSS vars)
-• JS: static/js/*.js (page modules)"]
-    SETPAGE["Settings View
-(templates/settings.html)"]
-    SETJS["Settings Logic
-(static/js/settings.js)
-• validation • submit • live CSS updates"]
-  end
-
-  %% === Backend ===
-  subgraph BE[Backend — FastAPI]
-    MAIN["FastAPI App
-(main.py)
-• routers • middleware • startup/shutdown"]
-
-    subgraph ROUTES[Routers]
-      R_SCN["scenarios"]
-      R_PAR["parameters"]
-      R_CST["costs"]
-      R_CONS["consumption"]
-      R_PROD["production"]
-      R_EQP["equipment"]
-      R_MNT["maintenance"]
-      R_SIM["simulations"]
-      R_REP["reporting"]
-      R_UI["ui.py (metadata for UI)"]
-      DEP["dependencies.get_db
-(shared SQLAlchemy session)"]
-    end
-
-    subgraph SRV[Services]
-      S_BLL["Business Logic Layer
-• orchestrates models + calc"]
-      S_REP["Reporting Calculations"]
-      S_SIM["Monte Carlo
-(simulation scaffolding)"]
-      S_SET["Settings Manager
-(services/settings.py)
-• defaults via CSS vars
-• persistence in DB
-• env overrides
-• surfaces to API & UI"]
-    end
-
-    subgraph MOD[Models]
-      M_SCN["Scenario"]
-      M_CAP["CapEx"]
-      M_OPEX["OpEx"]
-      M_CONS["Consumption"]
-      M_PROD["ProductionOutput"]
-      M_EQP["Equipment"]
-      M_MNT["Maintenance"]
-      M_SIMR["SimulationResult"]
-    end
-
-    subgraph DB[Database Layer]
-      CFG["config/database.py
-(SQLAlchemy engine & sessions)"]
-      PG[("PostgreSQL")]
-      APPSET["application_setting table"]
-    end
-  end
-
-  %% === Middleware & Utilities ===
-  subgraph MW[Middleware & Utilities]
-    VAL["JSON Validation Middleware
-(middleware/validation.py)"]
-  end
-
-  subgraph TEST[Testing]
-    UNIT["pytest unit tests
-(tests/unit/)
-• routes • services • UI rendering
-• negative-path validation"]
-    E2E["Playwright E2E (planned)
-• dashboard • scenario inputs • reporting
-• attach in CI"]
-  end
-
-  %% ===================== Edges / Flows =====================
-  %% User to Frontend/Backend
-  U -->|HTTP GET| MAIN
-  U --> TPL
-  TPL -->|server-rendered HTML| U
-  STATIC --> U
-  PARTS --> TPL
-  SETPAGE --> U
-  SETJS --> U
-
-  %% Frontend to Routers (AJAX/form submits)
-  SETJS -->|fetch/POST| R_UI
-  TPL -->|form submit / fetch| ROUTES
-
-  %% FastAPI app wiring and middleware
-  VAL --> MAIN
-  MAIN --> ROUTES
-
-  %% Routers to Services
-  ROUTES -->|calls| SRV
-  R_REP -->|calc| S_REP
-  R_SIM -->|run| S_SIM
-  R_UI -->|read/write settings meta| S_SET
-
-  %% Services to Models & DB
-  SRV --> MOD
-  MOD --> CFG
-  CFG --> PG
-
-  %% Settings manager persistence path
-  S_SET -->|persist/read| APPSET
-  APPSET --- PG
-
-  %% Shared DB session dependency
-  DEP -. provides .-> ROUTES
-  DEP -. session .-> SRV
-
-  %% Model entities mapping
-  S_BLL --> M_SCN & M_CAP & M_OPEX & M_CONS & M_PROD & M_EQP & M_MNT & M_SIMR
-
-  %% Testing coverage
-  UNIT --> ROUTES
-  UNIT --> SRV
-  UNIT --> TPL
-  UNIT --> VAL
-  E2E --> U
-  E2E --> MAIN
-
-  %% Legend
-  classDef store fill:#fff,stroke:#555,stroke-width:1px;
-  class PG store;
-```
-
-## 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.
+- [Architecture Overview](05_blocks/05_01_architecture_overview.md)
+- [Backend Components](05_blocks/05_02_backend_components.md)
+- [Frontend Components](05_blocks/05_03_frontend_components.md)
+- [Middleware & Utilities](05_blocks/05_04_middleware_utilities.md)