# hiraddlz/ai-alchemy architecture

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

## Overview

##### Project Type and Purpose
- AI Alchemy is a free, open-source multi-tool AI application built in Python. Its purpose is to offer a collection of modular AI-powered tools (e.g., summarizing text, translating, proofreading, converting images to ASCII, etc.) via a user-friendly Streamlit interface.
- The README underscores its modular design, ease of deployment, and the use of separate modules for various tools.

##### Analyzing the File Structure
- Top-level directories and files give clues to the architecture:
- .devcontainer & .github: Indicate containerized development environment and CI/CD automation respectively.
- assets: Contains CSS files (cards.css, styles.css), which are used for customizing the UI and presentation.
- requirements.txt & packages.txt: List external dependencies and packages required.
- src: Contains the core of the application.
- AI_Alchemy.py: Likely acts as the main entry point that starts the Streamlit application.
- pages: This directory contains individual modules for each tool (e.g., Chatbot, Summarizer, Translator, etc.). Each module corresponds to a feature or page rendered by the UI.
- tools: Contains shared utility modules (e.g., image_utils.py, llm_utils.py, utils.py) which provide underlying functionalities used by the various pages.
- The structure reveals a clear separation between UI (entry point and pages) and underlying tool logic (in tools).

##### Insights from the README
- The README explains how each tool is modular, easily manageable, and how Streamlit is used to provide the user interface.
- It emphasizes deployment instructions, indicating the use of environment variables (e.g., OpenAI_API_KEY) and a straightforward deployment path (Streamlit Cloud or similar platforms).
- The tool checklist in the README provides an overview of which pages are fully developed and which may be under development.

##### Final Remarks
- Be detailed in capturing the roles of all major components and how they connect to each other.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    UI["Streamlit UI (AI_Alchemy.py)"]:::ui

    %% Pages (src/pages)
    subgraph "Pages (src/pages)"
        PA["Ascii_Artist"]:::page
        PB["Chatbot"]:::page
        PC["Summarizer"]:::page
        PD["Translator"]:::page
    end

    %% Utility Modules (src/tools)
    subgraph "Utility Modules (src/tools)"
        U1["image_utils.py"]:::util
        U2["llm_utils.py"]:::util
        U3["utils.py"]:::util
    end

    %% Assets and Styling
    Assets["Assets (CSS)"]:::asset

    %% DevOps and Deployment
    subgraph "DevOps/Deployment"
        DevCont[".devcontainer (devcontainer.json)"]:::devops
        DevCICD["CI/CD (ci-cd.yml)"]:::devops
    end

    %% Dependency Management
    subgraph "Dependencies"
        DepReq["requirements.txt"]:::dep
        DepPkg["packages.txt"]:::dep
    end

    %% External API
    ExternalAPI["External API (OpenAI)"]:::external

    %% Relationships
    UI -->|"routes"| PA
    UI -->|"routes"| PB
    UI -->|"routes"| PC
    UI -->|"routes"| PD

    UI -->|"applies"| Assets

    PA -->|"calls"| U1
    PB -->|"calls"| U2
    PC -->|"calls"| U2
    PD -->|"calls"| U3

    U2 -->|"APIcall"| ExternalAPI

    UI -.->|"requires"| DepReq
    UI -.->|"requires"| DepPkg
    U1 -.->|"requires"| DepReq
    U1 -.->|"requires"| DepPkg

    DevCICD -.->|"deploys"| UI
    DevCont -.->|"environments"| UI

    %% Click Events
    click UI "https://github.com/hiraddlz/ai-alchemy/blob/master/src/AI_Alchemy.py"
    click PA "https://github.com/hiraddlz/ai-alchemy/blob/master/src/pages/Ascii_Artist.py"
    click PB "https://github.com/hiraddlz/ai-alchemy/blob/master/src/pages/Chatbot.py"
    click PC "https://github.com/hiraddlz/ai-alchemy/blob/master/src/pages/Summarizer.py"
    click PD "https://github.com/hiraddlz/ai-alchemy/blob/master/src/pages/Translator.py"
    click U1 "https://github.com/hiraddlz/ai-alchemy/blob/master/src/tools/image_utils.py"
    click U2 "https://github.com/hiraddlz/ai-alchemy/blob/master/src/tools/llm_utils.py"
    click U3 "https://github.com/hiraddlz/ai-alchemy/blob/master/src/tools/utils.py"
    click Assets "https://github.com/hiraddlz/ai-alchemy/tree/master/assets/css"
    click DevCont "https://github.com/hiraddlz/ai-alchemy/blob/master/.devcontainer/devcontainer.json"
    click DevCICD "https://github.com/hiraddlz/ai-alchemy/blob/master/.github/workflows/ci-cd.yml"
    click DepReq "https://github.com/hiraddlz/ai-alchemy/blob/master/requirements.txt"
    click DepPkg "https://github.com/hiraddlz/ai-alchemy/blob/master/packages.txt"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#1f6fb2,color:#1f3a93,stroke-width:2px;
    classDef page fill:#d4edda,stroke:#28a745,color:#155724,stroke-width:2px;
    classDef util fill:#f8d7da,stroke:#dc3545,color:#721c24,stroke-width:2px;
    classDef asset fill:#fff3cd,stroke:#ffc107,color:#856404,stroke-width:2px;
    classDef devops fill:#e2e3e5,stroke:#6c757d,color:#383d41,stroke-width:2px;
    classDef dep fill:#d1ecf1,stroke:#0c5460,color:#0c5460,stroke-width:2px;
    classDef external fill:#f5f5f5,stroke:#ced4da,color:#6c757d,stroke-width:2px;
```
