nicolas.cantu/3TE
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3TE/data_schemas.md
Nicolas Cantu c7db6590f0 Initial commit: 4NK Waste & Water Simulator 
**Motivations :**
* Create a complete simulator for 4NK Waste & Water modular waste treatment infrastructure
* Implement frontend-only application with client-side data persistence
* Provide seed data for wastes and natural regulators from specifications

**Root causes :**
* Need for a simulation tool to configure and manage waste treatment projects
* Requirement for localhost-only access with persistent client-side storage
* Need for initial seed data to bootstrap the application

**Correctifs :**
* Implemented authentication system with AuthContext
* Fixed login/logout functionality with proper state management
* Created placeholder pages for all routes

**Evolutions :**
* Complete application structure with React, TypeScript, and Vite
* Seed data for 9 waste types and 52 natural regulators
* Settings page with import/export and seed data loading functionality
* Configuration pages for wastes and regulators with CRUD operations
* Project management pages structure
* Business plan and yields pages placeholders
* Comprehensive UI/UX design system (dark mode only)
* Navigation system with sidebar and header

**Page affectées :**
* All pages: Login, Dashboard, Waste Configuration, Regulators Configuration, Services Configuration
* Project pages: Project List, Project Configuration, Treatment Sites, Waste Sites, Investors, Administrative Procedures
* Analysis pages: Yields, Business Plan
* Utility pages: Settings, Help
* Components: Layout, Sidebar, Header, base components (Button, Input, Select, Card, Badge, Table)
* Utils: Storage, seed data, formatters, validators, constants
* Types: Complete TypeScript definitions for all entities
2025-12-09 19:09:42 +01:00

11 KiB
Raw Blame History

Data Schemas and Relations

1. JSON Data Structure

1.1 Root Storage Structure

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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"