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.
35 lines
2.8 KiB
Markdown
35 lines
2.8 KiB
Markdown
# 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.py` produces statistical summaries, while `services/simulation.py` provides 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 shared `base.html` layout with a persistent left sidebar, pull global styles from `static/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.
|
|
- **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.
|