# Data Schemas and Relations

## 1. JSON Data Structure

### 1.1 Root Storage Structure
```json
{
  "version": "1.0.0",
  "lastModified": "2024-01-01T00:00:00Z",
  "users": [],
  "wastes": [],
  "regulators": [],
  "services": [],
  "treatmentSites": [],
  "wasteSites": [],
  "investors": [],
  "administrativeProcedures": [],
  "projects": []
}
```

## 2. Entity Schemas

### 2.1 User Schema
```json
{
  "id": "string (UUID)",
  "username": "string",
  "password": "string (hashed or plain for localhost)",
  "createdAt": "ISO 8601 date string",
  "lastLogin": "ISO 8601 date string"
}
```

### 2.2 Waste Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "originType": "string (animals|markets|restaurants|other)",
  "originSubType": "string (specific type)",
  "originUnitsPer1000m3Methane": "number",
  "bmp": "number (Nm³ CH₄/kg VS)",
  "waterPercentage": "number (0-100)",
  "regulationNeeds": "string[]",
  "regulatoryCharacteristics": {
    "nitrogen": "number (optional)",
    "phosphorus": "number (optional)",
    "potassium": "number (optional)",
    "carbonNitrogenRatio": "number (optional)"
  },
  "maxStorageDuration": "number (days)",
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.3 Natural Regulator Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "type": "string",
  "regulatoryCharacteristics": {
    "nitrogen": "number (optional)",
    "phosphorus": "number (optional)",
    "potassium": "number (optional)",
    "carbonNitrogenRatio": "number (optional)",
    "phAdjustment": "number (optional, -14 to 14)",
    "metalBinding": "boolean (optional)",
    "pathogenReduction": "boolean (optional)"
  },
  "applicationConditions": "string",
  "dosageRequirements": {
    "min": "number",
    "max": "number",
    "unit": "string (kg/t|L/t|%)"
  },
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.4 Service Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "type": "string (rawRental|biologicalTreatment|bitcoinManagement|fertilizers|wasteHeat|carbonCredits|brownfield|transport)",
  "pricing": {
    "year1": "number (€/module/year)",
    "year2": "number (€/module/year)",
    "year3": "number (€/module/year)",
    "year4": "number (€/module/year)",
    "year5": "number (€/module/year)",
    "year6": "number (€/module/year)",
    "year7": "number (€/module/year)",
    "year8": "number (€/module/year)",
    "year9": "number (€/module/year)",
    "year10": "number (€/module/year)"
  },
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.5 Treatment Site Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "status": "string (toBeApproached|loiOk|inProgress|completed)",
  "location": {
    "address": "string (optional)",
    "coordinates": {
      "lat": "number (optional)",
      "lng": "number (optional)"
    }
  },
  "altitude": "number (meters)",
  "availableGroundSurface": "number (m²)",
  "monthlyTemperatures": [
    "number (January, °C)",
    "number (February, °C)",
    "number (March, °C)",
    "number (April, °C)",
    "number (May, °C)",
    "number (June, °C)",
    "number (July, °C)",
    "number (August, °C)",
    "number (September, °C)",
    "number (October, °C)",
    "number (November, °C)",
    "number (December, °C)"
  ],
  "subscribedServices": "string[] (array of service IDs)",
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.6 Waste Site Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "type": "string",
  "status": "string (toBeApproached|loiOk|inProgress|completed)",
  "wasteType": "string (reference to waste ID)",
  "quantityRange": {
    "min": "number (t/day)",
    "max": "number (t/day)"
  },
  "contact": {
    "name": "string",
    "email": "string (optional)",
    "phone": "string (optional)",
    "address": "string (optional)"
  },
  "collectionType": "string",
  "distance": "number (km, from treatment site)",
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.7 Investor Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "type": "string",
  "amountRange": {
    "min": "number (€)",
    "max": "number (€)"
  },
  "geographicRegions": "string[]",
  "wasteRange": {
    "min": "number (t/day)",
    "max": "number (t/day)"
  },
  "wasteTypes": "string[] (array of waste type IDs)",
  "solarPanelsRange": {
    "min": "number (kW)",
    "max": "number (kW)"
  },
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.8 Administrative Procedure Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "type": "string (ICPE|spreading|other)",
  "delays": "number (days)",
  "contact": {
    "name": "string",
    "email": "string (optional)",
    "phone": "string (optional)",
    "organization": "string (optional)"
  },
  "regions": "string[]",
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

