From 28fea1f3fe370071279b6a906386689da1dcf78a Mon Sep 17 00:00:00 2001 From: zwitschi Date: Fri, 24 Oct 2025 13:49:04 +0200 Subject: [PATCH] docs: Update README and architecture documents with build instructions and detailed data models --- README.md | 20 +++- docs/architecture/08_concepts.md | 8 ++ .../08_concepts/08_02_data_models.md | 106 ++++++++++++++++++ 3 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 docs/architecture/08_concepts/08_02_data_models.md diff --git a/README.md b/README.md index 4a3b6fc..9a72ca5 100644 --- a/README.md +++ b/README.md @@ -38,13 +38,27 @@ For contributors: the `routes/`, `models/` and `services/` folders contain the p The repository ships with a multi-stage `Dockerfile` that produces a slim runtime image. +### Build container + ```powershell # Build the image locally docker build -t calminer:latest . +``` -# Run the container (exposes FastAPI on http://localhost:8000) -docker run --rm -p 8000:8000 calminer:latest +### Push to registry +```powershell +# Tag and push the image to your registry +docker login your-registry.com -u your-username -p your-password +docker tag calminer:latest your-registry.com/your-namespace/calminer:latest +docker push your-registry.com/your-namespace/calminer:latest +``` + +### Run container + +Expose FastAPI on with database configuration via granular environment variables: + +```powershell # Provide database configuration via granular environment variables docker run --rm -p 8000:8000 ^ -e DATABASE_DRIVER="postgresql" ^ @@ -57,6 +71,8 @@ docker run --rm -p 8000:8000 ^ calminer:latest ``` +### Orchestrated Deployment + Use `docker compose` or an orchestrator of your choice to co-locate PostgreSQL/Redis alongside the app when needed. The image expects migrations to be applied before startup. ## CI/CD expectations diff --git a/docs/architecture/08_concepts.md b/docs/architecture/08_concepts.md index d38264c..61cf25e 100644 --- a/docs/architecture/08_concepts.md +++ b/docs/architecture/08_concepts.md @@ -42,6 +42,10 @@ The domain model consists of the following key entities: - `Attachment`: Files associated with scenarios, such as documents or images. - `Version`: Tracks different versions of scenarios and their configurations. +### Detailed Domain Models + +See [Domain Models](08_concepts/08_01_domain_models.md) document for detailed class diagrams and entity relationships. + ## Data Model Highlights - `scenario`: central entity describing a mining scenario; owns relationships to cost, consumption, production, equipment, and maintenance tables. @@ -53,3 +57,7 @@ The domain model consists of the following key entities: - `simulation_result`: staging table for future Monte Carlo outputs (not yet populated by `run_simulation`). Foreign keys secure referential integrity between domain tables and their scenarios, enabling per-scenario analytics. + +### Detailed Data Models + +See [Data Models](08_concepts/08_02_data_models.md) document for detailed ER diagrams and table descriptions. diff --git a/docs/architecture/08_concepts/08_02_data_models.md b/docs/architecture/08_concepts/08_02_data_models.md new file mode 100644 index 0000000..3e873b9 --- /dev/null +++ b/docs/architecture/08_concepts/08_02_data_models.md @@ -0,0 +1,106 @@ +# Data Models + +## Data Model Highlights + +- `scenario`: central entity describing a mining scenario; owns relationships to cost, consumption, production, equipment, and maintenance tables. +- `capex`, `opex`: monetary tracking linked to scenarios. +- `consumption`: resource usage entries parameterized by scenario and description. +- `parameter`: scenario inputs with base `value` and optional distribution linkage via `distribution_id`, `distribution_type`, and JSON `distribution_parameters` to support simulation sampling. +- `production_output`: production metrics per scenario. +- `equipment` and `maintenance`: equipment inventory and maintenance events with dates/costs. +- `simulation_result`: staging table for future Monte Carlo outputs (not yet populated by `run_simulation`). + +Foreign keys secure referential integrity between domain tables and their scenarios, enabling per-scenario analytics. + +## Schema Diagrams + +```mermaid +erDiagram + SCENARIO ||--o{ CAPEX : has + SCENARIO ||--o{ OPEX : has + SCENARIO ||--o{ CONSUMPTION : has + SCENARIO ||--o{ PARAMETER : has + SCENARIO ||--o{ PRODUCTION_OUTPUT : has + SCENARIO ||--o{ EQUIPMENT : has + EQUIPMENT ||--o{ MAINTENANCE : has + SCENARIO ||--o{ SIMULATION_RESULT : has + + SCENARIO { + int id PK + string name + string description + datetime created_at + datetime updated_at + } + CAPEX { + int id PK + int scenario_id FK + float amount + string description + datetime created_at + datetime updated_at + } + OPEX { + int id PK + int scenario_id FK + float amount + string description + datetime created_at + datetime updated_at + } + CONSUMPTION { + int id PK + int scenario_id FK + string resource_type + float quantity + string description + datetime created_at + datetime updated_at + } + + PRODUCTION_OUTPUT { + int id PK + int scenario_id FK + float tonnage + float recovery_rate + float revenue + datetime created_at + datetime updated_at + } + EQUIPMENT { + int id PK + int scenario_id FK + string name + string type + datetime created_at + datetime updated_at + } + MAINTENANCE { + int id PK + int equipment_id FK + date maintenance_date + float cost + string description + datetime created_at + datetime updated_at + } + SIMULATION_RESULT { + int id PK + int scenario_id FK + json result_data + datetime created_at + datetime updated_at + } + PARAMETER { + int id PK + int scenario_id FK + string name + float value + int distribution_id FK + string distribution_type + json distribution_parameters + datetime created_at + datetime updated_at + } + +```