# goldirana/bounce2 architecture

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

## Overview

##### Project Type and Purpose
- The README clarifies that this is a RAG system where a web interface (Streamlit) is used for querying documents and then generating responses by retrieving and processing relevant document content.
- The project is structured as a full-stack application with clearly divided responsibilities: a backend API (FastAPI), a separate server module handling services and API routes, and a frontend for user interaction.
- The system also involves document processing using various extractors (text/image summarizers), storage strategies (Chroma, Firebase, or Pinecone), and prompt management for LLM responses.

##### Analyzing the File Structure
- Top-level files: Files like app.py, Makefile, config.yaml, credentials (Firebase credentials provided), and README provide overall project configuration.
- Backend Folder:
- Contains its own “main.py”, notebooks for testing and experimentation, and a “src” folder which further segments core modules:
- config: Manages configuration settings.
- constants and entity: Likely used for defining application-specific data models and constants.
- extractors: Houses code for data ingestion and summarization (both text and image).
- prompts: Contains JSON definitions for various prompts, suggesting a modular approach to creating context-specific queries.
- queries: Implements the handling of queries coming from the frontend.
- storage: Manages different storage backends (Chroma, Firebase, Pinecone) for vector embeddings.
- unit_testing and utils: For testing and common utilities.
- Server Folder:
- Contains the FastAPI app (server/main.py) and several service modules like chroma_service, cosine_score, prompt_service, query_service, rag_service, and vb_service which correspond to different parts of the RAG pipeline.
- The api_routes and dependencies organize how different parts of the system interact via API requests.
- Frontend Folder:
- Implements the UI using Streamlit (frontend/main.py and pages like query.py and about_me.py) and includes components for building the interactive interface.
- The Procfile and logger module show preparation for deployment.
- Additional deployment scripts/files: Dockerfile.ignore, supervisord.conf, and Render deployment instructions indicate containerized and managed deployment options.

##### Main Components
a. Frontend (Streamlit):
- It as the user interface layer.
- Components/pages (e.g., “query”, “about me”, “contact”) that interact with backend endpoints.
- That it is deployed as a separate web service (with its own Procfile/streamlit starter command).

b. API Gateway / Backend (FastAPI):
- Inside or connected to the backend, mark the “server” and “backend” modules.
- Role of “api_routes”, “dependencies”, and various service modules (e.g., chroma_service, prompt_service, query_service, rag_service) that implement the core RAG functionality.

c. Data Processing Modules:
- Within the backend, indicate the “extractors” (data_ingestion, text_summarizer, image_summarizer) that process and prepare data.
- “prompts” module that holds the JSON configurations guiding the response generation.
- “queries” and “llm_models” modules which tie the extraction and prompt generation to the final answer.

d. Storage and External Services:
- Multiple storage options used by the system (Chroma, Firebase, Pinecone) as separate components.
- “credentials” for Firebase, and indicate that environmental variables (e.g., OPENAI_API_KEY) play a role in accessing external APIs.
- Optionally, include external LLM services (such as those provided by OpenAI) as a separate component that the backend communicates with to generate responses.

e. Auxiliary Components:
- Testing and notebooks: Although not part of the production system, include a note about “backend/notebooks” and “unit_testing” which are used for learning and validating the system.
- Deployment container: Represent Docker and Render deployments (with separate build and start commands for the backend and frontend).

##### Relationships and Data Flow
- Within the backend, indicate internal calls between:
- Data extraction modules (extractors) and query handlers.
- Utilization of storage services, where data is fetched/stored.
- Communication with external services (like OpenAI’s API) passing prompts from the “prompts” module.
- How responses are generated via the hypothesized chain of query handling, retrieval, and generation, culminating in the result that flows back to the frontend.

