# conj43/titanbot architecture

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

## Overview

##### Main Components
a. User Interface: The Streamlit UI is started via main.py and is likely managed in ui.py. This is where users upload their databases and enter their natural language queries.
b. Core Engine: The heart of the application is located in main.py, which orchestrates the flow between receiving user input, processing queries, and invoking the OpenAI API.
c. Prompt and Conversation Management: The file prompts.py is likely in charge of constructing the prompts or conversation context that is sent to the OpenAI API.
d. Dynamic Code Execution: The sandbox.py module implies a contained environment for generating and executing dynamic Python code, which supports real-time data analysis.
e. Utility and Helper Modules: Tools (tools.py) and utils (utils.py) provide additional support functions and abstractions used throughout the project.
f. External Integrations:
- OpenAI API: For processing natural language queries and generating responses.
- Transportation Database: The application supports SQLite databases, CSV files (converted to temporary SQLite databases), and API data sources.
- Docker: Used for ensuring that any necessary containerized environments (perhaps for the database) are available and running.

##### Understand the Relationships and Interactions
- The User Interface (UI via Streamlit) handles user interactions and query inputs. Once a query is submitted, main.py acts as the coordinator.
- main.py leverages prompts.py to construct a proper request for ChatGPT and then sends it to the OpenAI API.
- Depending on the user’s request (which might involve data retrieval or transformation), dynamic Python code may be generated and executed using sandbox.py.
- Helper modules (tools.py and utils.py) support operations like formatting, logging, and complex data manipulations.
- Data retrieval workflows bridge the UI actions with the underlying transportation database, respecting the read-only operations and safely transforming CSV/API data to temporary SQLite databases.
- Docker is assumed to be running in the background, ensuring that container-based dependencies or environments (if needed) are operational.

##### Recognize the Architectural Patterns and Design Principles
- Separation of Concerns: The project has cleanly separated modules for UI, prompt management, dynamic execution, and utilities, making it easier to understand and extend.
- Modular and Extensible: With distinct files handling specific aspects (UI, prompts, sandboxing, etc.), the architecture is modular, allowing for future enhancements.
- External Service Integration: The design manages external communications – with the OpenAI API and a containerized environment (via Docker) – using clear interfaces.

- Incorporate an “External Services” section that includes:
- OpenAI API
- Transportation Database (with possible sub-labels indicating SQLite, CSV conversion, or API endpoints)
- Docker (illustrated as an infrastructural/operational dependency)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        A["User"]:::external
        B["Streamlit UI (ui.py)"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        C["Core Engine (main.py)"]:::core
        D["Prompt Manager (prompts.py)"]:::core
        E["Dynamic Executor (sandbox.py)"]:::core
        F["Helper Module (tools.py)"]:::core
        G["Helper Module (utils.py)"]:::core
    end

    %% External Services Layer
    subgraph "External Services"
        H["OpenAI API"]:::external
        I["Transportation Database\n[SQLite, CSV/API]"]:::external
        J["Docker"]:::external
    end

    %% Data Flow Connections
    A -->|"submits_query"| B
    B -->|"triggers"| C
    C -->|"builds_prompt"| D
    C -->|"executes_code"| E
    C -->|"uses_helpers"| F
    C -->|"uses_helpers"| G
    C -->|"calls"| H
    C -->|"retrieves_data"| I
    C -->|"ensures_env"| J

    %% Click Events for Component Mapping
    click B "https://github.com/conj43/titanbot/blob/main/TitanBot Code/ui.py"
    click C "https://github.com/conj43/titanbot/blob/main/TitanBot Code/main.py"
    click D "https://github.com/conj43/titanbot/blob/main/TitanBot Code/prompts.py"
    click E "https://github.com/conj43/titanbot/blob/main/TitanBot Code/sandbox.py"
    click F "https://github.com/conj43/titanbot/blob/main/TitanBot Code/tools.py"
    click G "https://github.com/conj43/titanbot/blob/main/TitanBot Code/utils.py"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
```
