# mesieou/simple_booking architecture

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

- Interactive diagram: https://gitdiagram.com/mesieou/simple_booking
- Repository: https://github.com/mesieou/simple_booking

## Overview

##### Project type and purpose
- This is a full-stack, server-rendered web application built with Next.js (app directory) that doubles as an AI-powered WhatsApp agent (“Skedy”).
- Core use cases:
- Customers interact via WhatsApp (Twilio webhook) or website UI for quoting, booking, calendar management.
- Backend uses Supabase (Postgres) for data, OpenAI GPT for chat and content analysis, Google Maps APIs for distance/geo, custom web/PDF content crawler for training data.

##### File structure
- Frontend (user-facing UI):
- app/(auth-pages), app/[providerId]/… and app/page.tsx (Next.js Server/Client components)
- components/, components/ui/** (reusable UI primitives)
- Backend API (Next.js Route Handlers):
- app/api/* folders (chat, content-crawler, maps, provider, seed, webhook, etc.)
- middleware.ts for auth/SSR
- Business logic and services (lib/):
- lib/chatbot-handlers (chat orchestration, task processors)
- lib/llm-actions (OpenAI config & function calls)
- lib/backend-actions/content-crawler (URL/PDF crawler + embedding pipeline)
- lib/database (Supabase client, migrations, models, seed scripts)
- lib/general-helpers (distance, cost calculators)
- Scripts:
- scripts/* for seeding, testing, uploading PDFs
- Config files:
- next.config.ts, tailwind.config.ts, jest.config.js, tsconfig.json

##### README for additional insights
- Emphasizes real-time quoting, booking, calendar management via AI/WhatsApp
- Mentions customizable, scalable deployment (likely Vercel + Supabase + OpenAI)

a. Main components
1. Client layer
- Web Browser (Next.js Frontend pages & components)
- WhatsApp Client (via Twilio)
2. API Layer (Next.js Route Handlers)
- /api/chat → Chat orchestration
- /api/webhook → WhatsApp webhook entry
- /api/maps → Google Maps wrapper
- /api/content-crawler → Trigger crawler jobs
3. Business Logic
- Chatbot Processor (lib/chatbot-handlers)
- LLM Functions (lib/llm-actions)
- Booking & Availability Services (lib/general-helpers + DB models)
- Content Crawler & Embedding Pipeline (lib/backend-actions)
4. Data Layer
- Supabase PostgreSQL (tables: users, providers, availability_slots, bookings, quotes, embeddings, crawl_sessions)
- Object Storage (PDFs, crawler artifacts)
5. External Services
- OpenAI API (Chat, Embeddings)
- Google Maps API (Geocode, Distance Matrix, Autocomplete)
- Twilio WhatsApp API
6. Background / CI-CD
- Vercel Serverless Functions (hosting API + frontend)
- Scheduler / Cron (to run content-crawler jobs)
b. Relationships & interactions
- User → (WhatsApp) Twilio → Next.js /api/webhook → Chatbot Processor → OpenAI → Response back via Twilio
- User → (Browser) Next.js Frontend → Next.js API (maps, provider info, booking) → Supabase
- Chatbot Processor or Web UI triggers Database reads/writes (bookings, availability, quotes)
- Admin or Seeder Scripts → run /api/seed or scripts/seed.ts → populate Supabase
- Crawler jobs fetch URLs/PDFs → process content → generate embeddings via OpenAI → store in Supabase
c. Architectural patterns & design principles
- Separation of concerns: UI / API / business logic / data layer in distinct folders
- Serverless microservices: Next.js route handlers act as independent functions
- Modular “lib/” code: reusable helpers, LLM wrappers, crawler modules
- Event-driven design: webhooks and background crawler pipelines
- Use of third-party PaaS: Supabase for data, Vercel for hosting
d. Technologies & frameworks
- Next.js (React, Server Components, API routes)
- TypeScript
- Supabase (Postgres, Auth, Storage)
- OpenAI API
- Google Maps REST APIs
- Twilio WhatsApp
- Tailwind CSS

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        WebUI["Next.js Frontend<br/>(Web UI)"]:::frontend
        WhatsAppClient["WhatsApp Client<br/>(Twilio)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        WebhookAPI["/api/webhook<br/>(WhatsApp Webhook)"]:::api
        ChatAPI["/api/chat"]:::api
        ContentCrawlerAPI["/api/content-crawler"]:::api
        ContentCrawlerPDFAPI["/api/content-crawler/pdf"]:::api
        MapsAutocompleteAPI["/api/maps/autocomplete"]:::api
        MapsGeocodeAPI["/api/maps/geocode"]:::api
        MapsDistanceAPI["/api/maps/mapsdistance"]:::api
        ProviderInfoAPI["/api/provider/[id]"]:::api
        ProviderSlotsAPI["/api/provider/[id]/slots"]:::api
        SeedAPI["/api/seed"]:::api
        TestConnAPI["/api/test-connection"]:::api
        AuthCallbackAPI["/auth/callback"]:::api
    end

    %% Business Logic
    subgraph "Business Logic"
        direction TB
        ChatProcessor["Central Chatbot Processor"]:::business
        BookingHandler["Booking Handler"]:::business
        QuoteCalculator["Quote Calculator"]:::business
        FunctionCallHandler["Function Call Handler"]:::business
        WhatsAppLogger["WhatsApp Message Logger"]:::business
        OpenAICore["OpenAI Core Config"]:::business
        EmbeddingsFunc["Embeddings Function"]:::business
        VectorSearchFunc["Vector Search Function"]:::business
        AvailabilityHelper["Availability Helper"]:::business
        DistanceHelper["Distance Calculator"]:::business
        CostHelper["Quote Cost Calculator"]:::business
    end

    %% Background Crawler
    subgraph "Background / Crawler"
        direction TB
        HTMLCrawler["HTML Crawler"]:::business
        PDFCrawler["PDF Crawler"]:::business
        EmbeddingCreator["Embedding Creator"]:::business
        SchedulerScripts["Scheduler / Scripts"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        SupabaseDB["Supabase PostgreSQL"]:::data
        ObjectStorage["Object Storage<br/>(PDFs, Artifacts)"]:::data
        AvailSlotsModel["availability_slots Model"]:::data
        BookingModel["booking Model"]:::data
        QuoteModel["quote Model"]:::data
        Migration1["001_create_availability_slots.sql"]:::data
        Migration2["003_create_embeddings.sql"]:::data
        SeedBookingScript["create-bookings.ts"]:::data
        SeedQuoteScript["create-quotes.ts"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        GoogleMaps["Google Maps API"]:::external
        Twilio["Twilio WhatsApp API"]:::external
    end

    %% Connections
    WebUI -->|calls| ChatAPI
    WebUI -->|calls| ProviderInfoAPI
    WebUI -->|calls| ProviderSlotsAPI
    WebUI -->|calls| MapsAutocompleteAPI
    WebUI -->|calls| MapsGeocodeAPI
    WebUI -->|calls| MapsDistanceAPI
    WebUI -->|calls| SeedAPI
    WebUI -->|calls| TestConnAPI
    WhatsAppClient -->|Webhook| WebhookAPI

    WebhookAPI -->|triggers| ChatProcessor
    ChatAPI -->|triggers| ChatProcessor
    ChatProcessor -->|uses| BookingHandler
    ChatProcessor -->|uses| QuoteCalculator
    ChatProcessor -->|uses| FunctionCallHandler
    ChatProcessor -->|logs| WhatsAppLogger

    ChatProcessor -->|calls| OpenAICore
    ChatProcessor -->|uses| EmbeddingsFunc
    ChatProcessor -->|uses| VectorSearchFunc

    BookingHandler -->|reads/writes| SupabaseDB
    QuoteCalculator -->|reads/writes| SupabaseDB
    FunctionCallHandler -->|reads| SupabaseDB

    AvailabilityHelper -->|reads| AvailSlotsModel
    DistanceHelper -->|calculates via| GoogleMaps
    CostHelper -->|calculates| QuoteCalculator

    HTMLCrawler -.->|scheduled| ContentCrawlerAPI
    HTMLCrawler --> EmbeddingCreator
    PDFCrawler -.->|scheduled| ContentCrawlerPDFAPI
    PDFCrawler --> EmbeddingCreator
    EmbeddingCreator -->|stores| SupabaseDB

    SchedulerScripts -.-> HTMLCrawler
    SchedulerScripts -.-> PDFCrawler

    OpenAICore -->|chat| OpenAI
    EmbeddingsFunc -->|embed| OpenAI
    VectorSearchFunc -->|search| OpenAI
    GoogleMaps -->|geocode/distance| MapsGeocodeAPI
    Twilio -->|messages| WebhookAPI

    %% Click Events
    click WebUI "https://github.com/mesieou/simple_booking/tree/main/app/"
    click WebhookAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/webhook/route.ts"
    click ChatAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/chat/route.ts"
    click ContentCrawlerAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/content-crawler/route.ts"
    click ContentCrawlerPDFAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/content-crawler/pdf/route.ts"
    click MapsAutocompleteAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/maps/autocomplete/route.ts"
    click MapsGeocodeAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/maps/geocode/route.ts"
    click MapsDistanceAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/maps/mapsdistance/route.ts"
    click ProviderInfoAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/provider/[id]/route.ts"
    click ProviderSlotsAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/provider/[id]/slots/route.ts"
    click SeedAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/seed/route.ts"
    click TestConnAPI "https://github.com/mesieou/simple_booking/blob/main/app/api/test-connection/route.ts"
    click AuthCallbackAPI "https://github.com/mesieou/simple_booking/blob/main/app/auth/callback/route.ts"
    click ChatProcessor "https://github.com/mesieou/simple_booking/blob/main/lib/chatbot-handlers/central-chatbot-processor.ts"
    click BookingHandler "https://github.com/mesieou/simple_booking/blob/main/lib/chatbot-handlers/task-processors/booking-handler.ts"
    click QuoteCalculator "https://github.com/mesieou/simple_booking/blob/main/lib/chatbot-handlers/task-processors/quote-calculator.ts"
    click FunctionCallHandler "https://github.com/mesieou/simple_booking/blob/main/lib/chatbot-handlers/task-processors/functio-call-handler.ts"
    click OpenAICore "https://github.com/mesieou/simple_booking/blob/main/lib/llm-actions/chat-interactions/openai-config/openai-core.ts"
    click EmbeddingsFunc "https://github.com/mesieou/simple_booking/blob/main/lib/llm-actions/chat-interactions/functions/embeddings.ts"
    click VectorSearchFunc "https://github.com/mesieou/simple_booking/blob/main/lib/llm-actions/chat-interactions/functions/vector-search.ts"
    click WhatsAppLogger "https://github.com/mesieou/simple_booking/blob/main/lib/llm-actions/whatsapp/whatsapp-message-logger.ts"
    click HTMLCrawler "https://github.com/mesieou/simple_booking/blob/main/lib/backend-actions/content-crawler/html-crawler.ts"
    click PDFCrawler "https://github.com/mesieou/simple_booking/blob/main/lib/backend-actions/content-crawler/pdf-crawler.ts"
    click EmbeddingCreator "https://github.com/mesieou/simple_booking/blob/main/lib/backend-actions/content-crawler/process-content/grouping-storing-content/embedding-creator.ts"
    click SchedulerScripts "https://github.com/mesieou/simple_booking/blob/main/scripts/seed.ts"
    click SchedulerScripts "https://github.com/mesieou/simple_booking/blob/main/scripts/test-crawler.ts"
    click SchedulerScripts "https://github.com/mesieou/simple_booking/blob/main/scripts/uploadPdf.ts"
    click SupabaseDB "https://github.com/mesieou/simple_booking/blob/main/lib/database/supabase/server.ts"
    click AvailSlotsModel "https://github.com/mesieou/simple_booking/blob/main/lib/database/models/availability-slots.ts"
    click BookingModel "https://github.com/mesieou/simple_booking/blob/main/lib/database/models/booking.ts"
    click QuoteModel "https://github.com/mesieou/simple_booking/blob/main/lib/database/models/quote.ts"
    click Migration1 "https://github.com/mesieou/simple_booking/blob/main/lib/database/migrations/001_create_availability_slots.sql"
    click Migration2 "https://github.com/mesieou/simple_booking/blob/main/lib/database/migrations/003_create_embeddings.sql"
    click SeedBookingScript "https://github.com/mesieou/simple_booking/blob/main/lib/database/seed/create-bookings.ts"
    click SeedQuoteScript "https://github.com/mesieou/simple_booking/blob/main/lib/database/seed/create-quotes.ts"
    click AvailabilityHelper "https://github.com/mesieou/simple_booking/blob/main/lib/general-helpers/availability.ts"
    click DistanceHelper "https://github.com/mesieou/simple_booking/blob/main/lib/general-helpers/google-distance-calculator.ts"
    click CostHelper "https://github.com/mesieou/simple_booking/blob/main/lib/general-helpers/quote-cost-calculator.ts"
    click AuthCallbackAPI "https://github.com/mesieou/simple_booking/blob/main/app/auth/callback/route.ts"

    %% Styles
    classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef api fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef business fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef data fill:#E1BEE7,stroke:#4A148C,color:#4A148C
    classDef external fill:#CFD8DC,stroke:#37474F,color:#37474F
```
