zwitschi
4b3a15ed15
- Introduced multiple architecture documentation files covering building block view, runtime view, deployment view, concepts, architecture decisions, quality requirements, technical risks, glossary, UI and styling, testing, CI, and development setup. - Migrated existing content from `architecture_overview.md` and `implementation_plan.md` into structured documentation. - Created scripts for checking broken links in documentation and formatting Markdown files for consistency. - Updated quickstart guide to provide clearer setup instructions and usage overview. - Removed outdated MVP features and testing strategy documents to streamline documentation.
2.8 KiB
2.8 KiB
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.pyproduces statistical summaries, whileservices/simulation.pyprovides 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 sharedbase.htmllayout with a persistent left sidebar, pull global styles fromstatic/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.
- Reusable partials (
- 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 docs/architecture.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:
docs/architecture/05_building_block_view.md - Request flow & runtime interactions:
docs/architecture/06_runtime_view.md - Simulation roadmap & strategy:
docs/architecture/04_solution_strategy.md
Currency normalization and backfill tooling have been added (see scripts/backfill_currency.py and related migrations) to support canonical currency lookups across cost tables.