# bigc7292/eva_eva architecture

> Architecture diagram of the GitHub repository bigc7292/eva_eva, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bigc7292/eva_eva
- Repository: https://github.com/bigc7292/eva_eva

## Overview

##### Project Type and Purpose
- This is a full-stack AI calling solution for real estate, built as a monorepo using Next.js (frontend) and a Node.js service (backend) with Supabase as the primary data store, VAPI for AI-powered voice interactions, and Twilio for telephony.

##### Main Components
a. Frontend (apps/frontend)
- Next.js 13 App Router serves UI pages (calls dashboard, analytics, scheduling, etc.)
- Next.js API routes handle:
– Call initiation & status endpoints
– Webhook endpoints for VAPI and Twilio events
– Analytics & metrics endpoints
- Supabase client for data CRUD
- Static assets & recordings (public/)
b. Backend Service (apps/backend)
- Node.js/Express (server.js) for batch scripts and advanced call handling
- Scripts folder for database setup, call simulation, webhook registration, testing
c. Database (Supabase)
- Hosted Postgres; schema under db/ and supabase/migrations/
- Tables for calls, leads, analytics views, meeting metrics
d. AI Voice Platform (VAPI)
- External REST API for AI-driven call conversations
- Webhook events posted to Next.js API
e. Telephony Provider (Twilio)
- Calls, SIP trunk logs, SMS
- Webhook events for call status delivered to Next.js API
f. “AI Mega-Brain” Knowledge Store
- Logical component representing combined data lake:
– Raw call audio
– Transcripts & AI insights
– Lead & audience profiles
– Content ideas & campaign metadata
– Historical analytics

##### Relationships & Data Flows
1. User interacts with Next.js UI → triggers REST/gRPC call to Next.js API
2. Next.js API → writes/reads Supabase (call records, user settings)
3. Next.js API → calls VAPI endpoints to initiate AI call
4. VAPI → rings Twilio phone number, Twilio → outbound call to lead
5. Twilio call events → webhook → Next.js API → updates Supabase
6. VAPI conversation events → webhook → Next.js API → persists transcript & metadata
7. Analytics module (UI) → queries Supabase views/functions
8. Backend service (optional) → runs batch scripts against Supabase or triggers calls via VAPI/Twilio for bulk operations

##### Architectural Patterns & Principles
- Monorepo (turbo.json) separates apps/ and shared packages/ui, config, tsconfig
- Frontend follows modular App Router & API-first pattern
- Backend service as thin microservice for heavy scripts
- Database‐as‐a‐service (Supabase) with SQL migrations & seed scripts
- Event-driven webhooks for real-time updates
- Clear separation of concerns: UI, API, data, external integrations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        UI["Next.js UI\n(apps/frontend)"]:::frontend
        SupClient["Supabase Client\n(supabase.ts)"]:::frontend
        VapiFE["VAPI Client\n(vapi.ts)"]:::frontend
        TwilioFE["Twilio Client\n(twilio.js)"]:::frontend
        Static["Static Assets & Recordings\n(public/)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIRoutes["Next.js API Routes\n(apps/frontend/src/app/api)"]:::api
    end

    %% Services Layer
    subgraph "Services Layer"
        direction TB
        BServer["Backend Service\n(server.js)"]:::backend
        Scripts["Batch Scripts\n(apps/backend/scripts)"]:::backend
        VapiService["VAPI Service\n(vapi.service.js)"]:::backend
        VapiClientBE["VAPI REST Client\n(vapi.js)"]:::backend
        TwilioService["Twilio Service\n(twilio.service.js)"]:::backend
        TwilioClientBE["Twilio Client\n(twilio.js)"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Supabase["Supabase (Postgres)"]:::data
        Migrations["Schema & Migrations\n(db/schema.sql\nsupabase/migrations\nsupabase/schema.sql)"]:::data
    end

    %% Knowledge Store
    Knowledge["AI Mega-Brain\nKnowledge Store"]:::brain

    %% External Services
    subgraph "External Services"
        direction TB
        VAPI["AI Voice Platform\n(VAPI)"]:::external
        TwilioExt["Telephony Provider\n(Twilio)"]:::external
    end

    %% Connections
    UI --> APIRoutes
    APIRoutes --> Supabase
    APIRoutes --> VapiService
    APIRoutes --> TwilioService

    VapiService --> VAPI
    VAPI --> TwilioExt
    TwilioExt --> APIRoutes
    VAPI --> APIRoutes

    BServer --> Supabase
    Scripts --> Supabase
    Scripts --> VapiService
    Scripts --> TwilioService

    Supabase --> Knowledge
    Migrations --> Supabase

    %% Analytics flow
    UI -->|"query metrics"| Supabase

    %% Click Events
    click UI "https://github.com/bigc7292/eva_eva/tree/main/apps/frontend"
    click SupClient "https://github.com/bigc7292/eva_eva/blob/main/apps/frontend/src/lib/services/supabase.ts"
    click VapiFE "https://github.com/bigc7292/eva_eva/blob/main/apps/frontend/src/lib/services/vapi.ts"
    click TwilioFE "https://github.com/bigc7292/eva_eva/blob/main/apps/frontend/src/twilio/twilio.js"
    click Static "https://github.com/bigc7292/eva_eva/tree/main/apps/frontend/public"
    click APIRoutes "https://github.com/bigc7292/eva_eva/tree/main/apps/frontend/src/app/api"
    click BServer "https://github.com/bigc7292/eva_eva/blob/main/apps/backend/server.js"
    click Scripts "https://github.com/bigc7292/eva_eva/tree/main/apps/backend/scripts"
    click VapiService "https://github.com/bigc7292/eva_eva/blob/main/apps/backend/src/services/vapi/vapi.service.js"
    click VapiClientBE "https://github.com/bigc7292/eva_eva/blob/main/apps/backend/src/services/vapi/vapi.js"
    click TwilioService "https://github.com/bigc7292/eva_eva/blob/main/apps/backend/src/services/twilio/twilio.service.js"
    click TwilioClientBE "https://github.com/bigc7292/eva_eva/blob/main/apps/backend/src/services/twilio/twilio.js"
    click Migrations "https://github.com/bigc7292/eva_eva/blob/main/db/schema.sql"
    click Migrations "https://github.com/bigc7292/eva_eva/tree/main/supabase/migrations"
    click Migrations "https://github.com/bigc7292/eva_eva/blob/main/supabase/schema.sql"
    click Knowledge "https://github.com/bigc7292/eva_eva/blob/main/supabase/schema.sql"
    click Knowledge "https://github.com/bigc7292/eva_eva/blob/main/db/schema.sql"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef backend fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef data fill:#98FB98,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef brain fill:#FFD700,stroke:#333,stroke-width:1px
```
