# gianpaj/sexyvoice architecture

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

- Interactive diagram: https://gitdiagram.com/gianpaj/sexyvoice
- Repository: https://github.com/gianpaj/sexyvoice

## Overview

##### Project type and purpose
- SexyVoice.ai is a full-stack, multi-language AI voice generation and cloning platform.
- Frontend: Next.js 15 with App Router and TypeScript.
- Backend: Next.js server-side API routes, Supabase (PostgreSQL + Auth), Redis (Upstash KV), Vercel Blob storage.
- External AI services: Replicate, Fal.ai, Google Generative AI.
- Payments: Stripe.
- Monitoring & analytics: Sentry, PostHog; CI/CD on Vercel.

##### File structure
- app/ → Next.js App Router pages and Server/Client components.
- app/api/ → Route handlers (clone-voice, generate-text, generate-voice, stripe/webhook, etc.).
- supabase/ → Infrastructure: SQL migrations, edge functions (Telegram cronjob).
- lib/ & utils/ → Core logic: API wrappers (supabase, stripe, redis, ai), constants, helpers.
- components/ & hooks/ → UI and client hooks.
- public/, posts/, contentlayer.config.ts → CMS for blog.
- config files: next.config.js, vercel.json, .env.example, toolchain (pnpm, Biome, TypeScript).

##### README for additional insights
- Architecture.md link for an overview.
- Tech stack calls out each major service.
- Credit-based usage, RLS in PostgreSQL, rate limiting, real-time updates.

