# botta0oss/bigbrother architecture

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

- Interactive diagram: https://gitdiagram.com/botta0oss/bigbrother
- Repository: https://github.com/botta0oss/bigbrother

## Overview

##### Main Components
a. Data Ingestion
- Local CSV datasets (data/*.csv)
- Telegram API input (API.py – to be created; uses api_id/api_hash/phone)
b. Analysis Engine
- Entry point: main.py
- Core logic: Analysis.py (statistical analysis, sentiment classification via HuggingFace transformers)
c. Data Storage & Artifacts
- Raw & processed CSV files (data/)
- Generated charts (grafici/)
d. Visualization
- Graph generation modules (matplotlib/seaborn in Analysis.py)
e. External Dependencies & Models
- Python 3.9+ runtime
- Transformers library (HuggingFace)
- pandas, numpy, matplotlib, etc.

##### Component Relationships & Data Flow
- CSV files read by main.py/Analysis.py
- Telegram messages fetched by API.py
- Preprocessing, tokenization, statistical computations
- Calls HuggingFace transformer models for embedding/sentiment analysis
- Writes results back to CSV in data/
- Generates charts in grafici/

##### Architectural Patterns & Principles
- Modular separation: ingestion logic (API.py), analysis logic (Analysis.py), orchestration (main.py)
- Single-process monolith for simplicity, but modules can be refactored into microservices if needed
- Extensibility points: pluggable data sources (add new API modules), new analysis submodules

##### Technologies & Frameworks
- Python 3.9+
- HuggingFace Transformers (for NLP models)
- pandas/numpy (data manipulation)
- matplotlib/seaborn (plotting)
- Telethon or python-telegram-api (in API.py for Telegram ingestion)

##### Final Checklist
- All modules and folders clearly labeled
- An outer boundary that encapsulates the system

## Diagram (Mermaid)

```mermaid
flowchart TD
  subgraph "BigBrother System"
    direction TB

    CSV["CSV Files (data/*.csv)"]:::external
    TelegramAPI["Telegram API"]:::external

    API["API.py"]:::code
    Main["main.py"]:::code
    Analysis["Analysis.py"]:::code

    HuggingFace["HuggingFace Model Hub"]:::external

    DataDir["data/"]:::storage
    GrafDir["grafici/"]:::storage
    Sentiment["sentimenti.csv"]:::storage
    TopWords["top_parole.csv"]:::storage

    Requirements["requirements.txt"]:::docs
    Readme["README.md"]:::docs

    CSV -->|"raw CSV via pandas.read_csv"| Main
    CSV -->|"raw CSV via pandas.read_csv"| Analysis
    TelegramAPI -->|"messages via HTTP/JSON"| API
    API -->|"preprocessed text"| Analysis
    Main -->|"trigger analysis"| Analysis
    Analysis -->|"sentiment labels via Transformers pipeline"| HuggingFace
    Analysis -->|"writes processed CSV"| DataDir
    Analysis -->|"writes results"| Sentiment
    Analysis -->|"writes results"| TopWords
    Analysis -->|"generate .png charts"| GrafDir
  end

  click DataDir "https://github.com/botta0oss/bigbrother/tree/main/data/"
  click Analysis "https://github.com/botta0oss/bigbrother/blob/main/Analysis.py"
  click Main "https://github.com/botta0oss/bigbrother/blob/main/main.py"
  click GrafDir "https://github.com/botta0oss/bigbrother/tree/main/grafici/"
  click Sentiment "https://github.com/botta0oss/bigbrother/blob/main/sentimenti.csv"
  click TopWords "https://github.com/botta0oss/bigbrother/blob/main/top_parole.csv"
  click Requirements "https://github.com/botta0oss/bigbrother/blob/main/requirements.txt"
  click Readme "https://github.com/botta0oss/bigbrother/blob/main/README.md"

  classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
  classDef storage fill:#90EE90,stroke:#000,stroke-width:1px
  classDef external fill:#FFA500,stroke:#000,stroke-width:1px
  classDef docs fill:#D3D3D3,stroke:#000,stroke-width:1px
```
