# ahsan7162/ai-communication-coach architecture

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

- Interactive diagram: https://gitdiagram.com/ahsan7162/ai-communication-coach
- Repository: https://github.com/ahsan7162/ai-communication-coach

## Overview

##### Main Components
- Frontend: Built with React.js. Key elements include the main application (App.tsx), separate pages for chat, login, and signup, and associated styles, configurations, and service calls (e.g., authApis.ts and chatApi.ts).
- Backend: Built with FastAPI in Python. It is organized into distinct directories:
– Routes: Contains API endpoints for chat, login, signup, home, and fetching LLM responses.
– Services: Contains the business logic for interfacing with Gemini (get_ai_coach_reply, llm integration, context extraction).
– Models: Contains data models and schemas (e.g., chat messages, login requests, token data) that are used with SQLAlchemy and SQLite.
– Database: Includes SQLite database files and setup scripts (db_setup.py, get_db.py) to configure and manage persistence.
– Prompts: Contains Gemini-specific prompts that tailor the AI coaching behavior.
– Helpers: Provides utility functions such as extracting user data from JWT tokens.
- Database: A SQLite database (aicoach.db) utilized by the backend for storing user data, chat logs, etc.
- External Service Integration: Gemini LLM is used to generate responses and coaching prompts—this integration is woven into the services layer.

##### Relationships and Data Flow
- User interactions occur at the Frontend where the React app captures actions (login, signup, chat messages).
- Frontend then communicates with the Backend using API calls defined in the routes.
- The Backend routes invoke services that use the LLM (Gemini) and access the SQLite database via the models and helper methods.
- Business logic in the services determines the AI responses and processes the data based on prompt templates.
- Data is stored and retrieved from the SQLite database using SQLAlchemy through model definitions within the backend.
- Response data flows back to the Frontend, which then displays the AI communication coaching output to the user.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project neatly separates API endpoints (routes), business logic (services), data persistence (models and database), and AI prompt handling (prompts).
- Layered Architecture: Each layer (frontend, API, database, integration with Gemini) is clearly defined.
- Consistent Naming and Module Organization: Directories such as “models”, “routes”, “services”, and “helpers” indicate a modular approach to design.
- Clear API Contract: The use of specific request and response models in the models directory ensures that the API is well-documented and standardized.

