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

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