# lahsiva/whatsapp-chat-analyser architecture

> Architecture diagram of the GitHub repository lahsiva/whatsapp-chat-analyser, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lahsiva/whatsapp-chat-analyser
- Repository: https://github.com/lahsiva/whatsapp-chat-analyser

## Overview

##### Project type & purpose (from README + tree)
This is a **single-process, local (or single-node) Streamlit web app** for **WhatsApp chat analytics**:
- **Input**: user-uploaded exported WhatsApp chat text file
- **Processing**: parsing + preprocessing + NLP feature extraction (TF‑IDF), sentiment classification (Naive Bayes), lexicon-based sentiment
- **Output**: interactive visualizations (timelines, activity maps, word clouds, top terms/topics, sentiment/user activity insights)

There’s no evidence of a separate backend service, database, or microservices; the “backend” is simply the Python Streamlit runtime executing analysis in-memory.

##### File structure analysis → architectural components
Top-level files imply a simple module-based architecture:

- `app.py` / `main.py`
- Likely the Streamlit entrypoint(s): UI layout, file uploader, user controls (filters/user selection), orchestration of analysis calls, and rendering charts.
- For diagramming, treat this as the **Presentation + Orchestration layer**.

- `preprocessor.py`
- Core parsing/cleaning: converting raw WhatsApp export text into structured data (likely a pandas DataFrame with columns like datetime, user, message).
- Treat this as the **Ingestion/Preprocessing layer**.

- `helper.py`
- “Business logic” / analytics functions: timelines, activity maps, word clouds, TF-IDF vectorization, Naive Bayes inference/training (or loading), lexicon scoring, aggregations.
- Treat this as the **Analytics / Feature Engineering / Visualization Data Prep layer**.

- `stop_hinglish.txt`
- A domain-specific stopword list used in tokenization/wordcloud/TF‑IDF cleanup.
- Treat as a **Static resource** feeding NLP.

- `setup.sh`
- Environment bootstrap (dependency install, run commands).
- Treat as **Build/Run tooling** (not runtime).

- `README.md`
- High-level purpose; no additional runtime components implied.

At runtime the flow is essentially:

##### `helper.py` computes
- aggregations (timelines, activity heatmaps)
- NLP artifacts (tokenization, stopword removal using `stop_hinglish.txt`)
- TF‑IDF features
- sentiment via Naive Bayes + lexicon scoring

##### System Context (Level 0) – who uses it and what external artifacts exist

This gives maximum clarity without inventing non-existent services.

##### Ingestion & Preprocessing
- `preprocessor.py`
- Parsing WhatsApp raw text
- Normalizing timestamps/users/messages
- Producing structured dataset (e.g., DataFrame)

##### Analytics / NLP / Insights
- `helper.py`
- Timeline generation (daily/monthly)
- Activity map (hour/day heatmap)
- Word frequency / top words
- Word cloud generation
- Sentiment analysis:
- TF‑IDF vectorizer
- Naive Bayes classifier
- Lexicon-based sentiment scorer

##### Static Data / Configuration
- `stop_hinglish.txt` → used by helper NLP pipeline (stopword filtering)

##### Tooling (out-of-band)

- `app.py/main.py` → `preprocessor.py`: “parse(uploaded_chat)”
- `preprocessor.py` → `app.py/main.py`: “structured_messages_df”
- `app.py/main.py` → `helper.py`: “compute_metrics(df, filters)”
- `helper.py` → `stop_hinglish.txt`: “load/consume stopwords”
- `helper.py` → `app.py/main.py`: “metrics + chart-ready datasets + wordcloud image”
- `app.py/main.py` → Browser: “render plots/tables”

