System Architecture Overview

The Planovi Webpage (planovi-webpage) is the public web gateway and marketing platform for the Planovi Smart Energy Cooperative ecosystem. It serves prospective energy cooperative boards, property managers, developers, and current members by providing marketing showcases, real-time system status metrics, legal document access, and lead intake automation.

---

1. High-Level Architectural Topology

flowchart TD
    subgraph Clients ["Public Clients & Web Browsers"]
        Desktop["💻 Desktop Browser (Chrome, Safari, Firefox)"]
        Mobile["📱 Mobile Device / Tablet"]
    end

    subgraph EdgeDNS ["Edge Routing & Security"]
        CF["🌐 Cloudflare CDN & DNS (*.planovi.app)"]
        Turnstile["🛡️ Cloudflare Turnstile Bot Defense"]
    end

    subgraph HostingerVPS ["Hostinger VPS (191.218.165.149)"]
        Nginx["🛡️ Nginx Reverse Proxy (:80 / :443)"]
        PHPRuntime["⚡ PHP 8.3 Application Runtime (/opt/vps-apps/webpage)"]
        Deployer["🚀 vps-deployer (Python Webhook on :9000)"]
    end

    subgraph CloudServices ["External Cloud Services & APIs"]
        Supabase["⚡ Supabase REST API (PostgreSQL DB)"]
        GChat["💬 Google Chat Webhook (Lead Alert Space)"]
        Calendar["📅 Google Calendar (Demo Scheduling)"]
    end

    Desktop --> CF
    Mobile --> CF
    CF --> Turnstile
    CF -->|SSL Full Strict| Nginx
    Nginx --> PHPRuntime
    Deployer -->|"Git Pull / Sync"| PHPRuntime

    PHPRuntime -->|Contact Form Submission| Supabase
    PHPRuntime -->|Real-time Module Status| Supabase
    PHPRuntime -->|Lead Notifications| GChat
    PHPRuntime -.->|Book Demo CTA| Calendar

---

2. Technology Stack

Layer	Technology	Version / Specification	Role
Runtime	PHP	8.3 FPM	Server-side rendering, routing, i18n, and form handling
Web Server	Nginx	Alpine Docker	Reverse proxy, static asset caching, SSL termination
Frontend Core	HTML5 / Vanilla JS	ES6+ Modules	Interactive client logic, canvas physics, DOM manipulation
Design System	Vanilla CSS	CSS3 Variables	Glassmorphic design, dark/light theme switching, responsive layouts
Bot Protection	Cloudflare Turnstile	v0 API	Invisible/interactive challenge verification
Database Integration	Supabase REST API	PostgREST / PostgreSQL	Asynchronous message persistence and system health queries
Alerting	Google Chat Webhook	Google Workspace API	Instant notification dispatch for new business inquiries
Documentation	Astro + Starlight	Astro 4.16, Starlight 0.28	Docs-as-Code technical reference and API documentation

---

3. Request Lifecycle & Routing

The webpage uses clean PHP request routing orchestrated through modular scripts:

1. Static & Initial Page Load (index.php):
   • Initializes config.php (global site links, API keys, endpoints).
   • Loads i18n.php to detect query parameter ?lang=pl or ?lang=en (or user session / browser header).
   • Injects localized translations from lang/{lang}.json.
   • Renders structural components: skip links, interactive <canvas id="bg-canvas">, components/navbar.php, section blocks (Hero, Features, How It Works, Pricing, FAQ, Blog, Contact), and components/footer.php.
2. Contact Form Intake (contact-handler.php):
   • Receives JSON payload or POST form values.
   • Validates required inputs (name, email, message) and email syntax.
   • Verifies Cloudflare Turnstile challenge token (cf-turnstile-response) against Cloudflare API.
   • Writes message record directly to Supabase table website_form_messages via HTTP REST.
   • Dispatches formatted alert card to Google Chat webhook.
   • Responds with JSON { success: true, message: ... }.
3. Live Status Dashboard (status.php):
   • Queries Supabase REST endpoint /rest/v1/app_modules?select=*,app_modules_maintenance(*).
   • Parses active health states and planned maintenance windows for all Planovi modules (Dashboard, AI Agent, Modbus Gateway, Edge Functions).
   • Falls back gracefully to cached mock values if database connectivity is unavailable.
4. Legal Document Center (documentation.php / docs.php):
   • Scans directory documents/{lang}/ for verified legal PDF files (privacy_policy.pdf, terms_and_conditions.pdf).
   • Renders interactive dropdown selector with embedded iframe viewer (#toolbar=0).

---

4. Hosting & Infrastructure Topology

The application is deployed to the central Planovi Hostinger VPS (191.218.165.149):

• Production Directory: /opt/vps-apps/webpage/prod
• Development Directory: /opt/vps-apps/webpage/dev
• Reverse Proxy: Containerized vps-proxy (Nginx) terminating Cloudflare 15-year origin wildcard SSL (*.planovi.app).
• CI/CD Automation: vps-deployer webhook runner automatically updates working trees upon GitHub push to main or dev branches.