3TE/specification.md

4NK Waste & Water - Simulator Specification

1. Overview

4NK Waste & Water is developing a simulator for its modular waste treatment infrastructure. The system processes 67T of waste at 75% water content per module, with a total capacity of 21 modules processing 67T of waste at 75% water content per day.

Platform: Desktop-only application (no mobile version or responsive design)

2. Infrastructure Architecture

2.1 Module Configuration

• Module capacity: 67T of waste at 75% water content
• Total modules: 21 modules
• Daily processing capacity: 67T × 21 = 1,407T of waste at 75% water content per day

2.2 Container Configuration (4 × 40-foot containers per module)

Container 1: Mesophilic Anaerobic Digestion

• Function: Anaerobic digestion of waste mixture at ambient temperature
• Processes:
  • Phase separation
  • Hygienization: 18 days
  • Note: STEP sludge cannot be mixed
  • Total duration: 21 days

Container 2: Drying and Bioremediation

• Function: Drying and bioremediation
• Processes:
  • Drying: 21 days
  • Bioremediation: 3 phases depending on waste type × 21 days each
  • Total duration: Variable (21 days + 3 phases × 21 days)

Container 3: Thermophilic Anaerobic Digestion + Composting

• Function: Thermophilic anaerobic digestion and composting with waste mixture
• Processes:
  • Thermophilic digestion: 18 days
  • Composting: 3 days
  • Note: Possible mixing of STEP digestate
  • Total duration: 21 days

Container 4: Water Storage and Spirulina Culture

• Function: Water storage and spirulina culture
• Processes:
  • Spirulina culture: 72-hour cycle → return to thermophilic anaerobic digestion
  • Water wall for cooling (evaporation)
  • Inter-container water cycles only

2.3 Energy Production

Heat Sources

• Biogas generator: Produces energy to power Bitcoin mining machines
• Electric generator: Additional electrical power generation

Solar Panels

• Location: Surface of containers
• Function: Additional electrical power input

2.4 Application Architecture

2.4.1 Technical Stack

• Framework: React (latest version)
• Language: TypeScript
• Routing: React Router
• State Management: None (use React useState, useContext for local state only)
• Build Tool: None (development server only, no build process)
• Package Manager: npm, yarn, or pnpm
• Node.js: Latest LTS version

2.4.2 Project Structure

/src
  /components
    /base          # Base reusable components
    /composite     # Composite components
    /layout        # Layout components (Header, Sidebar)
    /shared        # Shared business logic components
  /pages           # Page components
  /hooks           # Custom React hooks
  /utils
    /calculations  # Calculation functions
    /formatters    # Data formatting
    /validators    # Validation functions
    /constants     # Constants and default values
  /types           # TypeScript type definitions
  /data            # Seed data (optional)

2.4.3 Authentication

• Login system: Simple authentication system
• Access restriction: Localhost only (127.0.0.1 / localhost)
• No remote access: Application must only be accessible from localhost
• Authentication method: Simple username/password or basic authentication
• Session management: Local session management (localStorage)
• Storage: Credentials stored in localStorage (plain or hashed for localhost)

2.4.4 Data Storage

• Storage location: Frontend only (client-side)
• Persistence mechanism: Browser-based persistence (localStorage primary, IndexedDB optional)
• No backend database: All data stored locally in the browser
• Data format: JSON format for data storage
• Storage key: 4nkwaste_simulator_data (localStorage)
• Export/Import:
  • Export: Complete storage structure as JSON (replaces all data)
  • Import: Replace entire storage with imported JSON
  • Validation: Check structure, references, constraints before import
• Data isolation: Data stored per browser (desktop only)
• Versioning: Data structure includes version number for migration

2.4.5 Routing

• Library: React Router (latest version)
• Route structure: Defined in navigation section
• Protected routes: Authentication check before accessing pages
• 404 handling: Default route to dashboard or 404 page
• Deep linking: All pages have unique URLs, bookmarkable

3. Navigation Structure

3.0 Navigation Architecture

3.0.1 Main Navigation Structure

Sidebar Navigation (Left Side - Fixed, Collapsible):

