Skip to content
PLANOVI Docs

System & Core Architecture

PLANOVI System Architecture

PLANOVI is an enterprise cross-platform management platform tailored for Energy Cooperatives (Kooperatywy Energetyczne) and distributed business operations. The system bridges mobile/web clients with real-time IoT energy telemetry, democratic governance voting, calendar scheduling, contract authoring, and an AI voice assistant (Jarvis).

High-Level Architecture Diagram

graph TB
    subgraph ClientLayer ["Client Application (Flutter 3.x / Dart)"]
        UI["UI Screens & Widgets"]
        Providers[Provider State Management]
        Tenancy["TenantSession & Workspace Context"]
        RBAC[RbacContextProvider]
        
        UI --> Providers
        Providers --> Tenancy
        Providers --> RBAC
    end

    subgraph EdgeLayer ["Supabase Cloud & Edge Services"]
        EdgeAuth["Supabase Auth & JWT"]
        Postgres[(PostgreSQL + RLS)]
        Realtime[Supabase Realtime WebSockets]
        Storage[Supabase Storage Buckets]
        Functions[30+ Deno TypeScript Edge Functions]
    end

    subgraph ExternalServices ["External & Third-Party Integrations"]
        JarvisAI["OpenAI / LLM Voice Processing"]
        Tauron[Tauron Energy Grid Telemetry CSV]
        GoogleCalendar[Google Calendar API]
        CF_Pages[Cloudflare Pages Docs Engine]
    end

    UI -->|HTTPS REST & Auth| EdgeAuth
    UI -->|"Direct SQL / PostgREST"| Postgres
    UI -->|WebSocket Subscriptions| Realtime
    UI -->|Binary Document Uploads| Storage
    UI -->|Function Invocations| Functions

    Functions -->|AI Inference| JarvisAI
    Functions -->|Energy Telemetry Sync| Tauron
    Functions -->|Calendar Sync| GoogleCalendar
    CF_Pages -.->|Internal Documentation| UI

Technology Stack Breakdown

Frontend Core

  • Framework: Flutter 3.24+ / Dart 3.x
  • State Management: provider (version ^6.1.2), leveraging ChangeNotifier, ChangeNotifierProxyProvider, and Consumer patterns.
  • Navigation & Localization: get (GetMaterialApp) for route helpers and centralized two-language dynamic localization (pl_PL and en_US).
  • Charts & Telemetry Visualization: fl_chart for energy production, battery states, and grid load curves.
  • Document Engine: flutter_quill for rich-text document editing, custom PDF engines (pdf, printing), and conditional multi-platform DOCX viewers.
  • Voice & Audio Pipeline: record for microphone capture, flutter_tts for speech synthesis, and audioplayers for alert effects.

Backend Infrastructure (Supabase)

  • Authentication: Email/Password and OAuth sessions, token refresh handling, and claim-based session storage.
  • Database & RLS: PostgreSQL engine with strict Row-Level Security (RLS) enforcing tenant isolation (company_id).
  • Realtime Subscriptions: Postgres Changes broadcast via WebSockets to automatically update the Energy Dashboard, Work Order queue, and chat screens.
  • Edge Functions: Over 30 specialized TypeScript functions running on Deno, handling heavy operations such as telemetry aggregation, Tauron CSV ingestion, AI voice response generation, OCR, and billing calculations.

Directory Organization

The Flutter client adheres to a modular domain-driven feature layout:

lib/
├── core/                        # Shared cross-cutting concerns
│   ├── api/                     # Base HTTP clients and network interceptors
│   ├── config/                  # App environment constants & configurations
│   ├── constants/               # Global strings, assets, localization dictionary
│   ├── layout/                  # Main layout shell, side panel, responsive scaffolds
│   ├── providers/               # Global singletons (Auth, Theme, Maintenance)
│   ├── services/                # Device/External integrations (Secure Storage, TTS)
│   ├── theme/                   # Design system tokens (AppColors, AppTheme)
│   ├── utils/                   # Platform view registries, formatting utilities
│   └── widgets/                 # Reusable UI widgets, badges, maintenance overlays
│
└── features/                    # Independent domain modules
    ├── admin/                   # Access control, role management, invitation flows
    ├── auth/                    # Login, registration, password recovery screens
    ├── clients/                 # CRM customer directory and profile cards
    ├── companies/               # Workspace switcher and tenant setup
    ├── dashboard/               # Generic business executive dashboard
    ├── dealflow/                # Sales pipeline Kanban and deal management
    ├── documents/               # Document reader, rich-text editor, file manager
    ├── energy_coop/             # Full energy cooperative suite (12+ screens)
    ├── jarvis/                  # AI Voice Assistant, reminders, and chat
    ├── scheduler/               # Booking system, calendar, branding settings
    └── settings/                # User profile, language, and security preferences

Client-to-Backend Communication Flow

The app communicates with Supabase through three distinct layers:

  1. Direct PostgREST Queries: Standard CRUD operations on entities (e.g. clients, documents, calendars) use supabase.from('table').select(). RLS policies ensure records are filtered automatically by the authenticated user’s active tenant.
  2. WebSocket Channels: Realtime updates for fast-changing states (like technician assignments or real-time IoT power generation) use supabase.channel(...).
  3. Edge Functions (/functions/v1/*): Complex multi-step actions (such as generating an invoice PDF, processing Jarvis voice queries, or computing cooperative energy balance) are dispatched to serverless Edge Functions to keep the client lightweight.