##### Key Elements
- Dependency relationships:
– Indicate that the backend’s “routes” depend on “models” and “services” to process requests.
– Show the connection between “database” setup and ORM models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend"
        F1["React App"]:::frontend
        F2["Chat Page.tsx"]:::frontend
        F2css["Chat Page.css"]:::frontend
        F3["Login Page.tsx"]:::frontend
        F3css["Login Page.css"]:::frontend
        F4["Signup Page.tsx"]:::frontend
        F4css["Signup Page.css"]:::frontend
        F5["Auth APIs"]:::frontend
        F6["Chat APIs"]:::frontend
        F7["API Config"]:::frontend
    end

    subgraph "Backend"
        subgraph "Routes"
            R1["chat.py"]:::backend
            R2["get_llm_response.py"]:::backend
            R3["home.py"]:::backend
            R4["login.py"]:::backend
            R5["signup.py"]:::backend
        end

        subgraph "Services"
            S1["get_ai_coach_reply.py"]:::backend
            S2["get_context_from_message.py"]:::backend
            S3["llm.py"]:::backend
        end

        subgraph "Models"
            M1["chat_message.py"]:::backend
            M2["chat_response.py"]:::backend
            M3["create_chat.py"]:::backend
            M4["create_message.py"]:::backend
            M5["enums.py"]:::backend
            M6["login_request.py"]:::backend
            M7["message_response.py"]:::backend
            M8["profile_update.py"]:::backend
            M9["signup_request.py"]:::backend
            M10["token_data.py"]:::backend
            M11["user_response.py"]:::backend
        end

        subgraph "Database Setup"
            D1["db_setup.py"]:::database
            D2["get_db.py"]:::database
            D3["SQLite DB"]:::database
            D4["SQLite DB (aux)"]:::database
        end

        subgraph "Prompts"
            P1["coach_prompt.py"]:::backend
            P2["get_profile_from_message_prompt.py"]:::backend
        end

        subgraph "Helpers"
            H1["get_user_from_jwt.py"]:::backend
        end

        subgraph "Gemini Integration"
            G1["Gemini LLM"]:::gemini
        end
    end

    %% Data Flow Connections
    F1 -->|"loads"| F2
    F1 -->|"loads"| F3
    F1 -->|"loads"| F4
    F2 -->|"calls"| F5
    F2 -->|"calls"| F6
    F3 -->|"calls"| F5
    F4 -->|"calls"| F5

    F5 -->|"APIrequest"| R1
    F5 -->|"APIrequest"| R2
    F5 -->|"APIrequest"| R3
    F5 -->|"APIrequest"| R4
    F5 -->|"APIrequest"| R5
    F6 -->|"APIrequest"| R1
    F6 -->|"APIrequest"| R2

    R1 -->|"processesWith"| S1
    R2 -->|"processesWith"| S3
    R3 -->|"processesWith"| S1
    R4 -->|"processesWith"| S1
    R5 -->|"processesWith"| S1

    S1 -->|"callsLogic"| S2
    S3 -->|"callsLogic"| S2
    S1 -->|"queries"| M1
    S1 -->|"queries"| M2
    S1 -->|"queries"| M3
    S1 -->|"queries"| M4
    S1 -->|"uses"| P1
    S2 -->|"uses"| H1
    S3 -->|"callsExternal"| G1

    M1 -->|"storesData"| D3
    M2 -->|"storesData"| D3
    M3 -->|"storesData"| D3
    M4 -->|"storesData"| D3
    M5 -->|"storesData"| D3
    M6 -->|"storesData"| D3
    M7 -->|"storesData"| D3
    M8 -->|"storesData"| D3
    M9 -->|"storesData"| D3
    M10 -->|"storesData"| D3
    M11 -->|"storesData"| D3
    D1 --> D3
    D2 --> D3

    R1 -->|"response"| F1
    R2 -->|"response"| F1
    R3 -->|"response"| F1
    R4 -->|"response"| F1
    R5 -->|"response"| F1

    %% Additional internal dependencies
    R1 --> S1
    R2 --> S3
    R4 --> S1
    R5 --> S1
    S1 --> P1
    S1 --> H1
    S3 --> G1

    %% Click Events for Frontend
    click F1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/App.tsx"
    click F2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/chat/index.tsx"
    click F2css "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/chat/index.css"
    click F3 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/login/index.tsx"
    click F3css "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/login/index.css"
    click F4 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/signup/index.tsx"
    click F4css "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/pages/signup/index.css"
    click F5 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/services/authApis.ts"
    click F6 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/services/chatApi.ts"
    click F7 "https://github.com/ahsan7162/ai-communication-coach/blob/main/frontend/src/config/api-service.ts"

    %% Click Events for Backend - Routes
    click R1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/routes/chat.py"
    click R2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/routes/get_llm_response.py"
    click R3 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/routes/home.py"
    click R4 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/routes/login.py"
    click R5 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/routes/signup.py"

    %% Click Events for Backend - Services
    click S1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/services/get_ai_coach_reply.py"
    click S2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/services/get_context_from_message.py"
    click S3 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/services/llm.py"

    %% Click Events for Backend - Models
    click M1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/chat_message.py"
    click M2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/chat_response.py"
    click M3 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/create_chat.py"
    click M4 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/create_message.py"
    click M5 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/enums.py"
    click M6 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/login_request.py"
    click M7 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/message_response.py"
    click M8 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/profile_update.py"
    click M9 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/signup_request.py"
    click M10 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/token_data.py"
    click M11 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/models/user_response.py"

    %% Click Events for Backend - Database Setup
    click D1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/database/db_setup.py"
    click D2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/database/get_db.py"
    click D3 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/aicoach.db"
    click D4 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/database/aicoach.db"

    %% Click Events for Backend - Prompts
    click P1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/prompts/coach_prompt.py"
    click P2 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/prompts/get_profile_from_message_prompt.py"

    %% Click Events for Backend - Helpers
    click H1 "https://github.com/ahsan7162/ai-communication-coach/blob/main/backend/helpers/get_user_from_jwt.py"

    classDef frontend fill:#cce5ff,stroke:#0056b3,stroke-width:2px;
    classDef backend fill:#d4f8d4,stroke:#2e8b57,stroke-width:2px;
    classDef database fill:#ffe6cc,stroke:#ff8c1a,stroke-width:2px;
    classDef gemini fill:#ffe6f7,stroke:#ff66b3,stroke-width:2px;
```
