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 (Planned)

Not yet deployed. Target: Vercel for Next.js, Supabase cloud for data.

See Infrastructure for deployment planning.

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