# weeehung/learnai-bandicota architecture

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

## Overview

##### Project Type & Purpose
- This is a full-stack web application built with Python and Streamlit.
- Its primary purpose is to detect scam indicators in text and to generate educational content (e.g., quiz questions) that help users learn about scam prevention.
- The application achieves this by integrating a front-end UI built in Streamlit with back-end modules that handle LLM-based text analysis and generation.

##### File Structure
- Key top-level files include:
- app.py – the main entry point that runs the Streamlit web application.
- requirements.txt – lists all dependencies such as Streamlit and OpenAI libraries.
- README.md – provides documentation and an overview of features.
- Top-level directories:
- component/ – holds modules that implement the webapp’s core features:
- homefeature.py: Introduces the scam awareness concepts.
- mainfeature.py: Implements the scam detection UI and integrates with the LLM’s scam analysis functions.
- subfeature1.py: Implements the scam education feature (generates questions/extracts) using LLM text generation.
- llm/ – encapsulates helper functions for OpenAI API interactions:
- scamanalyzer.py: Contains logic for text parsing and scam indicator analysis.
- textgenerator.py: Contains logic for generating educational text (questions etc.).
- client.py: Implements the OpenAI API client for making external API calls.

- User Interface (UI) Layer:
- Represented by app.py, which is the main Streamlit entry script.
- Feature Components:
- Introduction/Education Component: Represented by homefeature.py.
- LLM Processing Layer:
- Scamanalyzer module (llm/scamanalyzer.py) – handles parsing and analyzing text.
- Textgenerator module (llm/textgenerator.py) – handles generating quiz questions and educational content.
- OpenAI API Client (llm/client.py) – acts as the intermediate responsible for outbound calls to the external OpenAI service.
- External Services:
- OpenAI API – the cloud-based service that processes the LLM requests.
- Configuration / Secrets:
- Secrets file (e.g., .streamlit/secrets.toml) should be noted as providing sensitive API keys used in API calls (though not part of the primary file tree, it’s evident from the README).

b. Relationships and Interactions:
- The UI Layer (app.py) collects user input and directs it to the appropriate component:
- When a user enters text for scam detection, the data flows from app.py to mainfeature.py.
- For scam education, app.py directs the action to subfeature1.py.
- Each component then invokes the corresponding functionality:
- mainfeature.py calls the scamanalyzer module to analyze the text.
- subfeature1.py calls the textgenerator module to generate educational content.
- Both scamanalyzer.py and textgenerator.py use the OpenAI API Client (client.py) for sending requests and receiving responses from the external OpenAI API.

c. Architectural Patterns & Design Principles:
- Separation of Concerns: The design cleanly separates UI from business logic (feature components) and external service interactions (LLM modules).
- Modularity: Each component (scam detection, scam education, and LLM interactions) is encapsulated in its own module, promoting maintainability and testability.
- Extensibility: The clear division means new features (more scam-related features) can be added easily without major architectural overhauls.

d. Relevant Technologies and Frameworks:
- Python: Core programming language.
- Streamlit: Framework for building the webapp UI.
- OpenAI: External LLM API for analysis and text generation.
- File-based configuration (e.g., secrets management via .toml files) for secure API key handling.

- From UI to feature components.
- From feature components to the LLM processing modules.
- From LLM modules to the external OpenAI API and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    U["User"]:::external

    %% UI Layer
    UI["Streamlit UI (app.py)"]:::ui

    %% Feature Components
    A["Scam Awareness/Introduction Component (homefeature.py)"]:::feature
    D["Scam Detection Feature (mainfeature.py)"]:::feature
    E["Scam Education Feature (subfeature1.py)"]:::feature

    %% LLM Processing Layer
    SA["Scam Analyzer Module (llm/scamanalyzer.py)"]:::llm
    TG["Text Generator Module (llm/textgenerator.py)"]:::llm
    AC["OpenAI API Client (llm/client.py)"]:::llm

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

    %% Data Flow
    U -->|"initiates"| UI
    UI -->|"triggers"| A
    UI -->|"triggers"| D
    UI -->|"triggers"| E
    D -->|"analyzes"| SA
    SA -->|"calls"| AC
    E -->|"generates"| TG
    TG -->|"calls"| AC
    AC -->|"queries"| OAPI

    %% Click Events
    click UI "https://github.com/weeehung/learnai-bandicota/blob/main/app.py"
    click A "https://github.com/weeehung/learnai-bandicota/blob/main/component/homefeature.py"
    click D "https://github.com/weeehung/learnai-bandicota/blob/main/component/mainfeature.py"
    click E "https://github.com/weeehung/learnai-bandicota/blob/main/component/subfeature1.py"
    click SA "https://github.com/weeehung/learnai-bandicota/blob/main/llm/scamanalyzer.py"
    click TG "https://github.com/weeehung/learnai-bandicota/blob/main/llm/textgenerator.py"
    click AC "https://github.com/weeehung/learnai-bandicota/blob/main/llm/client.py"

    %% Styles
    classDef ui fill:#a1cfff,stroke:#333,stroke-width:2px;
    classDef feature fill:#c3f7c0,stroke:#333,stroke-width:2px;
    classDef llm fill:#fff7c0,stroke:#333,stroke-width:2px;
    classDef external fill:#ffdee0,stroke:#333,stroke-width:2px;
```
