System Design

Status: Accepted Owner: @bilal Last Updated: 2026-02-15

High-level architecture for Envo Energy.

System Context

C4Context
    title System Context Diagram
    Person(tenant, "Tenant", "Reports issues via chat, voice, or form")
    Person(landlord, "Landlord", "Manages properties and resolves issues")
    Person(vendor, "Vendor", "Accepts and completes maintenance jobs")
    System(envo, "Envo Platform", "Tenant support and property operations")
    System_Ext(twilio, "Twilio", "WhatsApp + SMS")
    System_Ext(sendgrid, "SendGrid", "Email")
    System_Ext(vapi, "VAPI", "Voice AI intake")
    Rel(tenant, envo, "Reports issues")
    Rel(landlord, envo, "Manages via dashboard")
    Rel(vendor, envo, "Accepts jobs via link")
    Rel(envo, twilio, "Sends SMS / WhatsApp")
    Rel(envo, sendgrid, "Sends email")
    Rel(vapi, envo, "Sends transcripts")

Container Architecture

graph TB
    subgraph NextApp["Next.js Monolith"]
        subgraph Frontend
            Dashboard[Landlord Dashboard<br/>React + Apollo + ShadCN]
            VendorPages[Vendor Pages]
        end
        subgraph API["API Layer"]
            GraphQL[GraphQL API<br/>Pothos + Yoga]
            RouteHandlers[Route Handlers<br/>Webhooks]
        end
        subgraph TenantEngine["Tenant Engine"]
            RAG[RAG Pipeline<br/>Multi-LLM + pgvector]
            MessageProcessor[Message Processor]
        end
        Prisma[Prisma ORM]
    end
    subgraph Data["Data Layer"]
        Supabase[(PostgreSQL + pgvector)]
        Storage[Supabase Storage]
        Auth[Supabase Auth]
    end
    Dashboard -->|Apollo Client| GraphQL
    GraphQL --> Prisma
    RouteHandlers --> Prisma
    Prisma --> Supabase
    TenantEngine --> Prisma

Key Architectural Decisions

Decision	Choice	Rationale
Framework	Next.js (App Router)	Full-stack, SSR, single deployment
ORM	Prisma	Type-safe, excellent DX
GraphQL	Pothos + Yoga + Apollo	Code-first, end-to-end type safety
Multi-tenancy	Single DB with RLS	Simpler ops, Supabase-native
Auth	Supabase Auth	Integrated with RLS
Vendor auth	Token-based	No accounts needed

Security Layers

1. Database (RLS) — Row-level security at PostgreSQL level
2. ORM (Prisma context) — Organisation scoping on all queries
3. GraphQL (Pothos) — Field-level permissions
4. Transport — HTTPS, CORS, rate limiting

Scalability

Layer	Concern	Mitigation
Database	Query performance	Indexes on FKs, status filters
API	N+1 queries	DataLoader via Pothos Prisma plugin
API	Request volume	Serverless auto-scaling
RAG	LLM latency	Multi-provider fallback

Deployment

Component	Target	URL
Dashboard	Cloudflare Workers (via @opennextjs/cloudflare)	app.ehq.tech
Documentation	Cloudflare Pages (Quartz)	brain.ehq.tech
Database	Supabase PostgreSQL	Hosted (cslpfplavhdkfprrmwno)
Infrastructure	Terraform Cloud + Cloudflare provider	Managed via GitHub Actions
Auth gate	Cloudflare Access (ZTNA, email OTP)	7-day sessions
Connection pool	Cloudflare Hyperdrive (caching disabled)	Pooling only

Interactive Diagrams

• System Architecture — Full runtime request flow from edge to database. Click components for details.
• CD Pipeline — GitHub Actions workflows, build steps, and deployment targets.
• Auth & Chat Architecture — Three auth models (landlord, tenant, vendor) and chat system architecture.
• Dashboard Features — Current dashboard capabilities and future roadmap (Now/Future tabs).
• RAG Pipeline — AI tenant support pipeline with current and ideal state views (Current/Ideal tabs).

See also: Data Model, Security, Tech Stack, RAG Pipeline