System Overview & Architecture

The Planovi Backend is an enterprise serverless micro-function architecture built on Deno and TypeScript, executing as Supabase Edge Functions. The system powers real-time IoT energy telemetry ingestion, AI-driven energy balancing and voice processing, automated invoicing, legal energy declaration workflows, and cooperative governance.

---

High-Level Architecture Blueprint

flowchart TB
    subgraph Clients["Client Layer"]
        FlutterApp["Planovi Flutter App (Mobile / Web)"]
        IoTHardware["IoT Converters & Smart Meters"]
        ExternalDS["External DSOs (Tauron / Enea)"]
    end

    subgraph EdgeGateway["Planovi Backend (Supabase Edge Functions - Deno)"]
        direction TB
        AuthFilter["CORS & JWT Auth Filter"]
        
        subgraph DomainModules["35 Production Micro-Functions"]
            IoTModule["⚡ Telemetry & Ingest Engine"]
            AIModule["🤖 Jarvis & AI Balancer Engine"]
            BillingModule["💰 Billing & Invoicing Engine"]
            DeclModule["📜 Declarations & Legal Engine"]
            MemberModule["👥 Member Onboarding Engine"]
            CronModule["⏱️ Scheduler & Aggregators"]
        end
        
        AuthFilter --> DomainModules
    end

    subgraph Infrastructure["Infrastructure & Storage Layer"]
        SupabaseDB[(PostgreSQL Database + PostGIS)]
        SupabaseStorage[("Supabase Storage (PDFs, DOCX, OCR)")]
        DenoKV[("Deno KV Store (Token & Telemetry Cache)")]
        GeminiAI["Google Gemini Vision / Multimodal AI"]
    end

    Clients -->|"HTTPS REST / JSON"| AuthFilter
    DomainModules -->|"pg / PostgREST"| SupabaseDB
    DomainModules -->|S3 REST| SupabaseStorage
    DomainModules -->|Fast Key-Value| DenoKV
    AIModule -->|REST API| GeminiAI

---

Runtime Environment & Hosting Topology

Deno Serverless Engine

All functions are authored in TypeScript and executed on the Deno runtime:

• Zero Cold Starts: Lightweight isolates spin up in sub-millisecond windows.
• Standards Compliant: Direct adherence to standard Web APIs (fetch, Request, Response, ReadableStream, Crypto).
• Secure by Default: Explicit environment variable access (Deno.env.get(...)) and scoped permissions.
• Edge KV Caching: Integrated Deno.openKv() utilized for sub-millisecond bearer token caching and session persistence.

Production Hosting: Planovi VPS (191.218.165.149)

The production instance runs on a dedicated, hardened Linux VPS environment:

• Host IP: 191.218.165.149
• Automated Webhook Deployment: Commits pushed to the repository trigger a secure GitHub Webhook listener on the VPS that tests, compiles, and deploys modified Edge Functions directly into the live Supabase stack.
• Reverse Proxy & TLS: Nginx / Kong reverse-proxy terminating SSL certificates and forwarding traffic to the local Supabase Edge Runtime (localhost:54321).

---

The 6 Subsystem Domains (35 Functions)

Subsystem Domain	Functions Included	Core Responsibility
⚡ Telemetry & IoT	ingest-telemetry refresh-live-state cleanup-telemetry process-tauron-csv process-alerts	High-frequency telemetry polling, InCharge API token caching, live state broadcasting, and alert triggers.
🤖 AI & Energy Balancing	jarvis ai-energy-balancer process-declaration-ocr fetch-energy-news	Conversational voice assistant, automated battery/grid balancing algorithms, and Gemini OCR extraction.
💰 Billing & Invoicing	billing-calculator generate-invoice-pdf generate-monthly-invoices export-csv generate-report	Tariff computation, monthly cooperative settlement, dynamic PDF invoice generation, and CSV exports.
📜 Declarations & Legal	get-company-declaration-schema approve-declaration-schema get-member-declaration submit-member-declaration update-member-declaration review-member-declaration upload-declaration generate-resolution-document generate-prefilled-docx docx-to-html	End-to-end statutory energy cooperative declaration lifecycle, schema validation, and DOCX/HTML generation.
👥 Member Onboarding	grant-portal-access member-onboarding-status send-onboarding-invitation send-correction-request-notice send-rejection-notice	Multi-step cooperative member onboarding, verification, and email notification dispatchers.
⏱️ Scheduler & Crons	run-scheduler reminder-scheduler tender-cron aggregate-hourly aggregate-daily main	Background automation, appointment reminders, energy auction monitoring, and timeseries data rollups.

---

Request Lifecycle

sequenceDiagram
    autonumber
    actor Client as Flutter App / Hardware
    participant Edge as Edge Function Isolate
    participant KV as Deno KV Cache
    participant DB as PostgreSQL
    participant Ext as "External Service (AI / InCharge)"

    Client->>Edge: POST /functions/v1/{function-name} (Bearer JWT)
    Edge->>Edge: Validate CORS & Verify JWT Header
    alt Token Cached in Deno KV
        Edge->>KV: kv.get(["incharge", "token"])
        KV-->>Edge: Cached Bearer Token
    else Token Expired or Missing
        Edge->>Ext: Re-authenticate with upstream provider
        Ext-->>Edge: New Token & TTL
        Edge->>KV: kv.set(["incharge", "token"], token, { expireIn })
    end
    Edge->>DB: Execute Query / Mutation (Service Role or User RLS)
    DB-->>Edge: Record Result Set
    Edge-->>Client: 200 OK + JSON Payload