# recoupable/recoup-chat architecture

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

- Interactive diagram: https://gitdiagram.com/recoupable/recoup-chat
- Repository: https://github.com/recoupable/recoup-chat

## Overview

##### Main Components
- Frontend User Interface:
- Pages in the “app/” folder with dynamic routing (e.g., chat pages, artist pages, funnels, reports).
- Reusable UI components under “components/”.
- Custom React hooks (“hooks/”) that manage UI interactivity.
- Providers (“providers/”) that supply global context (user, chat, payment, autopilot, etc.).
- Backend API Endpoints:
- Numerous API routes within “app/api/” handling various functions such as account management, artist actions, chat, credits, email, reporting, uploads, etc.
- These endpoints follow Next.js API routing conventions.
- Data Storage & External Integration:
- Supabase integration for data storage and migrations (located in “supabase/migrations/”).
- External services configuration, such as Privy for authentication and Stripe (in “lib/stripe”).
- Utility & Service Layers:
- “lib/”: Contains a variety of helper functions (for chat, agents, PDF generation, reporting, IPFS, Supabase queries, etc.).
- “types/”: TypeScript type definitions that support both frontend and backend.
- Evaluation Suite:
- The “evals/” directory holds many evaluation scripts, test cases, and experiments designed to validate and fine-tune the AI components.
- This section interacts with the core AI models and external evaluation APIs.

##### Relationships and Data Flow
- The frontend (user browser) communicates with the Next.js server:
- UI components render data fetched from API endpoints.
- Context providers (e.g., ChatProvider, UserProvider) manage state and pass it through the component tree.
- API Routes:
- Receive requests from the client and orchestrate backend logic, including data manipulation, authentication (via Privy), and communication with Supabase.
- They often delegate tasks to utility functions in “lib/” to process data or generate responses.
- Data Storage:
- Supabase acts as the persistent store for artists, accounts, campaigns, reviews, etc. API endpoints interact with Supabase using dedicated helper functions.
- Evaluation Flow:
- The evals scripts run tests (such as OpenAI Evals) to ensure AI responses are of high quality. They simulate real user interactions with the chatbot and possibly track metrics.
- These evaluation components can be isolated as a sub‑system that periodically polls or triggers test cases.

##### Architectural Patterns & Design Principles
- Separation of Concerns:
- Clear division between UI (pages/components) and backend (API endpoints and service libraries).
- Modular Design:
- Each feature (e.g., chat, account, artist actions) is encapsulated with its own dedicated API route, client-side component, and sometimes even its own provider/hook.
- Type Safety & Extensibility:
- Use of TypeScript (with types defined under “types/”) enforces correctness across components and services.
- External Integration:
- Integration with third‑party services (Supabase, Privy, Stripe) is isolated within the “lib/” directory so that changing one integration doesn’t affect other parts.
- Evaluation as a First‑Class Component:
- The extensive “evals/” directory highlights that the project uses continuous assessment to validate AI quality, making this an essential part of architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        A1["Next.js Pages"]:::frontend
        A2["UI Components"]:::frontend
        A3["Custom React Hooks"]:::frontend
        A4["Context Providers"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend"
        B1["API Endpoints"]:::backend
        B2["Helper Functions"]:::utility
        B3["Type Definitions"]:::utility
        subgraph "Data Storage & External Integration"
            C1["Supabase Database"]:::storage
            C2["Stripe Integration"]:::storage
        end
    end

    %% Evaluation & Testing Layer
    subgraph "Evaluation & Testing"
        D1["Evaluation Suite"]:::eval
    end

    %% Frontend internal relationships
    A1 -->|"uses"| A2
    A1 -->|"uses"| A3
    A1 -->|"provides"| A4

    %% Frontend to Backend
    A4 -->|"requests"| B1
    A1 -->|"requests"| B1

    %% Backend internal relationships
    B1 -->|"delegates"| B2
    B1 -->|"reliesOn"| B3
    B1 -->|"reads/writes"| C1
    B1 -->|"handles"| C2

    %% Evaluation flow
    D1 ---|"feedback"| B1

    %% Click Events
    click A1 "https://github.com/recoupable/recoup-chat/tree/main/app/"
    click A2 "https://github.com/recoupable/recoup-chat/tree/main/components/"
    click A3 "https://github.com/recoupable/recoup-chat/tree/main/hooks/"
    click A4 "https://github.com/recoupable/recoup-chat/tree/main/providers/"
    click B1 "https://github.com/recoupable/recoup-chat/tree/main/app/api/"
    click B2 "https://github.com/recoupable/recoup-chat/tree/main/lib/"
    click B3 "https://github.com/recoupable/recoup-chat/tree/main/types/"
    click C1 "https://github.com/recoupable/recoup-chat/tree/main/supabase/migrations/"
    click C2 "https://github.com/recoupable/recoup-chat/tree/main/lib/stripe/"
    click D1 "https://github.com/recoupable/recoup-chat/tree/main/evals/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#2a9df4,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef storage fill:#f8d7da,stroke:#dc3545,stroke-width:2px;
    classDef eval fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef utility fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
