docs: Update README and architecture documents with build instructions and detailed data models

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 <http://localhost:8000> 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

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.

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
+    }
+
+```