# itusiai/open-voicecanvas architecture

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

- Interactive diagram: https://gitdiagram.com/itusiai/open-voicecanvas
- Repository: https://github.com/itusiai/open-voicecanvas

## Overview

##### Main Components

- Frontend Interface:
- Built with Next.js 14 and styled using Tailwind CSS and shadcn/ui.
- Contains multiple UI pages/components (e.g., home, auth pages, profile, pricing, cloning) organized in the “app” directory.
- Navigation, theme, and analytics provided by components (e.g., nav-bar, theme-provider, google-analytics).

- Backend/API Endpoints:
- Structured under the “app/api” directory using Next.js routing conventions.
- Contains endpoints for authentication (login, register, NextAuth), checkout sessions (Stripe integration), speech processing, voice cloning, user management (plan updates, quota updates), and webhook handling (Stripe).

- Business Logic & Utility Libraries:
- Located in the “lib” directory which encapsulates core functionalities such as authentication, rate limiting, voice configurations, and third-party API integrations.
- Also includes a robust i18n system in “lib/i18n” for multi-language support.

- Database Layer:
- Managed with Prisma (files in the “prisma” directory) connecting to a Neon PostgreSQL database.
- Contains models for Users, Subscriptions, Character Quotas, and Cloned Voices as described in the README.

- External Services Integration:
- Voice Services: OpenAI TTS, AWS Polly, MiniMax.
- Authentication: NextAuth configured to support OAuth providers like Google and GitHub.
- Payment & Subscription: Stripe payment (checkout sessions and webhooks).
- Environment configurations for API keys and credentials (defined by environment variables).

##### Relationships and Data Flows

- The Frontend communicates with the Backend APIs through HTTP requests, initiating actions such as user login, registration, file uploads, and voice service requests.
- API endpoints delegate tasks to business logic in the “lib” folder to handle core actions (voice processing, persistence with Prisma, rate limiting, etc.).
- The database (PostgreSQL via Prisma) stores user data, subscription details, usage quotas, and voice clone records.
- External integrations are triggered as needed:
- For TTS/voice cloning, the API endpoints call external services (OpenAI, AWS, MiniMax) through the corresponding modules in “lib”.
- Payment processing involves sending requests to Stripe and receiving webhook events that update the subscription and quota state in the database.

##### Architectural Patterns and Design Principles

- Separation of Concerns:
- Clearly separate the UI layer (pages/components) from the API/business logic and further separate core integrations (external services) in the “lib” folder.
- Use Next.js API routes to encapsulate backend functionality making the project modular.

- Modular Design:
- Reusable UI components stored in the “components” directory along with dedicated hooks (e.g., use-analytics, use-speech) ensure reusability and ease testing.
- The “lib” directory centralizes third-party integrations and utility functions.

