# overdrive141/selftalk-ai architecture

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

- Interactive diagram: https://gitdiagram.com/overdrive141/selftalk-ai
- Repository: https://github.com/overdrive141/selftalk-ai

## Overview

##### Main Components
- Frontend Client: Represent the UI layer which includes the pages and components found under src/app (with folders for app, dashboard, conversations, login, etc.) and public assets. This layer handles user interactions.
- Business/Logic Layer: Illustrate the domain-specific logic and utility functions (found in src/lib, such as actions, hooks, database types, events, and seed scripts) that coordinate the APIs with the frontend.
- Database & External Services:
- Database: Mark a data store (e.g., PostgreSQL) inferred from the environment setup (POSTGRES_* variables) and Supabase integration. This is where user data, conversations, and transcripts are stored securely.
- External AI Services: Include relevant AI and audio services such as OpenAI’s GPT-3.5 for conversational intelligence, Eleven Labs for text-to-speech, and possibly Replicate (as indicated by the API token) for additional processing.

##### Out Relationships and Data Flow
- Role of the API backend as the mediator between the frontend and back-end services (e.g., the database and external AI/audio services).
- How business logic (in the lib folder) is invoked by API endpoints to handle application-specific tasks (like chat handling, audio conversion, emotion recognition, etc.).
- Authentication flows: from login pages and auth API routes, through secure communication of environment variables, to the database storage of user session data.

##### Architectural Patterns and Design Principles
- Component Separation: Clearly separate the UI components from the business logic and the API endpoints to illustrate a decoupled and modular design.
- API-Centric Communication: Indicate RESTful or Next.js Route Handlers (found in src/app/api) that act as a communication bridge between the user interface and the backend.
- Scalability & Extensibility: Note the existence of modular folders (such as for audio, conversations, user actions) and external configuration files (like next.config.js, tailwind.config.js, postcss.config.js).
- Secure and Maintainable Codebase: Emphasize secure data handling (as outlined in the README) and the use of environment variables for sensitive credentials.

##### Summary – Key Elements to Capture
✓ Frontend Components (Next.js pages, components in src/app and src/components)
✓ API Layer (located in src/app/api, with endpoints for various functionalities)
✓ Data Flow: User interactions → API endpoints → Business logic (src/lib) → Database/External Services
✓ Integration with external AI and audio processing services (OpenAI, Eleven Labs, etc.)
✓ Secure Handling of Configuration and Sensitive Data (environment variables and middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user

    subgraph "Client Side (Frontend)"
        PNL("Pages & Layout"):::frontend
        CP("Conversations Page"):::frontend
        DP("Dashboard Page"):::frontend
        LP("Login Page"):::frontend
        UIC("UI Components"):::frontend
        AFC("Auth Form Component"):::frontend
        SNC("Sidebar Nav Component"):::frontend
        PA("Public Assets"):::frontend
    end

    subgraph "Server Side (API Backend)"
        AUA("Add User API"):::backend
        AA("Audio API"):::backend
        CA("Chat API"):::backend
        CoA("Conversations API"):::backend
        CST("Convert STT API"):::backend
        CTT("Convert TTS API"):::backend
        LA("Logout API"):::backend
        RVA("Register Voice API"):::backend
        ACA("Auth Callback API"):::backend
        SA("Signout API"):::backend
    end

    subgraph "Business Logic Layer"
        DLU("Domain Logic & Utilities"):::business
        AH("Additional Hooks"):::business
    end

    subgraph "Infrastructure"
        DB("Database (PostgreSQL/Supabase)"):::infra
        EAI("External AI Services"):::infra
    end

    %% Data Flow Connections
    U -->|"interacts"| PNL
    PNL -->|"chat"| CA
    LP -->|"auth"| ACA
    DP -->|"conversation"| CoA

    %% API Endpoints invoking Business Logic
    AUA -->|"logic"| DLU
    AA  -->|"audio"| DLU
    CA  -->|"logic"| DLU
    CoA -->|"logic"| DLU
    CST -->|"logic"| DLU
    CTT -->|"logic"| DLU
    LA  -->|"session"| DLU
    RVA -->|"register"| DLU
    ACA -->|"auth"| DLU
    SA  -->|"session"| DLU

    %% Business Logic accessing Infrastructure
    DLU -->|"db-access"| DB
    DLU -->|"ai-call"| EAI

    %% Styling
    classDef frontend fill:#f1c40f,stroke:#333,stroke-width:2px;
    classDef backend fill:#3498db,stroke:#333,stroke-width:2px;
    classDef business fill:#2ecc71,stroke:#333,stroke-width:2px;
    classDef infra fill:#9b59b6,stroke:#333,stroke-width:2px;
    classDef user fill:#e74c3c,stroke:#333,stroke-width:2px;

    %% Click Events for Frontend Components
    click PNL "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/page.tsx"
    click PNL "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/layout.tsx"
    click CP "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/app/conversations/page.tsx"
    click DP "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/app/dashboard/page.tsx"
    click LP "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/login/page.tsx"
    click UIC "https://github.com/overdrive141/selftalk-ai/tree/main/src/components"
    click AFC "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/app/(components)/auth-form.tsx"
    click SNC "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/app/(components)/sidebar-nav.tsx"
    click PA "https://github.com/overdrive141/selftalk-ai/tree/main/public"

    %% Click Events for API Backend Endpoints
    click AUA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/add-user/route.ts"
    click AA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/audio/route.ts"
    click CA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/chat/route.ts"
    click CoA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/conversations/route.ts"
    click CST "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/convert-stt/route.ts"
    click CTT "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/convert-tts/route.ts"
    click LA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/logout/route.ts"
    click RVA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/api/register-voice/route.ts"
    click ACA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/auth/callback/route.ts"
    click SA "https://github.com/overdrive141/selftalk-ai/blob/main/src/app/auth/signout/route.ts"

    %% Click Events for Business/Logic Layer
    click DLU "https://github.com/overdrive141/selftalk-ai/blob/main/src/lib/actions.ts"
    click AH "https://github.com/overdrive141/selftalk-ai/blob/main/src/lib/hooks/use-at-bottom.tsx"

    %% Click Events for Infrastructure
    click DB "https://github.com/overdrive141/selftalk-ai/blob/main/src/lib/kysely.ts"
```