##### Detailed but not over-engineered
- Break out major subsystems: UI, API, Data, AI, Payments, Monitoring.
- Authentication, credit deduction, file storage, AI invocation, and billing.
- Keep each component self-contained with one or two inbound/outbound flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser(("Browser")):::frontend
        NextJSAppRouter["Next.js Frontend (App Router & Pages)"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        NextJSServer["Next.js Server (SSR & API Routes)"]:::backend

        subgraph "API Routes"
            direction TB
            RouteCloneVoice["Clone Voice API"]:::backend
            RouteGenVoice["Generate Voice API"]:::backend
            RouteGenText["Generate Text API"]:::backend
            RouteDailyStats["Daily Stats (cron)"]:::backend
            RouteHealth["Health Check API"]:::backend
            RoutePopularAudios["Popular Audios API"]:::backend
            RouteStripeTx["Stripe Transactions API"]:::backend
            RouteStripeWebhook["Stripe Webhook API"]:::backend
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        SupabaseAuthDB["Supabase Auth & PostgreSQL"]:::db
        RedisKV["Redis (Upstash KV)"]:::db
        BlobStorage["Vercel Blob Storage"]:::storage
        EdgeFunction["Supabase Edge Function\n(Telegram Cronjob)"]:::backend
    end

    %% External Integrations
    subgraph "External Services"
        direction TB
        Replicate["Replicate AI"]:::external
        FalAI["Fal.ai"]:::external
        GoogleAI["Google Generative AI"]:::external
        Stripe["Stripe"]:::payment
        TelegramBot["Telegram Bot"]:::external
    end

    %% Monitoring & Analytics
    subgraph "Monitoring & Analytics"
        direction TB
        Sentry["Sentry"]:::monitoring
        PostHog["PostHog"]:::monitoring
    end

    %% Flows
    Browser -->|"SSR & RSC"| NextJSAppRouter
    NextJSAppRouter -->|page request| NextJSServer

    Browser -->|invoke API| RouteGenVoice
    Browser -->|invoke API| RouteCloneVoice
    Browser -->|invoke API| RouteGenText
    Browser -->|view stats| RoutePopularAudios

    NextJSServer -->|calls| SupabaseAuthDB
    NextJSServer -->|rate-limit & cache| RedisKV
    NextJSServer -->|store audio| BlobStorage
    NextJSServer -->|invoke| lib_ai[AI Wrapper]:::backend
    lib_ai -->|call| Replicate
    lib_ai -->|call| FalAI
    lib_ai -->|call| GoogleAI

    RouteGenVoice --> lib_ai
    RouteCloneVoice --> lib_ai
    RouteGenText --> lib_ai

    RouteStripeTx -->|create session| Stripe
    RouteStripeWebhook -.->|webhook| Stripe
    RouteStripeWebhook -->|update credits| SupabaseAuthDB

    EdgeFunction -.->|cron trigger| RouteDailyStats
    EdgeFunction -->|read stats| RedisKV
    EdgeFunction -->|send message| TelegramBot

    RouteDailyStats --> RedisKV

    Sentry <-->|error tracking| NextJSServer
    Sentry <-->|error tracking| EdgeFunction
    PostHog <-->|analytics| NextJSAppRouter
    PostHog <-->|analytics| NextJSServer

    %% Click Events
    click NextJSAppRouter "https://github.com/gianpaj/sexyvoice/tree/main/app/"
    click RouteCloneVoice "https://github.com/gianpaj/sexyvoice/blob/main/app/api/clone-voice/route.ts"
    click RouteGenVoice "https://github.com/gianpaj/sexyvoice/blob/main/app/api/generate-voice/route.ts"
    click RouteGenText "https://github.com/gianpaj/sexyvoice/blob/main/app/api/generate-text/route.ts"
    click RouteDailyStats "https://github.com/gianpaj/sexyvoice/blob/main/app/api/daily-stats/route.ts"
    click RouteHealth "https://github.com/gianpaj/sexyvoice/blob/main/app/api/health/route.ts"
    click RoutePopularAudios "https://github.com/gianpaj/sexyvoice/blob/main/app/api/popular-audios/route.ts"
    click RouteStripeTx "https://github.com/gianpaj/sexyvoice/blob/main/app/api/stripe/transactions/route.ts"
    click RouteStripeWebhook "https://github.com/gianpaj/sexyvoice/blob/main/app/api/stripe/webhook/route.ts"
    click lib_supabase_client "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/client.ts"
    click lib_supabase_server "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/server.ts"
    click lib_supabase_admin "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/admin.ts"
    click lib_supabase_middleware "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/middleware.ts"
    click lib_supabase_queries "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/queries.ts"
    click lib_supabase_queries_client "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/queries.client.ts"
    click lib_supabase_types "https://github.com/gianpaj/sexyvoice/blob/main/lib/supabase/types.d.ts"
    click supabase_migrations "https://github.com/gianpaj/sexyvoice/tree/main/supabase/migrations/"
    click RedisKV "https://github.com/gianpaj/sexyvoice/blob/main/lib/redis/queries.ts"
    click BlobStorage "https://github.com/gianpaj/sexyvoice/blob/main/lib/audio.ts"
    click lib_ai "https://github.com/gianpaj/sexyvoice/blob/main/lib/ai.ts"
    click sup_edge "https://github.com/gianpaj/sexyvoice/blob/main/supabase/functions/telegram-bot/index.ts"
    click lib_stripe_admin "https://github.com/gianpaj/sexyvoice/blob/main/lib/stripe/stripe-admin.ts"
    click app_stripe_action "https://github.com/gianpaj/sexyvoice/blob/main/app/actions/stripe.ts"
    click util_get_stripejs "https://github.com/gianpaj/sexyvoice/blob/main/utils/get-stripejs.ts"
    click util_stripe_helpers "https://github.com/gianpaj/sexyvoice/blob/main/utils/stripe-helpers.ts"
    click sentry_server "https://github.com/gianpaj/sexyvoice/blob/main/sentry.server.config.ts"
    click sentry_edge "https://github.com/gianpaj/sexyvoice/blob/main/sentry.edge.config.ts"
    click lib_posthog "https://github.com/gianpaj/sexyvoice/blob/main/lib/posthog.ts"
    click PostHogProvider "https://github.com/gianpaj/sexyvoice/blob/main/components/PostHogProvider.tsx"
    click instrumentation "https://github.com/gianpaj/sexyvoice/blob/main/instrumentation.ts"
    click ui_lib "https://github.com/gianpaj/sexyvoice/tree/main/components/ui/"
    click comp_audio_gen "https://github.com/gianpaj/sexyvoice/blob/main/components/audio-generator.tsx"
    click comp_voice_sel "https://github.com/gianpaj/sexyvoice/blob/main/components/voice-selector.tsx"
    click comp_credits "https://github.com/gianpaj/sexyvoice/blob/main/components/credits-section.tsx"
    click hook_file_upload "https://github.com/gianpaj/sexyvoice/blob/main/hooks/use-file-upload.ts"
    click hook_toast "https://github.com/gianpaj/sexyvoice/blob/main/hooks/use-toast.ts"

    %% Styles
    classDef frontend fill:#D6E8FF,stroke:#0366d6
    classDef backend fill:#E8F5E9,stroke:#2E7D32
    classDef db fill:#FFF3E0,stroke:#EF6C00
    classDef storage fill:#F3E5F5,stroke:#8E24AA
    classDef external fill:#E1F5FE,stroke:#0288D1,stroke-dasharray: 5 5
    classDef payment fill:#FFEBEE,stroke:#C62828
    classDef monitoring fill:#ECEFF1,stroke:#455A64
```
