System Overview & Architecture

The Planovi Microservices repository (planovi-microservices) hosts the lightweight, high-performance PHP 8.3 microservices that power customer intake, interactive energy offer presentation, member accession onboarding, and appointment booking for the Planovi energy cooperative platform.

---

1. High-Level Topology

The microservices operate as dedicated web services behind Nginx reverse proxies, interacting with the Planovi Flutter App (client application), Planovi Backend (Supabase Edge Functions in Deno), and external third-party providers (Google Calendar API and Supabase Database).

flowchart TB
    subgraph Clients["Clients & Frontends"]
        Mobile["Planovi Flutter Mobile App"]
        WebPortal["Planovi Web Portal"]
        PublicUser["External Clients & Prospects"]
    end

    subgraph Ingress["Nginx Gateway & Subdomains (Planovi VPS)"]
        DealflowDomain["dealflow.planovi.app
dev-dealflow.planovi.app"]
        SchedulerDomain["scheduler.planovi.app
dev-scheduler.planovi.app"]
        OffersDomain["offers.planovi.app
dev-offers.planovi.app"]
        AgreementsDomain["agreements.planovi.app
dev-agreements.planovi.app"]
    end

    subgraph Microservices["PHP 8.3 FPM Microservices Engine"]
        Config["config.php (Environment Resolver)"]
        Dealflow["dealflow/
• inquiry.php
• offer.php
• api/create_offer.php
• api/save_dealflow.php"]
        Scheduler["scheduler/
• index.php
• assets/script_v2.js
• backend/api.php
• backend/auth_*.php"]
        JSONStore[("data/*.json Storage Engine")]
    end

    subgraph External["External Integrations & Cloud Services"]
        SupabaseEdge["Planovi Backend
(Supabase Edge Functions)"]
        SupabaseDB[("Supabase PostgreSQL DB")]
        GoogleCal["Google Calendar API v3
(OAuth 2.0 / Refresh Tokens)"]
    end

    Clients --> Ingress
    DealflowDomain --> Dealflow
    SchedulerDomain --> Scheduler
    OffersDomain -.-> Microservices
    AgreementsDomain -.-> Microservices

    Dealflow --> Config
    Scheduler --> Config

    Dealflow --- JSONStore
    Scheduler --- JSONStore

    Dealflow -->|"Token Mode: submit-member-declaration"| SupabaseEdge
    Scheduler -->|"Appointment Sync"| SupabaseDB
    Scheduler -->|"Slot Checking & Event Booking"| GoogleCal

---

2. Microservice Domains & Subdomain Routing

Each microservice maps directly to an isolated subdomain configured in Nginx and DNS:

Microservice	Staging Subdomain	Production Subdomain	Primary Responsibility
Dealflow	dev-dealflow.planovi.app	dealflow.planovi.app	Intake inquiries, offer viewer (?id=XXX), member onboarding tokens (?token=XXX), API deal creation.
Scheduler	dev-scheduler.planovi.app	scheduler.planovi.app	Embeddable booking calendar, dynamic branding, Google Calendar two-way synchronization, slot validation.
Offers	dev-offers.planovi.app	offers.planovi.app	Specialized dynamic energy quotation and PV/battery calculation engine.
Agreements	dev-agreements.planovi.app	agreements.planovi.app	Contract execution, legal agreement generation, and statutory member resolution workflows.

---

3. Centralized Environment Resolution (config.php)

All microservices inherit runtime configuration and environment awareness from the repository root config.php. The configuration automatically detects whether execution occurs locally, in staging (dev-*), or in production:

// config.php Host & Environment Inspection
$currentHost = $_SERVER['HTTP_HOST'] ?? 'localhost';

if (strpos($currentHost, 'localhost') !== false || strpos($currentHost, '127.0.0.1') !== false) {
    define('ENVIRONMENT', 'local');
    define('BASE_URL', 'http://localhost/planovi');
    define('SCHEDULER_URL', 'http://localhost/planovi/scheduler');
    define('DEALFLOW_URL', 'http://localhost/planovi/dealflow');
} elseif (strpos($currentHost, 'dev-') !== false) {
    define('ENVIRONMENT', 'staging');
    define('BASE_URL', 'https://dev-webpage.planovi.app');
    define('SCHEDULER_URL', 'https://dev-scheduler.planovi.app');
    define('DEALFLOW_URL', 'https://dev-dealflow.planovi.app');
} else {
    define('ENVIRONMENT', 'production');
    define('BASE_URL', 'https://planovi.app');
    define('SCHEDULER_URL', 'https://scheduler.planovi.app');
    define('DEALFLOW_URL', 'https://dealflow.planovi.app');
}

define('IS_LOCAL', ENVIRONMENT === 'local');
define('IS_STAGING', ENVIRONMENT === 'staging');
define('IS_PRODUCTION', ENVIRONMENT === 'production');

Error Reporting by Environment

• Production (IS_PRODUCTION = true): Error reporting is disabled (error_reporting(0); ini_set('display_errors', 0);) to prevent sensitive internal stack traces from leaking to public users.
• Local & Staging (IS_LOCAL / IS_STAGING = true): Verbose errors enabled (error_reporting(E_ALL); ini_set('display_errors', 1);) for rapid developer diagnosis and debugging.

---

4. Production Host & VPS Deployment

The microservices run on the Planovi Linux VPS:

• Server IP: 191.218.165.149
• Web Server: Nginx with HTTP/2 and Let’s Encrypt TLS termination.
• PHP Process Manager: PHP 8.3 FPM socket (/var/run/php/php8.3-fpm.sock).
• File System Permissions: Subdirectories dealflow/data/ and scheduler/data/ require read/write permissions (chmod 0755 or 0775) for the www-data user to write dynamic state JSON records.