# pixyglee/yorby architecture

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

- Interactive diagram: https://gitdiagram.com/pixyglee/yorby
- Repository: https://github.com/pixyglee/yorby

## Overview

##### Project type and purpose
- This is a full-stack, multi-tenant web application (“Yorby”) built with Next.js 15 (App Router) in TypeScript.
- It serves both B2B (AI-powered recruitment, candidate screening) and B2C (job-seeker mock interviews) use cases.
- It integrates real-time voice/video interviews, AI analysis, database storage, authentication, payments, and monitoring.

##### File structure
- **nextjs/**: the main Next.js application
- app/ → nested App Router routes (pages, layouts, server/client components)
- app/api/ → Next.js API Routes (serverless functions)
- components/, lib/, utils/, context/, hooks/ → shared UI, helper modules, React contexts
- public/ → static assets (demo videos, PDFs)
- supabase/ → Supabase migrations and email templates
- config files: next.config.ts, tailwind.config.js, sentry configs, vercel.json
- **supabase/**: local Supabase project configuration
- migrations/ → SQL scripts defining schema, RLS policies
- templates/ → email templates for auth flows
- CI/CD in .github/workflows

##### README for architectural insights
- Tech stack overview: Next.js, TypeScript, Tailwind, shadcn/ui
- Database: Supabase (PostgreSQL) with Row-Level-Security
- AI: Google AI SDK, OpenAI
- Real-time: LiveKit
- Video storage: Mux
- Speech transcription: Deepgram
- Payments: Stripe
- Monitoring/analytics: Sentry, PostHog, Axiom
- Multi-language support (i18n)

a. Main components
- Client (Web Browser)
- Next.js Application (deployed to Vercel or similar)
- Frontend: SSR/CSR React pages (App Router)
- Backend: API Routes (app/api/*) & Edge Functions
- Database & Storage
- Supabase (PostgreSQL + Storage buckets + Auth + Edge Functions)
- Real-time & Media
- LiveKit server (voice/video rooms)
- Mux (recording, playback)
- AI & Speech Services
- OpenAI/Google AI endpoints
- Deepgram transcription API
- Payments & Webhooks
- Stripe API + webhook receivers
- Monitoring & Analytics
- Sentry, PostHog, Axiom

b. Relationships & data flows
- Browser ↔ Next.js (HTTP for SSR + REST for client navigation)
- Browser ↔ LiveKit (WebSocket for real-time voice/video sessions)
- Next.js API ↔ Supabase (RPC/SQL calls via supabase client)
- Next.js API ↔ AI services (HTTPS calls to OpenAI/Google AI/Deepgram)
- Next.js API ↔ Stripe (HTTPS calls + webhook endpoints)
- Supabase Triggers/Webhooks → Next.js Edge Functions for async processing
- Next.js ↔ Mux (HTTPS to upload/retrieve video assets)

c. Architectural patterns & design principles
- **App Router** with nested layouts for domain-driven routing
- **API Route Layer** co-located with frontend code for domain logic
- **Context Providers** for global state (Auth, Onboarding, Multi-Tenant)
- **Modular folder structure** (apply, auth, dashboard, recruiting, etc.)
- **RLS** in Supabase for multi-tenant and role-based access
- **Server/Client components** mixing for performance and SEO

d. Key technologies/frameworks
- Next.js 15, React 19, TypeScript
- Tailwind CSS, shadcn/ui
- Supabase (Database, Auth, Storage, Edge Functions)
- LiveKit, Mux
- Deepgram, OpenAI, Google AI SDK
- Stripe, PostHog, Sentry, Axiom

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        Browser["Web Browser"]:::frontend
        LiveKitClient["LiveKit Client"]:::external
    end

    %% Next.js Layer
    subgraph "Next.js Layer" 
        direction TB
        SSR["SSR/CSR Pages"]:::frontend
        AuthUI["Auth UI & Flows"]:::frontend
        ContextApp["App Context Providers"]:::frontend
        ContextGlobal["Global Context Providers"]:::frontend
        subgraph "API Routes" 
            direction TB
            LiveKitConn["LiveKit Connection Details API"]:::backend
            MuxWebhook["Mux Webhook Receiver"]:::backend
            StripeWebhook["Stripe Webhook Receiver"]:::backend
            DeepgramAuth["Deepgram Auth API"]:::backend
            ParseQ["Questions Parse API"]:::backend
            ChatAPI["Chat API"]:::backend
            MemoriesAPI["Memories API"]:::backend
            AuthCallback["Auth Callback Route"]:::backend
            AuthConfirm["Auth Confirm Route"]:::backend
        end
        SupClient["Supabase Client (Client)"]:::backend
        SupServer["Supabase Client (Server)"]:::backend
        AIUtilsG["Google AI SDK (Gemini)"]:::backend
        UtilsGeneral["General Utils"]:::backend
        UtilsAuth["Auth Helpers"]:::backend
        UtilsSup["Supabase Helpers"]:::backend
        UtilsStorage["Storage Helpers"]:::backend
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        SupabaseDB["Supabase Database"]:::datastore
        SupabaseStorage["Supabase Storage Buckets"]:::datastore
        SupabaseMigrations["Supabase Migrations"]:::datastore
        SupabaseTemplates["Supabase Email Templates"]:::datastore
    end

    %% Third-Party Services
    subgraph "Third-Party Services"
        direction TB
        LiveKitServer["LiveKit Server"]:::external
        MuxService["Mux Video Service"]:::external
        OpenAI["OpenAI API"]:::external
        GoogleAI["Google AI API"]:::external
        Deepgram["Deepgram Transcription API"]:::external
        StripeAPI["Stripe API"]:::external
        Sentry["Sentry"]:::monitoring
        PostHog["PostHog"]:::monitoring
        Axiom["Axiom"]:::monitoring
    end

    %% Connections
    Browser -->|"HTTP/SSR & CSR"| SSR
    Browser -->|"WebSocket"| LiveKitClient
    LiveKitClient -->|"WebSocket"| LiveKitServer

    Browser -->|"OAuth/Callback"| AuthUI
    SSR -->|"uses"| SupClient
    SSR -->|"calls API Routes"| LiveKitConn
    SSR -->|"calls API Routes"| ChatAPI

    AuthUI -->|"calls API Routes"| AuthCallback
    AuthUI -->|"calls API Routes"| AuthConfirm

    ContextApp --> SSR
    ContextGlobal --> SSR

    SupClient -->|"RPC/SQL"| SupabaseDB
    SupServer -->|"RPC/SQL"| SupabaseDB

    LiveKitConn --> LiveKitServer
    MuxWebhook --> MuxService
    StripeWebhook --> StripeAPI
    DeepgramAuth --> Deepgram
    ParseQ --> OpenAI
    AIUtilsG --> GoogleAI
    ChatAPI --> OpenAI
    ChatAPI --> GoogleAI
    MemoriesAPI --> SupabaseDB

    StripeAPI -->|"webhook"| StripeWebhook

    SSR -->|"uploads/downloads"| SupabaseStorage
    SSR -->|"uploads/downloads"| MuxService

    SSR -->|"calls utils"| AIUtilsG
    SSR -->|"calls utils"| UtilsGeneral
    SSR -->|"calls utils"| UtilsAuth
    SSR -->|"calls utils"| UtilsSup
    SSR -->|"calls utils"| UtilsStorage

    SupabaseDB -->|"RLS & Triggers"| SupabaseMigrations
    SupabaseDB -->|"Auth Emails"| SupabaseTemplates

    SSR -->|"monitoring events"| Sentry
    SSR -->|"analytics events"| PostHog
    SSR -->|"logging"| Axiom

    %% Click Events
    click SSR "https://github.com/pixyglee/yorby/tree/main/nextjs/app"
    click AuthUI "https://github.com/pixyglee/yorby/tree/main/nextjs/app/auth"
    click ContextApp "https://github.com/pixyglee/yorby/tree/main/nextjs/app/context"
    click ContextGlobal "https://github.com/pixyglee/yorby/tree/main/nextjs/context"
    click LiveKitConn "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/livekit/connection-details/route.ts"
    click MuxWebhook "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/webhooks/mux/route.ts"
    click StripeWebhook "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/webhooks/stripe/route.ts"
    click DeepgramAuth "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/deepgram/authenticate/route.ts"
    click ParseQ "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/questions/parse/route.ts"
    click ChatAPI "https://github.com/pixyglee/yorby/blob/main/nextjs/app/api/chat/route.ts"
    click MemoriesAPI "https://github.com/pixyglee/yorby/tree/main/nextjs/app/api/memories"
    click AuthCallback "https://github.com/pixyglee/yorby/blob/main/nextjs/app/auth/callback/route.ts"
    click AuthConfirm "https://github.com/pixyglee/yorby/blob/main/nextjs/app/auth/confirm/route.ts"
    click SupClient "https://github.com/pixyglee/yorby/blob/main/nextjs/lib/supabase/client.ts"
    click SupServer "https://github.com/pixyglee/yorby/blob/main/nextjs/lib/supabase/server.ts"
    click SupabaseMigrations "https://github.com/pixyglee/yorby/tree/main/supabase/migrations"
    click SupabaseTemplates "https://github.com/pixyglee/yorby/tree/main/supabase/templates"
    click AIUtilsG "https://github.com/pixyglee/yorby/blob/main/nextjs/utils/ai/gemini.ts"
    click UtilsGeneral "https://github.com/pixyglee/yorby/blob/main/nextjs/utils/utils.ts"
    click UtilsAuth "https://github.com/pixyglee/yorby/blob/main/nextjs/utils/auth/server.ts"
    click UtilsSup "https://github.com/pixyglee/yorby/tree/main/nextjs/utils/supabase"
    click UtilsStorage "https://github.com/pixyglee/yorby/blob/main/nextjs/utils/storage.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef datastore fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
    classDef monitoring fill:#ECEFF1,stroke:#263238,color:#263238
```