- Extensibility and Scalability:
- The file and folder structure allows you to add new services or modify existing ones without disturbing the overall architecture.
- The i18n structure and modular API routes support expanding language support or additional functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Interface
    subgraph "Frontend Interface"
        subgraph "Pages & Layouts"
            A1("app/app/layout.tsx")
            A2("app/app/page.tsx")
            A3("app/page.tsx")
            A4("app/auth/login/page.tsx")
            A5("app/cloning/page.tsx")
            A6("app/cloning/layout.tsx")
            A7("app/profile/page.tsx")
            A8("app/pricing/page.tsx")
        end
        subgraph "Global Styling"
            FS("app/globals.css")
        end
        subgraph "Shared UI Components"
            SUI("components/")
        end
    end

    %% Backend/API Endpoints
    subgraph "Backend/API Endpoints"
        subgraph "Authentication Endpoints"
            B1("app/api/auth/[...nextauth]/route.ts")
            B2("app/api/auth/login/route.ts")
            B3("app/api/auth/register/route.ts")
        end
        subgraph "Checkout & Webhook"
            B4("app/api/create-checkout-session/route.ts")
            B10("app/api/webhook/stripe/route.ts")
        end
        subgraph "Speech & Voice Cloning"
            B5("app/api/speech/route.ts")
            B6("app/api/voice/clone/route.ts")
            B7("app/api/voice/cloned-voices/route.ts")
            B8("app/api/voice/openai-tts/route.ts")
        end
        subgraph "User Management"
            B9("app/api/user/plan/route.ts")
            B11("app/api/user/update-clones/route.ts")
            B12("app/api/user/update-quota/route.ts")
        end
    end

    %% Business Logic & Utility Libraries
    subgraph "Business Logic & Utility Libraries"
        subgraph "Core Utilities"
            L1("lib/auth.ts")
            L2("lib/rate-limit.ts")
            L3("lib/utils.ts")
            L4("lib/voice-config.ts")
        end
        subgraph "API Integrations"
            L5("lib/openai.ts")
            L6("lib/polly-service.ts")
            L7("lib/aws-config.ts")
        end
        subgraph "Internationalization (i18n)"
            L8("lib/i18n/index.ts")
            L9("lib/i18n/language-context.tsx")
            L10("lib/i18n/translations/")
        end
    end

    %% Database Layer
    subgraph "Database Layer"
        D1("prisma/schema.prisma")
        D2("lib/prisma.ts")
        D3("prisma/migrations/")
    end

    %% External Services Integration
    subgraph "External Services Integration"
        subgraph "Voice Services"
            E1("OpenAI TTS")
            E2("AWS Polly")
            E3("MiniMax")
        end
        subgraph "Authentication & Payment"
            E4("NextAuth (OAuth:Google,GitHub)")
            E5("Stripe Payment")
        end
    end

    %% Connections
    %% Frontend to Backend
    A4 -->|"HTTP_request"| B1
    A3 -->|"User_interaction"| A4

    %% Backend to Business Logic
    B1 -->|"Auth_logic"| L1
    B8 -->|"Voice_synthesis"| L5
    B6 -->|"Cloning_request"| E2

    %% Business Logic to Database
    L1 -->|"Persist_user_data"| D1
    L3 -->|"Query_data"| D2
    B9 -->|"Update_subscription"| D1

    %% Business Logic to External Services
    L5 -->|"Call_API"| E1
    L6 -->|"Integrate_API"| E2

    %% Backend directly to External Services
    B1 -->|"OAuth_integration"| E4
    B4 -->|"Initiate_checkout"| E5
    B10 -->|"Webhook_event"| E5

    %% Styling Classes
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef backend fill:#f8d7da,stroke:#333,stroke-width:1px;
    classDef utilities fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef database fill:#fff3cd,stroke:#333,stroke-width:1px;
    classDef external fill:#d1ecf1,stroke:#333,stroke-width:1px;

    class A1,A2,A3,A4,A5,A6,A7,A8,FS,SUI frontend;
    class B1,B2,B3,B4,B5,B6,B7,B8,B9,B10,B11,B12 backend;
    class L1,L2,L3,L4,L5,L6,L7,L8,L9,L10 utilities;
    class D1,D2,D3 database;
    class E1,E2,E3,E4,E5 external;

    %% Click Events for Frontend Interface
    click A1 "https://github.com/itusiai/open-voicecanvas/blob/main/app/app/layout.tsx"
    click A2 "https://github.com/itusiai/open-voicecanvas/blob/main/app/app/page.tsx"
    click A3 "https://github.com/itusiai/open-voicecanvas/blob/main/app/page.tsx"
    click A4 "https://github.com/itusiai/open-voicecanvas/blob/main/app/auth/login/page.tsx"
    click A5 "https://github.com/itusiai/open-voicecanvas/blob/main/app/cloning/page.tsx"
    click A6 "https://github.com/itusiai/open-voicecanvas/blob/main/app/cloning/layout.tsx"
    click A7 "https://github.com/itusiai/open-voicecanvas/blob/main/app/profile/page.tsx"
    click A8 "https://github.com/itusiai/open-voicecanvas/blob/main/app/pricing/page.tsx"
    click FS "https://github.com/itusiai/open-voicecanvas/blob/main/app/globals.css"
    click SUI "https://github.com/itusiai/open-voicecanvas/tree/main/components/"

    %% Click Events for Backend/API Endpoints
    click B1 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/auth/[...nextauth]/route.ts"
    click B2 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/auth/login/route.ts"
    click B3 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/auth/register/route.ts"
    click B4 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/create-checkout-session/route.ts"
    click B5 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/speech/route.ts"
    click B6 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/voice/clone/route.ts"
    click B7 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/voice/cloned-voices/route.ts"
    click B8 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/voice/openai-tts/route.ts"
    click B9 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/user/plan/route.ts"
    click B10 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/webhook/stripe/route.ts"
    click B11 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/user/update-clones/route.ts"
    click B12 "https://github.com/itusiai/open-voicecanvas/blob/main/app/api/user/update-quota/route.ts"

    %% Click Events for Business Logic & Utility Libraries
    click L1 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/auth.ts"
    click L2 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/rate-limit.ts"
    click L3 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/utils.ts"
    click L4 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/voice-config.ts"
    click L5 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/openai.ts"
    click L6 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/polly-service.ts"
    click L7 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/aws-config.ts"
    click L8 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/i18n/index.ts"
    click L9 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/i18n/language-context.tsx"
    click L10 "https://github.com/itusiai/open-voicecanvas/tree/main/lib/i18n/translations/"

    %% Click Events for Database Layer
    click D1 "https://github.com/itusiai/open-voicecanvas/blob/main/prisma/schema.prisma"
    click D2 "https://github.com/itusiai/open-voicecanvas/blob/main/lib/prisma.ts"
    click D3 "https://github.com/itusiai/open-voicecanvas/tree/main/prisma/migrations/"
```