##### Architectural Patterns and Technologies
- That the project employs a modular design with separation of concerns (frontend vs. backend, extraction vs. storage vs. service logic).
- A service-oriented approach (each service module like rag_service or chroma_service is a distinct element).
- Clear data flow pathways (from user query to processing modules and back to response).
- References to key technologies:
- FastAPI for backend REST service.
- Streamlit for the frontend UI.
- Python 3.9 and dependencies as listed in requirements.txt.
- Containerization with Docker and managed deployment via Render.
- Integration with external APIs (OpenAI) and storage systems (Chroma, Firebase, Pinecone).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Frontend (Streamlit UI)"
        FS1["Main UI"]:::frontend
        FS2["Pages"]:::frontend
    end

    %% API Gateway / Backend Layer
    subgraph "API Gateway/Backend (FastAPI)"
        API["API Gateway"]:::backend
        AR["API Routes"]:::backend
        AD["Dependencies"]:::backend
    end

    %% Backend Business Logic
    subgraph "Backend Business Logic"
        BP1["Core Processing & Query Handling"]:::backend
        BP2["LLM Models"]:::backend
        BP3["Configuration & Constants"]:::backend
    end

    %% Data Extraction Modules
    subgraph "Data Extraction"
        DE1["Data Ingestion"]:::processing
        DE2["Text Summarizer"]:::processing
        DE3["Image Summarizer"]:::processing
    end

    %% Prompt Management
    PM["Prompt Management"]:::processing

    %% Storage Services
    subgraph "Storage Services"
        ST1["Chroma Storage"]:::datastore
        ST2["Firebase Storage"]:::datastore
        ST3["Pinecone Storage"]:::datastore
        FC["Firebase Credentials"]:::datastore
    end

    %% RAG Pipeline Service Modules
    subgraph "RAG Pipeline Services"
        RS1["Chroma Service"]:::service
        RS2["Prompt Service"]:::service
        RS3["Query Service"]:::service
        RS4["RAG Service"]:::service
        RS5["Cosine Score"]:::service
        RS6["VB Service"]:::service
    end

    %% External API Service
    EX["OpenAI API"]:::external

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        AUX1["Notebooks"]:::auxiliary
        AUX2["Unit Testing"]:::auxiliary
        DEP["Deployment & Logging"]:::auxiliary
    end

    %% Relationships and Data Flow
    User["User"]:::user
    User -->|"initiates"| FS1
    FS1 -->|"navigates"| FS2
    FS2 -->|"sends query to"| API
    API -->|"routes request via"| AR
    API -->|"loads dependencies via"| AD
    AR -->|"calls"| BP1
    BP1 -->|"invokes"| DE1
    BP1 -->|"invokes"| DE2
    BP1 -->|"invokes"| DE3
    BP1 -->|"fetches prompts from"| PM
    BP1 -->|"reads config from"| BP3
    BP1 -->|"uses storage"| ST1
    BP1 -->|"uses storage"| ST2
    BP1 -->|"uses storage"| ST3
    ST2 -->|"secured by"| FC
    BP1 -->|"delegates to"| RS1
    BP1 -->|"delegates to"| RS2
    BP1 -->|"delegates to"| RS3
    BP1 -->|"delegates to"| RS4
    BP1 -->|"computes via"| RS5
    BP1 -->|"computes via"| RS6
    RS4 -->|"queries"| EX
    EX -->|"returns response to"| RS4
    RS4 -->|"sends result to"| BP1
    BP1 -->|"returns response to"| API
    API -->|"sends response to"| FS1
    FS1 -->|"displays result to"| User

    %% Click Events
    click FS1 "https://github.com/goldirana/bounce2/blob/main/frontend/main.py"
    click FS2 "https://github.com/goldirana/bounce2/tree/main/frontend/pages/"
    click API "https://github.com/goldirana/bounce2/blob/main/server/main.py"
    click AR "https://github.com/goldirana/bounce2/blob/main/server/api_routes.py"
    click AD "https://github.com/goldirana/bounce2/blob/main/server/dependencies.py"
    click BP1 "https://github.com/goldirana/bounce2/blob/main/backend/main.py"
    click BP1 "https://github.com/goldirana/bounce2/blob/main/backend/src/queries/handler.py"
    click BP2 "https://github.com/goldirana/bounce2/blob/main/backend/src/llm_models.py"
    click BP3 "https://github.com/goldirana/bounce2/blob/main/backend/src/config/configuration.py"
    click BP3 "https://github.com/goldirana/bounce2/tree/main/backend/src/constants/"
    click DE1 "https://github.com/goldirana/bounce2/blob/main/backend/src/extractors/data_ingestion.py"
    click DE2 "https://github.com/goldirana/bounce2/blob/main/backend/src/extractors/text_summarizer.py"
    click DE3 "https://github.com/goldirana/bounce2/blob/main/backend/src/extractors/image_summarizer.py"
    click PM "https://github.com/goldirana/bounce2/tree/main/backend/src/prompts/"
    click ST1 "https://github.com/goldirana/bounce2/blob/main/backend/src/storage/chroma_storage.py"
    click ST2 "https://github.com/goldirana/bounce2/blob/main/backend/src/storage/firebase_storage.py"
    click ST3 "https://github.com/goldirana/bounce2/blob/main/backend/src/storage/pinecone_storage.py"
    click FC "https://github.com/goldirana/bounce2/blob/main/credentials/firebase_credentials.json"
    click RS1 "https://github.com/goldirana/bounce2/blob/main/server/services/chroma_service.py"
    click RS2 "https://github.com/goldirana/bounce2/blob/main/server/services/prompt_service.py"
    click RS3 "https://github.com/goldirana/bounce2/blob/main/server/services/query_service.py"
    click RS4 "https://github.com/goldirana/bounce2/blob/main/server/services/rag_service.py"
    click RS5 "https://github.com/goldirana/bounce2/blob/main/server/services/cosine_score.py"
    click RS6 "https://github.com/goldirana/bounce2/blob/main/server/services/vb_service.py"
    click AUX1 "https://github.com/goldirana/bounce2/tree/main/backend/notebooks/"
    click AUX2 "https://github.com/goldirana/bounce2/tree/main/backend/src/unit_testing/"
    click DEP "https://github.com/goldirana/bounce2/blob/main/Dockerfile.ignore"

    %% Styles
    classDef frontend fill:#a2d9ce,stroke:#1e8449,stroke-width:2px;
    classDef backend fill:#f9e79f,stroke:#b9770e,stroke-width:2px;
    classDef processing fill:#fad7a0,stroke:#e67e22,stroke-width:2px;
    classDef datastore fill:#e8daef,stroke:#8e44ad,stroke-width:2px;
    classDef service fill:#d6eaf8,stroke:#3498db,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef auxiliary fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef user fill:#fcf3cf,stroke:#f39c12,stroke-width:2px;
```
