# sebampuero/simple_chatgpt_4 architecture

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

- Interactive diagram: https://gitdiagram.com/sebampuero/simple_chatgpt_4
- Repository: https://github.com/sebampuero/simple_chatgpt_4

## Overview

##### Main Components Identification
a. Frontend (React App):
- Located in the "react-app" directory.
- Contains all React components, styling files, and API communication logic (e.g., src/api/api.js).
- Manages UI elements such as ChatInput, ChatMessages, ChatPage, and ChatSidebar.
b. Backend:
- The entry point is main.py and server package.
- Contains HTTP routes, websocket (ws) handling, and various request handlers (e.g., chat, login, models).
c. Components (Business Logic and Services):
- Organized within the "components" directory.
- Divided into submodules for handling chat states, database connectivity (DynamoDB connectors), Elasticsearch operations, login (JWT management and actual login routines), and a repository layer for user management and data access.
- Includes abstraction for different LLMs in the "components/llm" folder.
d. Middleware:
- A separate module for handling authentication (located in middleware/authentication.py).
e. External Services and Integrations:
- DynamoDB for storing chat history and authorized users.
- Elasticsearch, which can be deployed via docker-compose (see included configuration).
- Google OAuth (via external configuration and environment variables).
- Cloud-based LLM APIs (OpenAI, Gemini, etc.).
f. Infrastructure & Deployment:
- Dockerfile, .dockerignore, docker-compose.yml – for containerization and orchestration.
- Environment configuration files (.env.dist and others) and setup scripts (setup.sh, add_authorized_email.sh, start_dev.sh, start_prd.sh).

##### Relationships and Interactions
- The React frontend communicates with the backend (through API calls and websockets), making requests to endpoints defined in the server package.
- The server routes requests to appropriate handlers (chat, login, models, ws) which in turn interact with the components.
- The authentication middleware intercepts requests to secure routes using JWT tokens.
- The LLM components call external APIs to generate responses and models encapsulate each LLM’s specifics.
- The database components handle both asynchronous and synchronous interactions with DynamoDB.
- When a search operation is done, the server will leverage the Elasticsearch component, connecting through the ElasticClient defined in components/elasticsearch.

##### Architectural Patterns and Design Principles
- The project follows a clear separation of concerns, with distinct layers:
- Presentation layer (React frontend).
- API/Controller layer (server handlers).
- Business/service layer (components) splitting functionalities for chat logic, database operations, authentication, and LLM integration.
- Uses modular design, making it easier to extend, test (note the components/tests folder), and maintain.
- Integration of external services is encapsulated behind specific connectors (e.g., DDBConnector for AWS DynamoDB, ElasticClient for Elasticsearch).

##### Technologies, Frameworks, and Libraries
- React (for frontend UI) with its ecosystem (including CSS, testing, and proxy configurations).
- Python for backend logic with server packages, middleware, and components.
- AWS DynamoDB (database connectivity configured through Python scripts and AWS CLI instructions in the README).
- Elasticsearch (for search capabilities, with a provided docker-compose example).
- Google OAuth for user authentication integrating with JWT for session management.
- Containerization (Dockerfile, docker-compose file) and configuration management (.env, setup scripts).

