# askjohngeorge/ai-dialer architecture

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

- Interactive diagram: https://gitdiagram.com/askjohngeorge/ai-dialer
- Repository: https://github.com/askjohngeorge/ai-dialer

## Overview

##### Project Type & Purpose
- This is a full-stack, proof-of-concept application focused on automating outbound calls with an AI agent. It manages leads and schedules appointments using voice synthesis (VAPI.ai), appointment scheduling (Cal.com), and email communications (Resend).
- The README and file tree indicate it’s built with Next.js (using the App Router), integrates with Supabase for the database/authentication, and has dedicated directories for voice assistant configurations (vapi) and detailed API endpoints (src/app/api).

##### Analyzing the File Structure
- Top-level Directories: Notice directories such as “src”, “supabase”, “vapi”, and “docs”. This segmentation shows a separation between frontend (Next.js app in “src”), backend/API endpoints (in “src/app/api”), database management (SQL init script and test data in “supabase”), and voice assistant tools/configuration in “vapi”.
- Within “src”, there are directories for:
- App pages and routes that handle core functionalities (e.g., leads, cron, login, settings)
- Components (organized in their own directory, including UI components and layout variations)
- Hooks, libraries (services for calls, emails, settings, Supabase integrations), and middleware.
- The “vapi” directory holds prompt templates, configuration files, and tools that manage and deploy the voice assistant specifics.
- Important configuration files exist (e.g., next.config.ts, tailwind.config.ts, tsconfig.json) that confirm the technology stack and environment settings.

##### Insights from the README
- The README outlines the core features of AI-driven outbound calling, a lead management dashboard, automated scheduling, and email follow-ups. It explicitly mentions integration points: VAPI.ai, Cal.com, Resend, and Supabase.
- It provides a clear mapping of the directories by summarizing the project structure, such as where the “src” application code lives, documentation in “docs”, and voice-related code in “vapi”.

a. Main Components:
- Frontend: Next.js application (located in src/app and src/components) that delivers pages, manages routing, and provides the dashboard.
- Backend API: Next.js API Routes (in src/app/api) that handle business logic such as cron jobs, lead operations, and integrations.
- Database: Supabase Postgres instance (with initialization scripts and RLS policies in the “supabase” directory).
- External Services:
- VAPI.ai: Handles voice synthesis and processes the autonomous voice agent’s prompts.
- Cal.com: Manages appointment scheduling.
- Resend: Sends out email communications.
b. Relationships and Interactions:
- The Frontend communicates with the API endpoints through Next.js routing. It renders the UI components and dispatches API calls (using hooks in src/hooks).
- API routes interact with the business logic layer (located in src/lib/services) to perform actions like creating/updating leads or scheduling calls.
- The business layer communicates with the Supabase database for data storage and authentication.
- The system pushes automation and cron tasks through dedicated endpoints (e.g., src/app/api/cron).
- Integration with external services: The backend triggers VAPI.ai for voice synthesis, Cal.com for scheduling, and Resend for email follow-ups, based on business logic.
c. Architectural Patterns & Design Principles:
- Adopt separation of concerns by clearly delineating the UI (components, pages) from the API (service endpoints) and database layers.
- Utilize an integration layer (src/lib/services) to encapsulate interactions with external services.
- The design is modular: voice assistant configurations are in a separate “vapi” module, and database-related functionality is contained in “supabase”.
d. Technologies, Frameworks, and Libraries:
- Frontend: Next.js 15.x, shadcn/ui, Tailwind CSS, React components.
- Backend: Next.js API Routes, middleware for authentication, and cron tasks.
- Database: Supabase (Postgres with RLS).
- Third-party services: VAPI.ai, Cal.com, Resend.

- Database (Supabase) as the persistent storage layer that the business logic interacts with.
- Additional notes, such as “Cron jobs,” which may be triggered separately and interact with the same backend logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        FE1["Next.js Pages"]:::frontend
        FE2["UI Components"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        API["API Endpoints (Cron,Leads,Integrations)"]:::backend
        VAPI_API["VAPI.ai API"]:::backend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        SVCS["Business Services"]:::service
        SUP_CLIENT["Supabase Client"]:::service
    end

    %% Database Layer
    DB["Supabase Database"]:::db

    %% External Services
    EXT_CAL["Cal.com Scheduling"]:::external
    EXT_RESEND["Resend Email"]:::external

    %% Voice Assistant Module
    VA["Voice Assistant Module"]:::voice

    %% Connections
    FE1 -->|"calls"| API
    FE2 -->|"renders"| API
    API -->|"processes"| SVCS
    API -->|"triggers"| VAPI_API
    SVCS -->|"queries"| SUP_CLIENT
    SUP_CLIENT -->|"accesses"| DB
    SVCS -->|"integrates"| EXT_CAL
    SVCS -->|"integrates"| EXT_RESEND
    VAPI_API -->|"usesConfig"| VA

    %% Click Events
    click FE1 "https://github.com/askjohngeorge/ai-dialer/tree/main/src/app"
    click FE2 "https://github.com/askjohngeorge/ai-dialer/tree/main/src/components"
    click API "https://github.com/askjohngeorge/ai-dialer/tree/main/src/app/api"
    click VAPI_API "https://github.com/askjohngeorge/ai-dialer/tree/main/src/app/api/integrations/vapi"
    click SVCS "https://github.com/askjohngeorge/ai-dialer/tree/main/src/lib/services"
    click SUP_CLIENT "https://github.com/askjohngeorge/ai-dialer/tree/main/src/lib/supabase"
    click DB "https://github.com/askjohngeorge/ai-dialer/tree/main/supabase"
    click VA "https://github.com/askjohngeorge/ai-dialer/tree/main/vapi"

    %% Styles
    classDef frontend fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef backend fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef service fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef db fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef external fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef voice fill:#d9ccff,stroke:#333,stroke-width:2px;
```
