Skip to content
PLANOVI Docs

Energy Cooperative Module

Energy Cooperative Module (Kooperatywa Energetyczna)

The Energy Cooperative module (lib/features/energy_coop/) is the central operational domain of PLANOVI. Built to comply with European and Polish renewable energy cooperative regulations (Ustawa o Odnawialnych Źródłach Energii), it coordinates multi-producer energy balancing, IoT asset control, democratic governance, and field service management.

Architectural Subsystems

graph TB
    subgraph Core_Telemetry ["1. Telemetry & Balancing Engine"]
        Dash[EnergyDashboardScreen]
        Balance[EnergyBalanceScreen]
        Devices[MyDevicesScreen]
        Edge_Balance[ai-energy-balancer Edge Function]
        Tauron_Edge[process-tauron-csv Edge Function]
    end

    subgraph Economics ["2. Member Economics & Ledger"]
        Wallet[MemberWalletScreen]
        Ledger[FinancialLedgerScreen]
        Invoicing[generate-monthly-invoices Function]
    end

    subgraph Democratic_Governance ["3. Democratic Governance"]
        Gov[GovernanceCenterScreen]
        Resolutions[generate-resolution-document]
        Declarations[TeamDeclarationsScreen]
        OCR[process-declaration-ocr Function]
    end

    subgraph Field_Operations ["4. Field Dispatch & Support"]
        TechQueue[TechnicianQueueScreen]
        WorkOrders[WorkOrderProvider]
        KB[KnowledgeBaseScreen]
    end

    Dash --> Devices
    Balance --> Edge_Balance
    Balance --> Tauron_Edge
    Wallet --> Invoicing
    Ledger --> Invoicing
    Gov --> Resolutions
    Declarations --> OCR
    TechQueue --> WorkOrders

Screen & Feature Reference Catalog

1. Energy Dashboard (energy_dashboard_screen.dart)

  • Purpose: High-fidelity visual dashboard of real-time generation, consumption, and storage metrics across the cooperative’s grid.
  • Key Visuals:
    • Solar yield line graphs with comparison against historical baselines.
    • Real-time Battery State of Charge (SoC) gauges.
    • Self-consumption and self-sufficiency percentages.
    • Carbon offset equivalents (kg of $CO_2$ saved).
  • Technologies: Rendered using fl_chart with gradient fills and smooth curve interpolation.

2. My Devices (my_devices_screen.dart)

  • Purpose: Hardware management portal for inverters, smart meters, heat pumps, and home storage units.
  • Capabilities:
    • Live status monitoring: online (green), degraded (amber), alarm (red), offline (grey).
    • Inverter throttle commands: Limit export power to prevent local grid over-voltage.
    • Telemetry log inspector: Inspect raw voltage, current, power factor, and frequency readings.
  • Provider: DeviceControlProvider & TelemetryProvider.

3. Energy Balance & Auto-Balancing (energy_balance_screen.dart)

  • Purpose: Tracks 15-minute settlement intervals to maximize cooperative self-consumption and minimize grid tariffs.
  • Tauron Integration: Coordinates with Distribution System Operators (OSD) via process-tauron-csv to ingest official grid meter readings.
  • AI Balancer: Invokes the ai-energy-balancer edge function to optimize storage charging and heat pump actuation before peak tariff spikes.

4. Member Wallet (member_wallet_screen.dart)

  • Purpose: Digital account for each cooperative member.
  • Components:
    • Virtual balance of tokenized energy units (kWh credits).
    • Energy shares: Percentage of ownership in cooperative solar parks.
    • Monthly settlement summaries: Savings compared to standard utility provider rates.

5. Financial Ledger (financial_ledger_screen.dart)

  • Purpose: Auditable double-entry accounting ledger of energy trades within the cooperative.
  • Exporting: Direct generation of official audit reports using pdf and printing packages, enabling instant export to PDF or CSV.

6. Democratic Governance Center (governance_center_screen.dart)

  • Purpose: Electronic voting system adhering to statutory cooperative rules (one member = one vote).
  • Voting Workflow: 
    sequenceDiagram
    actor Member
    participant UI as GovernanceCenterScreen
    participant GovP as GovernanceProvider
    participant Edge as generate-resolution-document
    participant DB as "Postgres (RLS)"

    Member->>UI: Casts Ballot (For / Against / Abstain)
    UI->>GovP: castVote(resolutionId, option)
    GovP->>DB: Insert encrypted vote record
    Note over DB: Quorum reached & voting closes
    GovP->>Edge: Trigger resolution finalization
    Edge->>Edge: Render formal PDF document with digital hashes
    Edge-->>UI: Resolution finalized and archived in Knowledge Base

7. Team Declarations & Onboarding (team_declarations_screen.dart)

  • Purpose: Prospective member intake and KYC verification.
  • OCR Ingestion: When members upload their paper declarations or utility bills, process-declaration-ocr extracts meter numbers (PPE), addresses, and contract parameters automatically.

8. Technician Queue (technician_queue_screen.dart)

  • Purpose: Dispatch panel for field technicians inspecting PV installations, inverters, and transmission lines.
  • Features:
    • Work order status pipeline: Pending $\to$ Assigned $\to$ In Progress $\to$ Awaiting Review $\to$ Closed.
    • Technician assignment with skill tags (e.g. SEP up to 1kV electrical certification).
    • Hardware serial number scanning and repair photo attachments.

State Management Architecture

The Energy Cooperative module relies on specialized providers:

lib/features/energy_coop/providers/
├── energy_coop_provider.dart      # Cooperative metadata, members, and license info
├── telemetry_provider.dart        # Real-time WebSocket subscriptions to IoT telemetry
├── device_control_provider.dart   # Inverter power controls & parameter updates
├── financial_provider.dart        # Wallet transactions and ledger balance
├── governance_provider.dart       # Resolutions, ballots, and quorum verification
├── work_order_provider.dart       # Field technician task lifecycle
└── knowledge_base_provider.dart   # Article hierarchy, search, and document attachments

Diagnostic Checklist for Support Staff

  1. Missing Dashboard Data:
    • Verify if the active tenant has configured valid PPE numbers (Punkt Poboru Energii) in CoopSettingsScreen.
    • Check if the latest telemetry cron job (ingest-telemetry or aggregate-hourly) succeeded in the Supabase logs.
  2. Device Shows Offline:
    • Check the device’s heartbeat timestamp in MyDevicesScreen. If older than 15 minutes, instruct the user to verify local Wi-Fi / Modbus gateway connectivity.
  3. Voting Button Inactive:
    • Check RbacContextProvider.can('governance', 'vote'). Ensure the user’s KYC declaration was marked as approved in TeamDeclarationsScreen.