##### Architectural patterns & design principles to highlight (accurately)
- **Layering by responsibility**:
- UI/orchestration (Streamlit entry)
- preprocessing (pure transformation)
- analytics helpers (computations)
- **Pipeline dataflow**:
- raw text → structured dataset → features → insights → visualization
- **Stateless-by-default** (likely):
- results recomputed per upload/session (unless caching is used)
- **In-memory analytics**:
- no persistence layer implied

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 0: System Context
    %% =========================
    subgraph "Level 0 — System Context"
        U["End User"]:::external
        B["Web Browser"]:::external
        W["WhatsApp Exported Chat (.txt)"]:::external
        SYS["WhatsApp Chat Analyzer App"]:::system
    end

    U -->|"upload_chat/select_filters"| B
    B -->|"Streamlit_session(HTTP/WebSocket)"| SYS
    SYS -->|"rendered_visualizations"| B
    W -->|"raw_chat_text"| SYS

    %% =========================
    %% Level 1: Container (Runtime)
    %% =========================
    subgraph "Level 1 — Container (Runtime)"
        subgraph "Single Node / Local Machine"
            ST["Streamlit Server (Python Process)"]:::container
            FS[("Local File System")]:::resource
            PY["Python Libraries (pandas, sklearn, numpy, wordcloud, matplotlib/plotly)"]:::note
        end
    end

    SYS -->|"runs_as"| ST
    ST -->|"load_resource"| FS
    PY -.->|"dependency_context"| ST

    %% =========================
    %% Level 2: Components (Inside Process)
    %% =========================
    subgraph "Level 2 — Components (Inside Streamlit Python Process)"
        direction TB

        subgraph "Presentation + Orchestration"
            A["Streamlit UI & Orchestrator (app.py)"]:::ui
            M["Streamlit UI & Orchestrator (main.py)"]:::ui
            UIX["UI Controls (uploader, filters, view selectors)"]:::ui
            R["Chart/Table Renderer"]:::ui
        end

        subgraph "Ingestion & Preprocessing"
            P["Chat Preprocessor (preprocessor.py)"]:::proc
            PF["Parsing + Cleaning (raw_text → structured table)"]:::proc
        end

        subgraph "Analytics / NLP / Sentiment"
            H["Analytics + NLP + Sentiment (helper.py)"]:::analytics
            AGG["Aggregations (timelines, activity heatmaps)"]:::analytics
            NLP["Tokenize + Clean + TF-IDF"]:::analytics
            SENT["Sentiment Scoring (Naive Bayes + Lexicon)"]:::analytics
            WC["Wordcloud / Top Terms"]:::analytics
        end

        subgraph "Static Resource"
            S["Stopwords Resource (stop_hinglish.txt)"]:::resource
        end

        subgraph "Tooling (Out-of-band)"
            SET["Setup/Run Script (setup.sh)"]:::tooling
            DOC["Documentation (README.md)"]:::doc
        end
    end

    %% Wiring: Context -> Container -> Components
    ST -->|"serves_UI"| A
    ST -->|"serves_UI"| M
    B -->|"interact"| A
    B -->|"interact"| M

    %% Orchestration pipeline
    UIX -->|"uploaded_file_content"| A
    UIX -->|"uploaded_file_content"| M

    A -->|"parse(uploaded_chat)"| P
    M -->|"parse(uploaded_chat)"| P
    P -->|"uses"| PF
    PF -->|"structured_messages_df"| A
    PF -->|"structured_messages_df"| M

    A -->|"compute_metrics(df,filters)"| H
    M -->|"compute_metrics(df,filters)"| H

    H -->|"compute"| AGG
    H -->|"compute"| NLP
    H -->|"compute"| SENT
    H -->|"compute"| WC

    NLP -->|"load/consume_stopwords"| S
    WC -->|"load/consume_stopwords"| S

    H -->|"chart_ready_datasets/scores/wordcloud_image"| R
    R -->|"render_to_browser"| B

    %% Resource + tooling relationships
    FS -->|"contains"| S
    SET -.->|"installs_deps/runs_app"| ST
    DOC -.->|"usage_instructions"| U

    %% =========================
    %% Click Events (mapped paths)
    %% =========================
    click A "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/app.py"
    click M "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/main.py"
    click P "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/preprocessor.py"
    click H "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/helper.py"
    click S "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/stop_hinglish.txt"
    click SET "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/setup.sh"
    click DOC "https://github.com/lahsiva/whatsapp-chat-analyser/blob/main/README.md"

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#ffffff,stroke:#64748b,stroke-width:1px,color:#0f172a
    classDef system fill:#ede9fe,stroke:#6d28d9,stroke-width:2px,color:#2e1065
    classDef container fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0f172a
    classDef ui fill:#bfdbfe,stroke:#1d4ed8,stroke-width:1.5px,color:#0f172a
    classDef proc fill:#bbf7d0,stroke:#16a34a,stroke-width:1.5px,color:#052e16
    classDef analytics fill:#86efac,stroke:#16a34a,stroke-width:1.5px,color:#052e16
    classDef resource fill:#fed7aa,stroke:#c2410c,stroke-width:1.5px,color:#431407
    classDef tooling fill:#e5e7eb,stroke:#6b7280,stroke-width:1.5px,stroke-dasharray:6 4,color:#111827
    classDef doc fill:#f3f4f6,stroke:#6b7280,stroke-width:1.5px,color:#111827
    classDef note fill:#fef9c3,stroke:#ca8a04,stroke-width:1.5px,color:#422006
```