### 2.9 Project Schema
```json
{
  "id": "string (UUID)",
  "name": "string",
  "startDate": "ISO 8601 date string",
  "endDate": "ISO 8601 date string",
  "treatmentSiteId": "string (reference to treatment site)",
  "collectionSiteIds": "string[] (array of waste site IDs)",
  "numberOfModules": "number",
  "transportBySite": "boolean",
  "wasteCharacteristicsOverride": {
    "wasteId": "string (optional, reference to waste)",
    "bmp": "number (optional, override)",
    "waterPercentage": "number (optional, override)",
    "regulatoryNeeds": "string[] (optional, override)"
  },
  "administrativeProcedures": [
    {
      "procedureId": "string (reference to administrative procedure)",
      "status": "string (toDo|done|na)"
    }
  ],
  "investments": [
    {
      "investorId": "string (reference to investor)",
      "status": "string (toBeApproached|loiOk|inProgress|completed)",
      "amount": "number (€)"
    }
  ],
  "businessPlan": {
    "revenues": {
      "rawRental": "number[] (10 years, €/year)",
      "biologicalTreatment": "number[] (10 years, €/year)",
      "bitcoinManagement": "number[] (10 years, €/year)",
      "fertilizers": "number[] (10 years, €/year)",
      "wasteHeat": "number[] (10 years, €/year)",
      "carbonCredits": "number[] (10 years, €/year)",
      "brownfield": "number[] (10 years, €/year)",
      "transport": "number[] (10 years, €/year)",
      "commercialPartnerships": "number[] (10 years, €/year)",
      "other": "number[] (10 years, €/year)"
    },
    "variableCosts": {
      "rentalServices": "number[] (10 years, €/year)",
      "commissions": "number[] (10 years, €/year)",
      "otherVariable": "number[] (10 years, €/year)",
      "transport": "number[] (10 years, €/year)"
    },
    "fixedCosts": {
      "salaries": "number[] (10 years, €/year)",
      "marketing": "number[] (10 years, €/year)",
      "rd": "number[] (10 years, €/year)",
      "administrative": "number[] (10 years, €/year)",
      "otherGeneral": "number[] (10 years, €/year)"
    },
    "investments": {
      "equipment": "number[] (10 years, €/year)",
      "technology": "number[] (10 years, €/year)",
      "patents": "number[] (10 years, €/year)"
    },
    "useOfFunds": {
      "productDevelopment": "number[] (10 years, €/year)",
      "marketing": "number[] (10 years, €/year)",
      "team": "number[] (10 years, €/year)",
      "structure": "number[] (10 years, €/year)"
    },
    "kpis": {
      "activeUsers": "number[] (10 years)",
      "cac": "number[] (10 years, €)",
      "ltv": "number[] (10 years, €)",
      "breakEvenDays": "number[] (10 years)"
    }
  },
  "notes": "string (optional)",
  "createdAt": "ISO 8601 date string",
  "updatedAt": "ISO 8601 date string"
}
```

## 3. Relations Between Entities

### 3.1 Project Relations
```
Project (1) ──→ (1) TreatmentSite
Project (1) ──→ (N) WasteSite
Project (1) ──→ (N) AdministrativeProcedure (with status)
Project (1) ──→ (N) Investment (with investor reference and status)
Project (1) ──→ (1) Waste (optional override)
```

### 3.2 Treatment Site Relations
```
TreatmentSite (1) ──→ (N) Service (subscribed services)
TreatmentSite (1) ──→ (N) Project
```

### 3.3 Waste Site Relations
```
WasteSite (1) ──→ (1) Waste (waste type)
WasteSite (N) ──→ (1) Project
```

### 3.4 Service Relations
```
Service (N) ──→ (1) TreatmentSite (subscribed)
Service (N) ──→ (N) Project (used in business plan)
```

### 3.5 Investor Relations
```
Investor (1) ──→ (N) Investment (in projects)
Investor (1) ──→ (N) Waste (waste type preferences)
```

### 3.6 Administrative Procedure Relations
```
AdministrativeProcedure (1) ──→ (N) Project (with status per project)
```

## 4. Data Validation Rules

### 4.1 Required Fields
- All entities must have: `id`, `createdAt`
- Projects must have: `name`, `startDate`, `endDate`, `treatmentSiteId`, `numberOfModules`
- Wastes must have: `name`, `bmp`, `waterPercentage`
- Services must have: `name`, `type`, `pricing` (all 10 years)

### 4.2 Value Constraints
- `waterPercentage`: 0-100
- `bmp`: > 0
- `numberOfModules`: > 0
- `startDate` < `endDate`
- All monetary values: >= 0
- All quantities: >= 0

### 4.3 Reference Integrity
- `treatmentSiteId` must exist in `treatmentSites`
- `collectionSiteIds` must exist in `wasteSites`
- `wasteId` in wasteCharacteristicsOverride must exist in `wastes`
- All `procedureId` must exist in `administrativeProcedures`
- All `investorId` must exist in `investors`
- All `serviceId` in subscribedServices must exist in `services`

## 5. Import/Export Format

### 5.1 Export
- Export complete storage structure as JSON
- Include all entities
- Include version number
- Include lastModified timestamp

### 5.2 Import
- Replace entire storage with imported JSON
- Validate structure
- Validate references
- Validate constraints
- If validation fails, keep existing data and show error

### 5.3 Import Validation
1. Check JSON structure validity
2. Check version compatibility
3. Validate all required fields
4. Validate all value constraints
5. Validate all reference integrity
6. If any validation fails, reject import and show detailed errors

## 6. Data Storage Keys

### 6.1 LocalStorage Keys
```
"4nkwaste_simulator_data" - Complete application data (JSON string)
"4nkwaste_simulator_user" - Current user session
"4nkwaste_simulator_version" - Data version
```

### 6.2 IndexedDB Structure (if used)
```
Database: "4nkwaste_simulator"
  - ObjectStore: "wastes"
  - ObjectStore: "regulators"
  - ObjectStore: "services"
  - ObjectStore: "treatmentSites"
  - ObjectStore: "wasteSites"
  - ObjectStore: "investors"
  - ObjectStore: "administrativeProcedures"
  - ObjectStore: "projects"
  - ObjectStore: "users"
```