# abhiagni11/tagore-speaks architecture

> Architecture diagram of the GitHub repository abhiagni11/tagore-speaks, 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/abhiagni11/tagore-speaks
- Repository: https://github.com/abhiagni11/tagore-speaks

## Overview

##### Main Components

- Frontend:
- A React application with TypeScript and Tailwind CSS.
- Components include Chat (chat container, chat input, message list, audio visualization), Header, Theme Toggle, and various hooks and services (e.g., authentication with Cartesia API, speech recognition/synthesis).

- Backend:
- A Python Flask server acting as an API layer.
- Organized modules such as:
▪ Routes (e.g., chat_routes in the “routes” directory).
▪ Services (e.g., anthropic_service and response_service) that handle business logic and integration with AI models.
▪ Tools (custom LLM tools like tagore_tools for special features).

- Data Layer:
- Two SQLite databases: one for Tagore’s literary creations (located in tagore-data/tagore-data) and another for conversation storage (as hinted by file names in the data directory).

- External Services:
- Anthropic API for AI conversational responses.
- Cartesia API for voice synthesis (text-to-speech), plus Web Speech API (in the frontend) for speech recognition.

##### Relationships and Interactions

- The User Interface on the frontend sends chat messages (text or voice) via REST calls to the backend API.
- The backend processes the request:
- Routes in Flask capture the chat requests.
- Depending on the request, services call the Anthropic API (with a specialized system prompt) to generate Tagore-like responses.
- If needed, custom LLM tools are used to fetch or list specific works (like “list_works” or “get_work_content”).
- The backend communicates with the SQLite database(s):
- One database stores the literary content (for retrieving Tagore’s works).
- Another stores the conversation history to be used for persistent memory.
- The response is sent back to the frontend, where additional services may call the Cartesia API to generate speech from text and apply visual/audio feedback.

##### Architectural Patterns

- Client-Server Pattern: Clearly demarcates the responsibilities between the frontend (client) and backend (server).
- RESTful API Architecture: The backend uses REST endpoints (defined in routes) for communication.
- Separation of Concerns: Distinct folders for routes (API endpoints), services (business logic/communication with external APIs), and tools (custom operations on Tagore’s content).
- Data Flow: User inputs → Frontend → Backend (processing, API calls, DB access) → External Services → Backend response → Frontend display and voice synthesis.

##### Final Checklist
- Clear labels for every component and sub-component.
- That custom LLM tools and conversation memory (persistent storage) aspects are included since they are critical to how the system personalizes and tracks conversations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Node
    User["User (Browser)"]:::client

    %% Frontend Layer
    subgraph "Tagore-Frontend"
        FRONT["React + TypeScript App"]:::frontend
        subgraph "UI Components"
            ChatUI["Chat Components"]:::frontend
            Header["Header"]:::frontend
            ThemeToggle["Theme Toggle"]:::frontend
        end
        subgraph "Frontend Utilities"
            Hooks["Frontend Hooks"]:::frontend
            subgraph "Frontend Services"
                CartesiaAuth["Cartesia Auth Service"]:::frontend
                ChatService["Chat Service"]:::frontend
                SpeechRecognition["Speech Recognition"]:::frontend
                SpeechSynthesis["Speech Synthesis"]:::frontend
            end
        end
    end

    %% Backend Layer
    subgraph "Tagore-Backend"
        BackendServer["Flask Server (Backend)"]:::backend
        subgraph "API Routes"
            ChatRoutes["Chat API Endpoint"]:::backend
        end
        subgraph "Backend Business Logic"
            AnthropicService["Anthropic Service"]:::backend
            ResponseService["Response Service"]:::backend
        end
        subgraph "LLM Tools"
            TagoreTools["Tagore Tools"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        LiteraryWorksDB["Literary Works DB"]:::database
        ConversationsDB["Conversations DB"]:::database
    end

    %% External Services
    AnthropicAPI["Anthropic API"]:::external
    CartesiaAPI["Cartesia API"]:::external

    %% Data Flow Arrows
    User -->|"sendsChatMessage"| FRONT
    FRONT -->|"rendersUI"| ChatUI
    FRONT -->|"rendersUI"| Header
    FRONT -->|"rendersUI"| ThemeToggle
    FRONT -->|"usesHook"| Hooks
    FRONT -->|"invokesService"| ChatService
    ChatService -->|"sendChatRequest"| ChatRoutes
    ChatUI -->|"capturesInput"| ChatRoutes

    ChatRoutes -->|"processRequest"| AnthropicService
    ChatRoutes -->|"processRequest"| ResponseService
    ChatRoutes -->|"accessDB"| ConversationsDB
    ChatRoutes -->|"accessDB"| LiteraryWorksDB

    AnthropicService -->|"callForResponse"| AnthropicAPI
    ResponseService -->|"invokeTool"| TagoreTools
    TagoreTools -->|"fetchWorkDetails"| LiteraryWorksDB

    CartesiaAuth -->|"authRequest"| CartesiaAPI
    SpeechSynthesis -->|"synthesizeVoice"| CartesiaAPI
    SpeechRecognition -->|"captureVoice"| FRONT

    AnthropicService -->|"returnResponse"| ChatRoutes
    ResponseService -->|"returnResponse"| ChatRoutes
    ChatRoutes -->|"returnsResponse"| FRONT
    FRONT -->|"displayResponseAndSynthesize"| SpeechSynthesis

    %% Click Events (mapping components to file paths)
    click FRONT "https://github.com/abhiagni11/tagore-speaks/tree/main/tagore-frontend/"
    click ChatUI "https://github.com/abhiagni11/tagore-speaks/tree/main/tagore-frontend/src/components/Chat/"
    click Header "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/components/Header.tsx"
    click ThemeToggle "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/components/ThemeToggle.tsx"
    click Hooks "https://github.com/abhiagni11/tagore-speaks/tree/main/tagore-frontend/src/components/hooks/"
    click CartesiaAuth "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/services/cartesiaAuth.ts"
    click ChatService "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/services/chatService.ts"
    click SpeechRecognition "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/services/speechRecognition.ts"
    click SpeechSynthesis "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-frontend/src/services/speechSynthesis.ts"
    click BackendServer "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-backend/app.py"
    click ChatRoutes "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-backend/routes/chat_routes.py"
    click AnthropicService "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-backend/services/anthropic_service.py"
    click ResponseService "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-backend/services/response_service.py"
    click TagoreTools "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-backend/tools/tagore_tools.py"
    click LiteraryWorksDB "https://github.com/abhiagni11/tagore-speaks/blob/main/tagore-data/tagore-data/creations.db"

    %% Styles
    classDef client fill:#ffebcc,stroke:#d2691e,stroke-width:2px;
    classDef frontend fill:#d1e7dd,stroke:#0d6efd,stroke-width:2px;
    classDef backend fill:#cfe2ff,stroke:#6f42c1,stroke-width:2px;
    classDef database fill:#f8d7da,stroke:#dc3545,stroke-width:2px,stroke-dasharray:5 5;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px,stroke-dasharray:2 2;
```