• Width: 256px (collapsed: 64px)
• Background: Background Secondary (#2D2D2D)
• Border right: 1px solid Border (#404040)
• Position: Fixed left
• Z-index: High (above content)

Top Navigation (Header):

• Height: 64px
• Background: Background Secondary (#2D2D2D)
• Border bottom: 1px solid Border (#404040)
• Position: Fixed top
• Contains: Logo, project selector, user info, logout

3.0.2 Navigation Menu Items

Main Sections (Top Level):

1. Dashboard (Home icon)

   • Route: /
   • Purpose: Overview and quick access to key metrics

2. Configuration (Settings icon)

   • Route: /configuration
   • Submenu items:
     • Waste Configuration (/configuration/waste)
     • Natural Regulators (/configuration/regulators)
     • Services (/configuration/services)

3. Projects (Folder icon)

   • Route: /projects
   • Submenu items:
     • Project List (/projects)
     • Treatment Sites (/projects/treatment-sites)
     • Waste Sites (/projects/waste-sites)
     • Investors (/projects/investors)
     • Administrative Procedures (/projects/procedures)

4. Yields (Chart icon)

   • Route: /yields
   • Purpose: Display processing yields and calculations

5. Business Plan (Calculator icon)

   • Route: /business-plan
   • Purpose: Financial analysis and projections

Secondary Items (Bottom of sidebar):

• Settings (Gear icon)

  • Route: /settings
  • Purpose: Application settings, data export/import

• Help (Question mark icon)

  • Route: /help
  • Purpose: Documentation, formulas reference

3.0.3 Navigation Behavior

Active State:

• Active item: Primary Green background (#2D7A4F), white text
• Active indicator: Left border 3px solid Primary Green

Hover State:

• Background: Background Tertiary (#404040)
• Transition: 200ms ease-in-out

Collapsed Sidebar:

• Width: 64px
• Icons only (no text labels)
• Tooltips on hover showing full menu item name
• Expand on click or hover

Breadcrumbs (Top of main content):

• Show current location: Home > Section > Page
• Clickable navigation path
• Font: Body Small, Text Secondary
• Separator: ">" icon

3.0.4 Navigation Icons

Icon Mapping:

• Dashboard: Home/House icon
• Configuration: Settings/Gear icon
• Waste Configuration: Trash/Recycle icon
• Natural Regulators: Leaf/Nature icon
• Services: Briefcase/Services icon
• Projects: Folder/Project icon
• Treatment Sites: Factory/Plant icon
• Waste Sites: Truck/Collection icon
• Investors: Users/People icon
• Administrative Procedures: Document/File icon
• Yields: Chart/Bar chart icon
• Business Plan: Calculator/Money icon
• Settings: Gear/Settings icon
• Help: Question mark/Info icon

Icon Size: 20px (Medium) Icon Style: Outline (default), Solid (active state)

3.0.5 Navigation Structure Details

Hierarchical Organization:

├── Dashboard (/)
├── Configuration (/configuration)
│   ├── Waste Configuration (/configuration/waste)
│   ├── Natural Regulators (/configuration/regulators)
│   └── Services (/configuration/services)
├── Projects (/projects)
│   ├── Project List (/projects)
│   ├── Treatment Sites (/projects/treatment-sites)
│   ├── Waste Sites (/projects/waste-sites)
│   ├── Investors (/projects/investors)
│   └── Administrative Procedures (/projects/procedures)
├── Yields (/yields)
├── Business Plan (/business-plan)
├── Settings (/settings)
└── Help (/help)

Navigation Flow:

1. User logs in → Dashboard
2. Configure data → Configuration section
3. Create/manage projects → Projects section
4. View results → Yields page
5. Analyze finances → Business Plan page

Quick Access:

• Project selector in header (dropdown)
• Recent projects in dashboard
• Direct links from project list to business plan

3. Application Pages

3.0 Dashboard Page

Purpose: Overview and quick access to key metrics and recent projects

Content:

• Key Metrics Summary:

  • Total active projects
  • Total modules in operation
  • Total waste processed (today/week/month)
  • Total revenue (current year)
  • Total bitcoins generated (current year)

• Recent Projects:

  • List of recently accessed projects
  • Quick links to project business plans
  • Project status indicators

• Quick Actions:

  • Create new project
  • Access yields page
  • Access business plan
  • Export data

• Recent Activity:

  • Last configuration changes
  • Last calculations performed
  • Last exports

3.1 Waste Configuration Page

Purpose: Configure waste characteristics

Parameters:

• Origin units of waste (animals/types, invested range, markets/types, restaurants/types...)
• Number of origin units to produce 1000m³ of methane
• BMP (Nm³ CH₄/kg VS)
• Water percentage (%)
• Regulation needs
• Regulatory characteristics
• Maximum storage duration in tank without altering anaerobic digestion

3.2 Natural Regulators Configuration Page

Purpose: Configure natural regulators (non-waste) characteristics

Parameters:

• Regulator type
• Regulatory characteristics
• Application conditions
• Dosage requirements

3.3 Services Configuration Page

Purpose: Configure services with pricing

Services (pricing per module per year over 10 years, first year prototype):

1. Raw rental
2. Biological waste treatment
3. Bitcoin management
4. Provision of standardized fertilizers from compost
5. Provision of waste heat
6. Provision of carbon credit indices
7. Brownfield redevelopment
8. Transport

3.4 Yields Page

Purpose: Display processing yields

Outputs:

• Water (t)
• Fertilizer (t)
• Methane (m³/day)
• CO₂ (m³/day)
• Energy (heat) (kJ/day)
• Energy (heat) (kW.h/day)
• Electrical power (kW) - anaerobic digestion
• Electrical power (kW) - solar panels
• Total electrical power (kW)
• Electrical power (kW) consumed by modules
• Number of 4NK flex miners (2kW)
• Bitcoins BTC/year – Parameter: Number of 4NK Miners (79.2 × 0.0001525 / flex miner)

Calculation Rules Display:

• Always display calculation formulas and rules applied for each output
• Show formulas next to or below each calculated value
• Display input parameters used in calculations
• Show calculation steps when applicable
• Use monospace font for formulas and technical expressions

3.5 Business Plan Page

Purpose: Business plan per project with detailed financial analysis

3.5.1 Project Header

Project Identification:

• Start date - End date: Project duration
• Treatment site(s): Associated treatment site(s)
• Collection site(s): Associated waste collection site(s)
• Number of modules: Number of modules in the project

3.5.2 Economic Characteristics (per year)

Annual economic data displayed for each year of the project (10 years)

REVENUES

• Raw rental: Container rental revenue
• Biological waste treatment service: Waste processing service revenue
• Bitcoin management service: Cryptocurrency mining service revenue
• Provision of standardized fertilizers service: Fertilizer supply service revenue
• Provision of waste heat service: Heat recovery service revenue
• Provision of carbon credit indices service: Carbon credit service revenue
• Brownfield redevelopment service: Site redevelopment service revenue
• Transport service: Transportation service revenue
• Commercial partnerships: Revenue from commercial partnerships
• Other revenues: Additional revenue sources
• TOTAL REVENUES: Sum of all revenue items

VARIABLE COSTS

• Rental & services: Rental and service costs
• Commissions / intermediaries / import: Commission and intermediary costs
• Other variable costs: Additional variable costs
• Transport: Transportation costs
• TOTAL VARIABLE COSTS: Sum of all variable cost items

GROSS MARGIN

• Calculation: TOTAL REVENUES - TOTAL VARIABLE COSTS

FIXED COSTS (OPEX)

• Salaries and social charges: Personnel costs
• Marketing / communication expenses: Marketing and communication costs
• R&D / product development: Research and development costs
• Administrative and legal fees: Administrative and legal expenses
• Other general expenses: Additional general expenses
• TOTAL FIXED COSTS: Sum of all fixed cost items

OPERATING RESULT (EBITDA)

• Calculation: GROSS MARGIN - TOTAL FIXED COSTS

CASH FLOW

• Calculation: OPERATING RESULT - adjustments for cash flow

INVESTMENTS (CAPEX)

• Equipment / machinery: Equipment and machinery investments
• Technology development: Technology development investments
• Patents / IP: Intellectual property investments
• TOTAL INVESTMENTS: Sum of all investment items

FUNDING NEED

• Calculation: Based on investments and cash flow requirements

USE OF RAISED FUNDS

• Product development (POC / MVP): Funds for product development
• Marketing / customer acquisition: Funds for marketing and acquisition
• Team strengthening / recruitment: Funds for team expansion
• Structure / administrative fees: Funds for administrative structure
• TOTAL USE OF FUNDS: Sum of all fund utilization items

KEY INDICATORS (KPIs)

• Active users / clients: Number of active users or clients
• Customer Acquisition Cost (CAC): Cost to acquire one customer
• Lifetime Value (LTV): Customer lifetime value
• Break-even point (days): Number of days to reach break-even

3.5.3 Pricing Characteristics (per year)

Annual pricing parameters and valorization calculations

Valorization Parameters

• Waste treatment valorization / year:

  • Parameter: €/t = 100 €
  • Formula: Waste_treatment_valorization = Waste_quantity (t) × 100 €/t

• Fertilizer valorization / year:

  • Parameter: €/t = 215 €
  • Formula: Fertilizer_valorization = Fertilizer_quantity (t) × 215 €/t

• Heat valorization / year:

  • Parameter: €/t = 0.12 €
  • Formula: Heat_valorization = Heat_quantity (t) × 0.12 €/t

• Carbon equivalent valorization - burned methane (CH₄):

  • Parameter: 630 €/tC ≈ 172 €/tCO₂e
  • Formula: CH4_carbon_valorization = CH4_quantity (tCO₂e) × 172 €/tCO₂e

• Carbon equivalent valorization - sequestered CO₂ (CO₂):

  • Parameter: 100 €/tC ≈ 27 €/tCO₂e
  • Formula: CO2_carbon_valorization = CO2_sequestered (tCO₂e) × 27 €/tCO₂e

• Carbon equivalent valorization - avoided electricity consumption:

  • Parameter: 0.12 €/kW
  • Formula: Energy_carbon_valorization = Electricity_avoided (kW) × 0.12 €/kW

• Bitcoin value:

  • Parameter: 100,000 €
  • Formula: Bitcoin_value = Bitcoin_quantity (BTC) × 100,000 €/BTC

• Land valorization (brownfield):

  • Parameter: 4000 m² brownfield
  • Formula: Land_valorization = Brownfield_area (m²) × valorization_rate

Calculation Rules Display:

• Always display calculation formulas and rules applied for financial metrics
• Show formulas for revenue, cost, and ROI calculations
• Display pricing calculation rules (per module, per year, 10-year model)
• Show service pricing formulas
• Display valorization formulas with parameters
• Use monospace font for formulas and technical expressions
• Show parameter values used in calculations

3.6 Project List Page

Purpose: List and manage all projects

Content:

• Project Table:

  • Project name
  • Treatment site
  • Collection site
  • Number of modules
  • Start date - End date
  • Status (To be approached / LOI OK / In progress / Completed)
  • Actions (Edit, View Business Plan, Delete)

• Filters:

  • Filter by status
  • Filter by treatment site
  • Filter by date range
  • Search by project name

• Actions:

  • Create new project
  • Edit project
  • View business plan
  • Delete project
  • Export project data

3.6.1 Project Configuration Page

Purpose: Configure project parameters and associated entities

Project Parameters:

• Treatment site:
  • Site identification
  • Status: To be approached / LOI OK / In progress / Completed
• Modules per year: Number of modules planned per year
• Waste sites:
  • Waste site type
  • Status: To be approached / LOI OK / In progress / Completed
• Transport by site: Yes/No
• Waste characteristics override: Configuration of waste characteristics overriding standard characteristics
• Administrative procedures (ICPE, spreading, etc.):
  • Procedure type
  • Status: To do / Done / N/A
• Investment:
  • Investor identification
  • Status: To be approached / LOI OK / In progress / Completed
  • Amount

3.7 Treatment Site Configuration Page

Purpose: Configure treatment site characteristics

Parameters:

• Average temperatures by month: Monthly temperature data (12 months)
• Altitude: Site altitude
• Available ground surface: Available surface area for installation
• Subscribed services: List of services subscribed for this site

3.8 Administrative Procedures Configuration Page

Purpose: Configure administrative procedures templates

Parameters:

• Procedure type: Type of administrative procedure (ICPE, spreading, etc.)
• Delays: Processing delays/duration
• Contact / Regions: Contact information and applicable regions

3.9 Investor Configuration Page

Purpose: Configure investor profiles and criteria

Parameters:

• Investor type: Classification of investor type
• Amount range: Minimum and maximum investment amounts
• Geographic regions: Applicable geographic regions
• Waste range: Minimum and maximum waste quantities / waste types
• Solar panels range: Minimum and maximum solar panel capacity

3.10 Waste Site Configuration Page

Purpose: Configure waste source sites

Parameters:

• Waste type: Type of waste produced
• Quantity range: Minimum and maximum quantities / days
• Contact: Contact information
• Waste collection type: Type of waste collection method
• Distance: Distance from treatment site

4. Waste Treatment Configuration

4.1 Treatment Composition

Each waste treatment has:

• Primary waste: Main waste type
• Regulatory wastes: Based on:
  • Client objectives
  • Bioremediation treatment needs based on quality requirements
• Additional natural regulators: Based on:
  • Client objectives
  • Bioremediation treatment needs based on quality requirements

4.2 Client Needs

Nutrient Requirements

• Total Nitrogen (N or NTK)
• Ammoniacal Nitrogen (N-NH₄): Indicator of rapid effect
• Total Phosphorus (P)
• Total Potassium (K)

4.3 Quality Requirements Before Anaerobic Digestion

Heavy Metals and Toxic Elements

• Arsenic (As) elimination
• Other elements elimination: zinc, aluminum, copper
• Heavy metals elimination

Biological Contaminants

• Pathogen elimination

Chemical Parameters

• Low C:N ratio enrichment
• Medication elimination
• Deposit elimination
• Odor elimination
• Turbidity reduction
• Sodium (Na⁺) reduction
• Chlorine (Cl⁻) reduction
• Electrical conductivity reduction
• Sulfide elimination
• Methane elimination
• CO₂ elimination
• Polyphenol elimination
• Elimination of refractory structural fractions (lignin, alginates, fucoidans, crystalline cellulose, and insoluble fibers)

Biological Processes

• Microbiological competition
• Oil emulsification

pH Regulation

• Acidity reduction
• pH increase
• pH reduction

5. Waste Characteristics

5.1 Origin Classification

• Animals/Types: Classification by animal type
• Invested Range: Investment range classification
• Markets/Types: Market type classification
• Restaurants/Types: Restaurant type classification

5.2 Technical Parameters

• Origin units per 1000m³ methane: Number of origin units required
• BMP (Nm³ CH₄/kg VS): Biochemical Methane Potential
• Water percentage (%): Moisture content
• Regulation needs: Required regulatory adjustments
• Regulatory characteristics: Specific regulatory properties
• Maximum storage duration: Maximum time in tank without affecting anaerobic digestion

6. Services and Pricing

6.1 Service List

1. Raw Rental: Container rental service
2. Biological Waste Treatment: Waste processing service
3. Bitcoin Management: Cryptocurrency mining management
4. Provision of Standardized Fertilizers: Compost-based fertilizer supply
5. Provision of Waste Heat: Heat recovery service
6. Provision of Carbon Credit Indices: Carbon credit index service
7. Brownfield Redevelopment: Site redevelopment service
8. Transport: Transportation service

6.2 Pricing Model

• Unit: Price per module per year
• Duration: 10 years
• First year: Prototype pricing
• Configuration: Configurable per service

7. Yields and Performance Metrics

7.1 Material Outputs

• Water (t): Processed water output
• Fertilizer (t): Compost/fertilizer output

7.2 Gas Outputs

• Methane (m³/day): Daily methane production
• CO₂ (m³/day): Daily CO₂ production

7.3 Energy Outputs

• Energy (heat) (kJ/day): Daily heat energy production
• Energy (heat) (kW.h/day): Daily heat energy in kilowatt-hours

7.4 Electrical Power

• Electrical power (kW) - Anaerobic digestion: Power from biogas generator
• Electrical power (kW) - Solar panels: Power from solar panels
• Total electrical power (kW): Combined electrical power
• Electrical power (kW) consumed by modules: Power consumption by processing modules

7.5 Bitcoin Mining

• Number of 4NK flex miners: Count of 2kW mining units
• Bitcoins BTC/year: Annual Bitcoin production
  • Calculation: 79.2 × 0.0001525 / flex miner
  • Parameter: Number of 4NK Miners

8. Technical Specifications

8.1 Processing Times

• Mesophilic digestion: 18 days hygienization + 3 days = 21 days total
• Drying: 21 days
• Bioremediation phases: 3 phases × 21 days each (variable)
• Thermophilic digestion: 18 days
• Composting: 3 days
• Spirulina cycle: 72 hours

8.2 Container Specifications

• Type: 40-foot containers
• Quantity per module: 4 containers
• Total containers: 21 modules × 4 = 84 containers

8.3 Mining Equipment

• 4NK Flex Miner: 2kW per unit
• Power consumption: Variable based on number of miners

9. Data Model Requirements

9.1 Waste Data Model

• Waste type identification
• Origin classification
• Physical and chemical characteristics
• BMP values
• Water content
• Regulatory needs
• Storage constraints

9.2 Regulator Data Model

• Regulator type (waste or natural)
• Regulatory characteristics
• Application conditions
• Dosage specifications

9.3 Service Data Model

• Service type
• Pricing structure (10-year model)
• Module association
• Project association

9.4 Yield Data Model

• Material outputs
• Gas outputs
• Energy outputs
• Electrical power metrics
• Bitcoin production metrics

9.5 Business Plan Data Model

• Project Header:

  • Start date - End date
  • Treatment site(s) association
  • Collection site(s) association
  • Number of modules

• Economic Characteristics (per year, 10 years):

  • Revenues (all service revenues, partnerships, other)
  • Variable costs (rental, commissions, transport, other)
  • Fixed costs (salaries, marketing, R&D, administrative, other)
  • Investments (equipment, technology, patents/IP)
  • Use of raised funds (development, marketing, team, structure)
  • KPIs (active users/clients, CAC, LTV, break-even)

• Pricing Characteristics (per year):

  • Valorization parameters (waste treatment, fertilizer, heat, carbon equivalents, bitcoin, land)
  • Valorization calculations with formulas
  • Parameter values

• Financial Calculations:

  • Gross margin
  • Operating result (EBITDA)
  • Cash flow
  • Funding need
  • Break-even point
  • CAC and LTV

9.6 Project Data Model

• Project identification
• Treatment site association
• Modules per year configuration
• Waste sites association
• Transport configuration
• Waste characteristics overrides
• Administrative procedures tracking
• Investment tracking

9.7 Treatment Site Data Model

• Site identification
• Geographic data (altitude, coordinates)
• Monthly temperature data (12 values)
• Available ground surface
• Subscribed services list
• Status tracking

9.8 Administrative Procedure Data Model

• Procedure type
• Standard delays
• Contact information
• Applicable regions
• Status tracking per project

9.9 Investor Data Model

• Investor type
• Investment amount range (min/max)
• Geographic regions
• Waste quantity range (min/max)
• Waste type preferences
• Solar panel capacity range (min/max)
• Status tracking per project

9.10 Waste Site Data Model

• Site identification
• Waste type
• Quantity range (min/max per day)
• Contact information
• Collection type
• Distance from treatment site
• Status tracking

9.11 Authentication Data Model

• User credentials (username/password)
• Session information
• Login status
• Access timestamp

9.12 Local Storage Data Model

• Storage structure: JSON format
• Data versioning
• Timestamp for each data entry
• Data categories:
  • Projects
  • Configurations
  • Yields
  • Business plans
  • Sites
  • Investors
  • Administrative procedures

10. Calculation Requirements

10.1 Methane Production

• Based on BMP (Nm³ CH₄/kg VS)
• Waste input quantities
• Processing efficiency factors

10.2 Energy Calculations

• Biogas to electricity conversion
• Solar panel output
• Module consumption
• Net energy balance

10.3 Bitcoin Production

• Formula: 79.2 × 0.0001525 / flex miner
• Based on number of 4NK flex miners
• Annual production calculation

10.4 Water Balance

• Input water from waste (75% of 67T)
• Water consumption in processes
• Water output from spirulina cycle
• Inter-container water cycles

10.5 Fertilizer Production

• Based on composting output
• Quality parameters (N, P, K)
• Standardization requirements

10.6 Valorization Calculations

Waste Treatment Valorization

• Formula: Waste_treatment_valorization (€/year) = Waste_quantity (t/year) × 100 €/t
• Parameter: 100 €/t

Fertilizer Valorization

• Formula: Fertilizer_valorization (€/year) = Fertilizer_quantity (t/year) × 215 €/t
• Parameter: 215 €/t

Heat Valorization

• Formula: Heat_valorization (€/year) = Heat_quantity (t/year) × 0.12 €/t
• Parameter: 0.12 €/t

Carbon Equivalent - Burned Methane (CH₄)

• Formula: CH4_carbon_valorization (€/year) = CH4_quantity (tCO₂e/year) × 172 €/tCO₂e
• Parameter: 630 €/tC ≈ 172 €/tCO₂e
• Conversion: 1 tC = 3.67 tCO₂e

Carbon Equivalent - Sequestered CO₂

• Formula: CO2_carbon_valorization (€/year) = CO2_sequestered (tCO₂e/year) × 27 €/tCO₂e
• Parameter: 100 €/tC ≈ 27 €/tCO₂e
• Conversion: 1 tC = 3.67 tCO₂e

Carbon Equivalent - Avoided Electricity Consumption

• Formula: Energy_carbon_valorization (€/year) = Electricity_avoided (kW/year) × 0.12 €/kW
• Parameter: 0.12 €/kW

Bitcoin Valorization

• Formula: Bitcoin_value (€) = Bitcoin_quantity (BTC) × 100,000 €/BTC
• Parameter: 100,000 €/BTC

Land Valorization (Brownfield)

• Formula: Land_valorization (€) = Brownfield_area (m²) × valorization_rate (€/m²)
• Parameter: 4000 m² brownfield (configurable valorization rate)

10.7 Financial Calculations

Gross Margin

• Formula: Gross_Margin = Total_Revenues - Total_Variable_Costs

Operating Result (EBITDA)

• Formula: EBITDA = Gross_Margin - Total_Fixed_Costs

Cash Flow

• Formula: Cash_Flow = EBITDA - Non_cash_adjustments - Working_capital_changes

Funding Need

• Formula: Funding_Need = Total_Investments - Available_Cash - Cash_Flow

Break-even Point

• Formula: Break_even_days = Fixed_Costs / (Daily_Revenue - Daily_Variable_Costs)

Customer Acquisition Cost (CAC)

• Formula: CAC = Marketing_Costs / Number_of_New_Customers

Lifetime Value (LTV)

• Formula: LTV = Average_Revenue_per_Customer × Average_Customer_Lifespan

11. User Interface Requirements

11.0 Calculation Rules Display (General Requirement)

Mandatory Display of Calculation Rules:

• Always Visible: Calculation formulas and rules must always be displayed on pages that show calculated results
• Display Format:
  • Formulas displayed in monospace font (JetBrains Mono, Fira Code, or Courier New)
  • Clear formatting with variable names and values
  • Formulas can be displayed inline, in expandable sections, or in dedicated formula panels
• Content Requirements:
  • Show the complete calculation formula
  • Display input parameters used in the calculation
  • Show intermediate calculation steps when applicable
  • Indicate units of measurement
  • Reference to calculation source/section when applicable
• Placement:
  • Next to or below calculated values
  • In expandable/collapsible sections for complex formulas
  • In tooltips for simple formulas (with option to expand)
  • In dedicated "Calculation Rules" panel or section
• Examples:
  • Bitcoin calculation: BTC/year = 79.2 × 0.0001525 / flex_miner
  • Methane production: Methane (m³/day) = BMP × Waste_quantity × Efficiency_factor
  • Energy conversion: Energy (kW.h/day) = Energy (kJ/day) / 3600
• Styling:
  • Background: Background Secondary
  • Border: 1px solid Border
  • Padding: 12px 16px
  • Border radius: 8px
  • Font: Monospace, Body Small size
  • Text color: Text Primary

11.1 Configuration Pages

• Intuitive form-based interfaces
• Dropdown selections for waste types
• Parameter input fields with validation
• Real-time calculation previews
• Calculation Rules Visibility:
  • Display calculation formulas when parameters affect calculations
  • Show how input parameters influence results
  • Display validation rules and constraints
  • Use monospace font for formulas and technical expressions

11.2 Yields Display

• Dashboard-style visualization
• Real-time metrics
• Historical data tracking
• Export capabilities
• Calculation Rules Visibility:
  • Always display calculation formulas alongside calculated values
  • Show formulas in expandable sections or tooltips
  • Display input parameters used in each calculation
  • Use monospace font for formulas
  • Format: Formula displayed clearly with variable names and values

11.3 Business Plan Interface

• Project Header Section:

  • Date range selector (start date - end date)
  • Treatment site(s) selection
  • Collection site(s) selection
  • Number of modules input

• Economic Characteristics Section (per year, 10-year view):

  • Revenues table/inputs (all service revenues, partnerships, other)
  • Variable costs table/inputs (rental, commissions, transport, other)
  • Fixed costs table/inputs (salaries, marketing, R&D, administrative, other)
  • Investments table/inputs (equipment, technology, patents/IP)
  • Use of raised funds table/inputs (development, marketing, team, structure)
  • KPIs display/inputs (active users/clients, CAC, LTV, break-even)
  • Automatic calculations (gross margin, EBITDA, cash flow, funding need)

• Pricing Characteristics Section (per year):

  • Valorization parameter configuration
  • Valorization calculation display with formulas
  • Parameter value inputs (€/t, €/tCO₂e, €/kW, €/BTC, etc.)
  • Real-time valorization calculations

• Financial Projections Display:

  • 10-year financial table/graph
  • Year-by-year breakdown
  • Cumulative calculations
  • Report generation and export

• Calculation Rules Visibility:

  • Always display financial calculation formulas
  • Show pricing calculation rules (per module, per year, 10-year model)
  • Display ROI calculation formulas
  • Show revenue and cost calculation methods
  • Display all valorization formulas with parameters
  • Use monospace font for formulas
  • Format: Formulas displayed clearly with explanations

11.4 Project Management Interface

• Project creation and editing
• Treatment site configuration
• Waste site management
• Investor management
• Administrative procedures tracking
• Status workflow management
• Multi-project dashboard

11.5 Authentication Interface

• Simple login page
• Username/password input
• Session status display
• Logout functionality
• Localhost access indicator

11.6 UI/UX Design System

11.6.1 Color Palette

Note: All colors defined below are for dark mode only. The application does not support theme switching.

Primary Colors

• Primary Green: #2D7A4F (Main brand color - waste treatment, sustainability)
• Primary Green Light: #4A9D6E (Hover states, highlights)
• Primary Green Dark: #1F5A3A (Active states, emphasis)
• Primary Green Accent: #6BC48A (Success states, positive actions)

Secondary Colors

• Secondary Blue: #2563EB (Information, data visualization)
• Secondary Blue Light: #3B82F6 (Hover states)
• Secondary Blue Dark: #1E40AF (Active states)

Neutral Colors (Dark Mode Only)

• Background: #1A1A1A (Main background)
• Background Secondary: #2D2D2D (Secondary surfaces, cards)
• Background Tertiary: #404040 (Borders, dividers)
• Text Primary: #FFFFFF (Main text, headings)
• Text Secondary: #B0B0B0 (Secondary text, labels)
• Text Tertiary: #808080 (Placeholder text, disabled)
• Border: #404040 (Default borders)
• Border Focus: #4A9D6E (Focus states - Primary Green Light)

Status Colors

• Success: #10B981 (Positive actions, success messages)
• Warning: #F59E0B (Warnings, caution)
• Error: #EF4444 (Errors, destructive actions)
• Info: #3B82F6 (Informational messages)
• Pending: #F59E0B (In progress states)
• Completed: #10B981 (Completed states)
• To Do: #6C757D (Pending states)

Status Workflow Colors

• To be approached: #F59E0B (Orange - initial state)
• LOI OK: #3B82F6 (Blue - letter of intent approved)
• In progress: #8B5CF6 (Purple - active work)
• Completed: #10B981 (Green - finished)
• N/A: #9CA3AF (Gray - not applicable)

11.6.2 Typography

Font Family

• Primary Font: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', sans-serif
• Monospace Font: 'JetBrains Mono', 'Fira Code', 'Courier New', monospace (for technical data, calculations)

Font Sizes

• H1: 2.5rem (40px) - Page titles
• H2: 2rem (32px) - Section titles
• H3: 1.5rem (24px) - Subsection titles
• H4: 1.25rem (20px) - Card titles
• Body Large: 1.125rem (18px) - Important body text
• Body: 1rem (16px) - Default body text
• Body Small: 0.875rem (14px) - Secondary text, labels
• Caption: 0.75rem (12px) - Captions, metadata

Font Weights

• Bold: 700 - Headings, emphasis
• Semi-bold: 600 - Subheadings, important labels
• Medium: 500 - Buttons, interactive elements
• Regular: 400 - Body text
• Light: 300 - Decorative text

Line Heights

• Tight: 1.2 - Headings
• Normal: 1.5 - Body text
• Relaxed: 1.75 - Long-form content

11.6.3 Spacing System

Base Unit

• Base: 4px (all spacing multiples of 4)

Spacing Scale

• xs: 4px (0.25rem)
• sm: 8px (0.5rem)
• md: 16px (1rem)
• lg: 24px (1.5rem)
• xl: 32px (2rem)
• 2xl: 48px (3rem)
• 3xl: 64px (4rem)
• 4xl: 96px (6rem)

Component Spacing

• Form fields: 16px vertical spacing
• Card padding: 24px
• Section spacing: 48px
• Page padding: 32px

11.6.4 Border Radius

• None: 0px - Sharp corners
• sm: 4px - Small elements (badges, tags)
• md: 8px - Default (buttons, inputs, cards)
• lg: 12px - Large cards, modals
• xl: 16px - Hero sections
• Full: 9999px - Pills, avatars

11.6.5 Shadows (Dark Mode)

• sm: 0 1px 2px 0 rgba(0, 0, 0, 0.3) - Subtle elevation
• md: 0 4px 6px -1px rgba(0, 0, 0, 0.4), 0 2px 4px -1px rgba(0, 0, 0, 0.3) - Cards
• lg: 0 10px 15px -3px rgba(0, 0, 0, 0.5), 0 4px 6px -2px rgba(0, 0, 0, 0.4) - Modals, dropdowns
• xl: 0 20px 25px -5px rgba(0, 0, 0, 0.6), 0 10px 10px -5px rgba(0, 0, 0, 0.5) - Large modals
• Note: Shadows are more pronounced in dark mode for better depth perception

11.6.6 Components

Buttons

• Primary Button:

  • Background: Primary Green (#2D7A4F)
  • Text: #FFFFFF (White)
  • Padding: 12px 24px
  • Border radius: 8px
  • Font weight: 500
  • Hover: Primary Green Light (#4A9D6E)
  • Active: Primary Green Dark (#1F5A3A)
  • Disabled: Background Secondary, Text Tertiary, cursor: not-allowed

• Secondary Button:

  • Background: Transparent
  • Border: 1px solid Border
  • Text: Text Primary
  • Padding: 12px 24px
  • Border radius: 8px
  • Hover: Background Secondary

• Danger Button:

  • Background: Error (#EF4444)
  • Text: #FFFFFF (White)
  • Hover: Darker red shade

• Icon Button:

  • Square: 40px × 40px
  • Circular border radius
  • Icon centered

Input Fields

• Text Input:

  • Height: 44px
  • Background: Background Secondary
  • Padding: 12px 16px
  • Border: 1px solid Border
  • Border radius: 8px
  • Text color: Text Primary
  • Focus: 2px solid Border Focus
  • Error: Border Error color
  • Placeholder: Text Tertiary

• Select/Dropdown:

  • Same as text input
  • Background: Background Secondary
  • Dropdown options: Background Secondary
  • Dropdown arrow indicator
  • Max height: 300px for options list

• Textarea:

  • Min height: 100px
  • Background: Background Secondary
  • Text color: Text Primary
  • Resizable: vertical only
  • Same border and focus styles as input

• Checkbox/Radio:

  • Size: 20px × 20px
  • Border: 2px solid Border
  • Checked: Primary Green background
  • Focus: Ring with Border Focus color

Cards

• Card Container:

  • Background: Background Secondary
  • Padding: 24px
  • Border radius: 12px
  • Shadow: md
  • Border: 1px solid Border (optional)

• Card Header:

  • Padding bottom: 16px
  • Border bottom: 1px solid Border (optional)
  • Font size: H4
  • Font weight: 600

Status Badges

• Badge:
  • Padding: 4px 12px
  • Border radius: Full
  • Font size: Body Small
  • Font weight: 500
  • Colors based on status (see Status Colors)

Tables

• Table Container:

  • Border: 1px solid Border
  • Border radius: 8px
  • Overflow: hidden

• Table Header:

  • Background: Background Secondary
  • Font weight: 600
  • Padding: 12px 16px
  • Text align: left

• Table Row:

  • Border bottom: 1px solid Border
  • Padding: 12px 16px
  • Hover: Background Secondary

Navigation

• Sidebar Navigation:

  • Width: 256px (collapsed: 64px)
  • Background: Background Secondary (#2D2D2D)
  • Border right: 1px solid Border (#404040)
  • Active item: Primary Green background (#2D7A4F), white text (#FFFFFF)
  • Active indicator: Left border 3px solid Primary Green
  • Hover: Background Tertiary (#404040)
  • Icon size: 20px (Medium)
  • Item padding: 12px 16px
  • Font: Body, Text Primary
  • Transition: 200ms ease-in-out

• Top Navigation (Header):

  • Height: 64px
  • Background: Background Secondary (#2D2D2D)
  • Border bottom: 1px solid Border (#404040)
  • Padding: 0 32px
  • Display: Flex, space-between, align-center
  • Contains: Logo (left), Project selector (center), User info + Logout (right)

• Breadcrumbs:

  • Position: Top of main content area
  • Font: Body Small, Text Secondary (#B0B0B0)
  • Separator: ">" icon, Text Tertiary (#808080)
  • Padding: 16px 0
  • Clickable: All items except current page

Modals/Dialogs

• Modal Overlay:

  • Background: rgba(0, 0, 0, 0.7)
  • Backdrop blur: 4px

• Modal Container:

  • Background: Background Secondary
  • Border radius: 16px
  • Shadow: xl
  • Max width: 600px (default)
  • Padding: 32px
  • Border: 1px solid Border

Forms

• Form Group:

  • Margin bottom: 24px

• Label:

  • Font size: Body Small
  • Font weight: 500
  • Color: Text Primary
  • Margin bottom: 8px
  • Display: block

• Error Message:

  • Font size: Caption
  • Color: Error
  • Margin top: 4px

• Help Text:

  • Font size: Caption
  • Color: Text Secondary
  • Margin top: 4px

Calculation Formula Display

• Formula Container:

  • Background: Background Secondary
  • Border: 1px solid Border
  • Border radius: 8px
  • Padding: 12px 16px
  • Margin: 8px 0

• Formula Label:

  • Font size: Body Small
  • Font weight: 500
  • Color: Text Secondary
  • Margin bottom: 8px

• Formula Content:

  • Font: Monospace (JetBrains Mono, Fira Code, or Courier New)
  • Font size: Body Small
  • Color: Text Primary
  • White-space: pre-wrap (preserve formatting)
  • Line height: 1.6

• Formula Variables:

  • Display input values used in calculation
  • Format: variable_name = value (unit)
  • Color: Text Secondary for variable names, Text Primary for values

• Expandable Formula (for complex calculations):

  • Collapsed: Show formula summary
  • Expanded: Show full formula with steps
  • Toggle button: Icon button with chevron

11.6.7 Icons

• Icon Library: Heroicons, Lucide, or similar
• Icon Size:
  • Small: 16px
  • Medium: 20px
  • Large: 24px
  • Extra Large: 32px
• Icon Style: Outline for most cases, solid for emphasis
• Icon Color: Inherit text color or use semantic colors

11.6.8 Data Visualization

Charts

• Color Scheme: Use Primary Green and Secondary Blue as base
• Grid Lines: Border color, opacity 0.3
• Axis Labels: Text Secondary, Body Small
• Tooltips: Background Secondary, shadow md, padding 8px 12px

Metrics/KPI Cards

• Value: H2 or H3, Primary Green or Text Primary
• Label: Body Small, Text Secondary
• Trend Indicator: Arrow icon with Success/Error color
• Background: Background Secondary
• Border: Optional, 1px solid Border

11.6.9 Layout

Grid System

• Container Max Width: 1280px
• Grid Columns: 12 columns
• Gutter: 24px
• Target Platform: Desktop only (minimum width: 1024px)
• No Mobile Support: Application designed exclusively for desktop browsers

Page Structure

• Header: Fixed or sticky, 64px height, Background Secondary
• Sidebar: Fixed, 256px width (collapsible), Background Secondary
• Main Content: Flexible, padding 32px, Background (dark)
• Footer: Optional, 64px height, Background Secondary

11.6.10 UX Principles

Navigation

• Breadcrumbs: Show current location in multi-level navigation
• Active States: Clear indication of current page/section
• Back Navigation: Consistent back button placement

Feedback

• Loading States: Skeleton loaders or spinners
• Success Messages: Toast notifications, green badge
• Error Messages: Inline errors, toast notifications, red badge
• Confirmation Dialogs: For destructive actions

Accessibility

• Color Contrast: Minimum WCAG AA (4.5:1 for normal text, 3:1 for large text)
• Focus Indicators: Visible focus rings (2px, Border Focus color)
• Keyboard Navigation: Full keyboard support
• Screen Readers: Proper ARIA labels, semantic HTML
• Text Alternatives: Alt text for icons and images

Desktop-Only Design

• No Mobile Version: Application is desktop-only, no mobile compatibility
• No Responsive Design: Fixed layout optimized for desktop screens (minimum 1024px width)
• No Touch Support: Designed for mouse and keyboard interaction only
• Fixed Layout: Sidebar and components maintain fixed sizes, no responsive breakpoints

Consistency

• Component Reuse: Use consistent components throughout
• Spacing: Follow spacing system
• Terminology: Consistent language across application
• Patterns: Reuse interaction patterns

11.6.11 Component Architecture Principles

Code Reusability

• Maximum Reuse: Prioritize component reuse over creating new components
• Shared Components Library: Maintain a centralized library of reusable components
• Composition Over Duplication: Build complex components by composing simple ones
• DRY Principle: Don't Repeat Yourself - extract common logic into reusable functions/components
• Component Hierarchy:
  • Base components (Button, Input, Card) - most reusable
  • Composite components (Form, Table, Modal) - composed of base components
  • Page-specific components - minimal, use composites when possible
• Props Interface: Standardize props interfaces across similar components
• Shared Utilities: Extract common utilities, helpers, and hooks into shared modules
• Template Patterns: Use consistent patterns for similar features (CRUD operations, forms, lists)

Component Simplicity

• Simple Technical Implementation:
  • Avoid complex state management patterns
  • Prefer straightforward component structure
  • Use standard React patterns (functional components, hooks)
  • Avoid advanced optimizations (memo, useMemo, useCallback)
  • Keep components focused on single responsibility
• Readable Code:
  • Clear naming conventions
  • Simple logic flow
  • Minimal nesting
  • Self-documenting code
• No Premature Optimization:
  • Write straightforward code first
  • Avoid performance optimizations unless explicitly needed
  • Focus on functionality and maintainability
• Standard Patterns:
  • Use standard library functions
  • Follow framework conventions
  • Avoid custom abstractions unless necessary
• Component Size:
  • Keep components small and focused
  • Split large components into smaller, reusable pieces
  • Maximum 200-300 lines per component file

Component Structure

• Base Components (highest reusability):
  • Button, Input, Select, Textarea, Checkbox, Radio
  • Card, Badge, Label, Icon
  • Modal, Toast, Tooltip
  • FormulaDisplay (for showing calculation rules)
• Composite Components (medium reusability):
  • Form (composed of Input, Select, etc.)
  • Table (composed of Card, Badge, etc.)
  • Navigation (composed of Button, Icon, etc.)
  • DataDisplay (composed of Card, Badge, etc.)
• Page Components (low reusability, use composites):
  • Configuration pages use Form components
  • Yields page uses DataDisplay components
  • Business plan uses shared calculation components

Shared Code Organization

• Components Directory Structure:

  /components
    /base          # Most reusable (Button, Input, etc.)
    /composite     # Composed components (Form, Table, etc.)
    /layout        # Layout components (Header, Sidebar, etc.)
    /shared        # Shared business logic components
  

• Utilities Directory:

  /utils
    /calculations  # Calculation functions
    /formatters    # Data formatting
    /validators    # Validation functions
    /constants     # Shared constants
  

• Hooks Directory:

  /hooks
    /useForm       # Form management
    /useStorage    # LocalStorage management
    /useAuth       # Authentication
  

Reusability Guidelines

• Before Creating New Component:
  1. Check if existing component can be extended with props
  2. Check if composition of existing components solves the need
  3. Only create new component if truly unique functionality needed
• Component Props:
  • Use flexible props to allow reuse in different contexts
  • Provide sensible defaults
  • Support common use cases out of the box
• Styling:
  • Use shared style constants/variables
  • Support className prop for customization
  • Avoid inline styles, use CSS classes or styled-components consistently
• State Management:
  • Keep state local when possible
  • Use shared state management only when necessary
  • Prefer props over context for simple data passing

Technical Constraints

• No Performance Optimizations:
  • Do not use React.memo()
  • Do not use useMemo() for calculations
  • Do not use useCallback() for functions
  • Do not implement code splitting
  • Do not implement lazy loading
  • Do not optimize re-renders
  • Keep code simple and straightforward
• Standard Implementation:
  • Use standard React hooks (useState, useEffect, useContext)
  • Use standard JavaScript/TypeScript features
  • Avoid complex patterns or abstractions
  • Prefer explicit over implicit
• Simplicity First:
  • If there's a simple way and a complex way, choose simple
  • Avoid over-engineering
  • Focus on working code over optimized code

11.6.12 Animation & Transitions

Transitions

• Duration:
  • Fast: 150ms (hover, active states)
  • Normal: 200ms (default transitions)
  • Slow: 300ms (page transitions, modals)
• Easing:
  • Default: ease-in-out
  • Enter: ease-out
  • Exit: ease-in

Animations

• Fade In: For modals, dropdowns
• Slide: For sidebars, drawers
• Scale: For buttons on click
• Pulse: For loading indicators
• Smooth Scrolling: For page navigation

11.6.13 Theme Configuration

Dark Mode Only - No Theme Switching

• The application uses dark mode exclusively
• No theme selector or switching functionality
• No light mode support
• All color definitions above are for dark mode
• Color palette:
  • Background: #1A1A1A
  • Background Secondary: #2D2D2D
  • Text Primary: #FFFFFF
  • Text Secondary: #B0B0B0
  • Border: #404040
• Maintain consistent color relationships and contrast ratios throughout

12. Validation Rules

12.1 Waste Configuration

• BMP values must be positive
• Water percentage: 0-100%
• Storage duration must be realistic
• Origin units must be valid

12.2 Regulator Configuration

• Dosage must be within safe limits
• Compatibility checks with waste types
• Application timing validation

12.3 Service Configuration

• Pricing must be positive
• Service combinations must be valid
• Module capacity constraints

12.4 Yield Calculations

• Energy balance validation
• Material balance validation
• Gas production validation

12.5 Project Configuration

• Treatment site must be valid
• Module count must be positive
• Waste sites must be compatible
• Investment amounts must be within investor ranges
• Administrative procedures must be valid
• Distance calculations must be realistic

12.6 Treatment Site Configuration

• Temperature values must be realistic
• Altitude must be valid
• Surface area must accommodate modules
• Services must be compatible

12.7 Waste Site Configuration

• Quantity ranges must be positive
• Distance must be realistic
• Collection type must be valid
• Waste type must match project requirements

13. Integration Requirements

13.1 Data Persistence

• Storage mechanism: Browser-based storage (localStorage, IndexedDB)
• Data types stored:
  • Configuration storage
  • Historical yield data
  • Business plan storage
  • Project management
  • Treatment site data
  • Waste site data
  • Investor data
  • Administrative procedures tracking
  • User authentication data
• Persistence strategy: Automatic save on data modification
• Data backup: Export/import functionality for data backup
• Storage limits: Browser storage quota management
• Data migration: Support for data structure versioning and migration

13.2 Reporting

• Yield reports
• Business plan reports
• Service reports
• Export formats (PDF, Excel, CSV)

13.3 Real-time Updates

• Live yield calculations
• Dynamic pricing updates
• Real-time energy balance

13.4 Security Requirements

• Localhost restriction: Application must only run on localhost
• No network access: No external API calls or network requests
• Client-side only: All processing and storage on client-side
• Authentication: Simple login system for local access control
• Data encryption: Optional encryption for sensitive data in local storage

14. Future Enhancements

14.1 Advanced Features

• Multi-project management
• Comparative analysis
• Optimization algorithms
• Predictive modeling

14.2 Integration Capabilities

• External data sources
• API integrations
• Third-party service connections