feat: enhance data model documentation with detailed entity descriptions and relationships

architecture/08_concepts.md

@@ -71,11 +71,27 @@ Each tenant can have customized settings and preferences, managed through the Ma
 
 ## Data Model
 
-The system employs a relational data model to manage and store information efficiently. The primary entities include Users, Projects, Datasets, and Results. Each entity is represented as a table in the database, with relationships defined through foreign keys.
+The system employs a relational data model to manage and store information efficiently. Core entities include Users, Projects, Scenarios, Financial Inputs, Simulation Parameters, Pricing Settings, and supporting metadata tables. Relationships are enforced using foreign keys with cascading deletes where appropriate (e.g., scenarios cascade from projects, financial inputs cascade from scenarios).
 
-A detailed [Data Model](08_concepts/02_data_model.md) documentation is available.
+Domain-specific enumerations are mapped to PostgreSQL enum types and mirrored in the ORM layer via `models.enums`:
 
-Discounted cash-flow metrics (NPV, IRR, Payback) referenced by the economic portion of the data model are described in the [Financial Metrics Specification](../specifications/financial_metrics.md), while stochastic extensions leverage the Monte Carlo engine documented in the [Monte Carlo Simulation Specification](../specifications/monte_carlo_simulation.md).
+- `MiningOperationType` — categorises projects (open pit, underground, in-situ leach, etc.).
+- `ScenarioStatus` — tracks lifecycle state (draft, active, archived).
+- `FinancialCategory` and `CostBucket` — classify financial inputs for reporting granularity.
+- `DistributionType` and `StochasticVariable` — describe probabilistic simulation parameters.
+- `ResourceType` — annotates primary resource consumption for scenarios and stochastic parameters.
+
+These enums back the relevant model columns through named SQLAlchemy `Enum` definitions referencing the same PostgreSQL type names, ensuring parity between application logic and database constraints.
+
+Schema creation and baseline seed data are handled by the idempotent initializer (`scripts/init_db.py`). On every application startup the initializer guarantees that:
+
+1. Enum types exist exactly once.
+2. Tables for authentication, pricing, and mining domain entities are present.
+3. Default roles, administrator account, pricing settings, and representative demo projects/scenarios/financial inputs are available for immediate use.
+
+Developers can reset to a clean slate with `scripts/reset_db.py`, which safely drops managed tables and enum types in non-production environments before rerunning the initializer.
+
+A detailed [Data Model](08_concepts/02_data_model.md) documentation is available. Discounted cash-flow metrics (NPV, IRR, Payback) referenced by the economic portion of the data model are described in the [Financial Metrics Specification](../specifications/financial_metrics.md), while stochastic extensions leverage the Monte Carlo engine documented in the [Monte Carlo Simulation Specification](../specifications/monte_carlo_simulation.md).
 
 All data interactions are handled through the [Data Access Layer](05_building_block_view.md#data-access-layer), ensuring consistency and integrity across operations.