##### Elements
- "React Frontend" (with possible subdivisions for components and API layer)
- "Python Backend" leading to "API Endpoints" which further branch to handlers (chat, login, etc.)
- "Components" grouping Chat, Database, LLM, Login, Repository.
- "Middleware" for authentication.
- "External Services" including AWS DynamoDB, Elasticsearch, Google OAuth, and external LLM APIs.
- Frontend → Backend API (API calls and websockets)
- API → Business Components (invoking specific functionalities)
- Components → External Services (for database access, search queries, and LLM queries).
- Ovals or cloud symbols for external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F1["React Frontend"] 
        F6["API Communication"]
        subgraph "UI Components"
            F2["ChatInput"]
            F3["ChatMessages"]
            F4["ChatPage"]
            F5["ChatSidebar"]
        end
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["Backend Entry (main.py & server)"]
        subgraph "API Endpoints"
            B2["Chat Handler"]
            B3["Login Handler"]
            B4["Models Handler"]
            B5["WebSocket Handler"]
        end
        subgraph "Business Components"
            subgraph "Chat State Management"
                C1a["ChatState"]
                C1b["RedisState"]
            end
            subgraph "Database Connectivity"
                C2a["DDBConnector"]
                C2b["DDBConnectorSync"]
            end
            C3["Elasticsearch Operations"]
            C4["LLM Integration"]
            subgraph "Login Management & JWT"
                C5a["Login"]
                C5b["JWT Manager"]
            end
            subgraph "Repository & Data Access"
                C6a["Repository"]
                C6b["DDBRepository"]
                C6c["User Data Model"]
            end
        end
        B6["Authentication Middleware"]
    end

    %% External Services
    subgraph "External Services"
        S1["AWS DynamoDB"]
        S2["Elasticsearch Service"]
        S3["Google OAuth"]
        S4["Cloud LLM APIs"]
    end

    %% Deployment & Configuration
    subgraph "Deployment & Configuration"
        D1["Docker & Deployment Files"]
    end

    %% Connections between Frontend and Backend
    F1 -->|"API/WebSocket calls"| B1

    %% Connections within Backend: Entry to API Endpoints
    B1 --> B2
    B1 --> B3
    B1 --> B4
    B1 --> B5

    %% API Endpoints routing to Business Components and Middleware
    B2 -->|"Processes chat"| C1a
    B2 --> C2a
    B2 --> C4

    B3 -->|"Handles login"| C5a
    B3 --> B6

    B4 -->|"Model interactions"| C4

    B5 -->|"Real-time chat updates"| C1b

    %% External service interactions from Business Components
    C2a -->|"Reads/Writes data"| S1
    C2b --> S1
    C3 -->|"Performs search queries"| S2
    C4 -->|"Calls external APIs"| S4
    C5a -->|"Validates via"| S3
    C5b --> S3
    B6 -->|"Checks tokens"| S3

    %% Deployment connection (indicative)
    B1 --- D1
    F1 --- D1

    %% Styling
    classDef frontend fill:#f9e79f,stroke:#e67e22,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef service fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef infra fill:#fadbd8,stroke:#e74c3c,stroke-width:2px;

    class F1,F2,F3,F4,F5,F6 frontend;
    class B1,B2,B3,B4,B5,B6,C1a,C1b,C2a,C2b,C3,C4,C5a,C5b,C6a,C6b,C6c backend;
    class S1,S2,S3,S4 service;
    class D1 infra;

    %% Click Events for Frontend Components
    click F1 "https://github.com/sebampuero/simple_chatgpt_4/tree/main/react-app/"
    click F6 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/react-app/src/api/api.js"
    click F2 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/react-app/src/components/ChatInput.js"
    click F3 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/react-app/src/components/ChatMessages.js"
    click F4 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/react-app/src/components/ChatPage.js"
    click F5 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/react-app/src/components/ChatSidebar.js"

    %% Click Events for Backend Components
    click B1 "https://github.com/sebampuero/simple_chatgpt_4/tree/main/server/"
    click B2 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/server/handlers/chat.py"
    click B3 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/server/handlers/login.py"
    click B4 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/server/handlers/models.py"
    click B5 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/server/handlers/ws.py"

    %% Click Events for Business Components - Chat State Management
    click C1a "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/chat/ChatState.py"
    click C1b "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/chat/RedisState.py"

    %% Click Events for Business Components - Database Connectivity
    click C2a "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/database/DDBConnector.py"
    click C2b "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/database/DDBConnectorSync.py"

    %% Click Event for Elasticsearch Operations
    click C3 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/elasticsearch/ElasticClient.py"

    %% Click Event for LLM Integration
    click C4 "https://github.com/sebampuero/simple_chatgpt_4/tree/main/components/llm/"

    %% Click Events for Login Management & JWT
    click C5a "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/login/Login.py"
    click C5b "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/login/JWTManager.py"

    %% Click Events for Repository & Data Access
    click C6a "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/repository/Repository.py"
    click C6b "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/repository/DDBRepository.py"
    click C6c "https://github.com/sebampuero/simple_chatgpt_4/blob/main/components/repository/User.py"

    %% Click Event for Middleware
    click B6 "https://github.com/sebampuero/simple_chatgpt_4/blob/main/middleware/authentication.py"
```
