# nikhilrajput63/cs671-hackthon-project-2025 architecture

> Architecture diagram of the GitHub repository nikhilrajput63/cs671-hackthon-project-2025, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nikhilrajput63/cs671-hackthon-project-2025
- Repository: https://github.com/nikhilrajput63/cs671-hackthon-project-2025

## Overview

##### Project type and purpose
- This is a multi-module AI recommendation system that analyzes a user’s mood via three parallel pipelines—facial expressions, text+emoji, and (optional) voice—and suggests movies accordingly.
- Each subdirectory is effectively its own “service” or module with its own models, data processing, and entry-point (app.py).

##### File structure
- Top-level modules:
– face_expression_recommendation/
– text_emoji_recommendation/
– voice_recommendation/
- Each contains:
– An entry script (app.py)
– Model-loading and inference components (e.g., mood_detector/face_mood.py, models/mood_predictor.py)
– Data processing utilities (data_processing.py, utils/data_processor.py)
– A recommendation engine (recommender/suggestor.py, recommendation_engine.py)
– Static assets or model artifacts (movies.csv, resnet50*.pth)
- The text UI folder follows an MVC-style pattern: ui/components/ for React-like widgets and ui/app.py as the controller.

##### README insights
- Each pipeline is standalone today; future plans call for unifying all three into one application.
- Dependencies are isolated per directory by requirements.txt.
- Data stores are simple CSV files; no external database yet.

##### Main components
a. Input sources
– Camera feed (face pipeline)
– Text input & emoji selection (text pipeline)
– Microphone/voice capture (voice pipeline)
b. Pre-processing modules
– face_expression_recommendation/data_processing.py
– text_emoji_recommendation/utils/data_processor.py
– voice_recommendation/voice_processing.py
c. Mood-detection models
– face: mood_detector/face_mood.py + ResNet50 weights
– text: models/text_embedder.py → mood_predictor.py
– voice: (future) voice tone classifier
d. Recommendation engines
– face_expression_recommendation/recommender/suggestor.py
– text_emoji_recommendation/models/recommendation_engine.py
e. Data store
– movies.csv / processed_movies.csv (stored locally)
f. User interface / API
– face: app.py CLI or minimal web interface
– text: ui/app.py + components
– voice: app.py script

##### Component interactions and data flow
- Model artifact loading from the file system into the detection modules.
- Shared movie database being read by each recommendation engine.

##### Architectural patterns & principles
- Modular “microservice” style: each mood-detector is self-contained.
- MVC pattern in text pipeline’s UI folder.
- Clear separation of concerns: I/O, preprocessing, inference, recommendation.
- Future orchestration layer (API gateway or aggregator service) can sit in front to choose among pipelines.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Face Expression Pipeline
    subgraph "Face Expression Pipeline"
        FI["Camera Feed"]:::face
        FP["Data Processing\ndata_processing.py"]:::face
        FM["Mood Detection Model\nface_mood.py"]:::face
        FW["ResNet50 Weights\nresnet50-0676ba61.pth"]:::face
        FS["Recommendation Engine\nsuggestor.py"]:::face
        FU["UI / Entry Point\napp.py"]:::face
    end

    %% Text+Emoji Pipeline
    subgraph "Text+Emoji Pipeline"
        TI["Text & Emoji Input"]:::text
        TC["Controller\napp.py"]:::text
        QComp["Questionnaire\nquestionnaire.py"]:::text
        ESel["Emoji Selector\nemoji_selector.py"]:::text
        FBComp["Feedback Collector\nfeedback_collector.py"]:::text
        RDComp["Results Display\nresults_display.py"]:::text
        TP["Pre-processing\ndata_processor.py"]:::text
        EU["Embedding Utils\nembedding_utils.py"]:::text
        TE["Text Embedder\ntext_embedder.py"]:::text
        MP["Mood Predictor\nmood_predictor.py"]:::text
        TR["Recommendation Engine\nrecommendation_engine.py"]:::text
        DBG["Debug Logger\ndebug_logger.py"]:::text
    end

    %% Voice Pipeline
    subgraph "Voice Pipeline"
        VInput["Microphone Capture"]:::voice
        VPre["Voice Processing\nvoice_processing.py"]:::voice
        VTC["Tone Classifier\n(future)"]:::voice
        VController["Entry Point\napp.py"]:::voice
    end

    %% Shared Components
    subgraph "Shared Data Stores"
        MDB1["movies.csv"]:::shared
        MDB2["processed_movies.csv"]:::shared
    end

    subgraph "Shared Requirements"
        Req1["requirements.txt"]:::shared
        Req2["requirements.txt"]:::shared
        Req3["requirements.txt"]:::shared
    end

    %% Connections Face
    FI -->|"video frame"| FP
    FP -->|"processed frames"| FM
    FW -->|"weights"| FM
    FM -->|"predicted mood"| FS
    FS -->|"movie list"| FU
    FS -->|"reads movies"| MDB1
    FS -->|"reads processed"| MDB2

    %% Connections Text
    TI -->|"text & emoji"| TP
    TP -->|"cleaned text"| EU
    EU -->|"embeddings"| TE
    TE -->|"embedded tokens"| MP
    MP -->|"predicted mood"| TR
    TR -->|"suggestions"| TC
    TC -->|"display results"| RDComp
    TC -->|"select emoji"| ESel
    TC -->|"collect feedback"| FBComp
    TR -->|"reads movies"| MDB1
    TR -->|"reads processed"| MDB2
    TC --> TP
    DBG --> MP

    %% Connections Voice
    VInput -->|"audio stream"| VPre
    VPre -->|"features"| VTC
    VTC -->|"predicted mood"| VController
    VController -->|"reads movies"| MDB1
    VController -->|"reads processed"| MDB2

    %% Click Events Face
    click FU "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/app.py"
    click FI "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/app.py"
    click FP "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/data_processing.py"
    click FM "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/mood_detector/face_mood.py"
    click FW "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/resnet50-0676ba61.pth"
    click FS "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/recommender/suggestor.py"
    click MDB1 "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/data/movies.csv"
    click MDB2 "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/processed_movies.csv"

    %% Click Events Text
    click TC "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/ui/app.py"
    click ESel "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/ui/components/emoji_selector.py"
    click QComp "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/ui/components/questionnaire.py"
    click FBComp "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/ui/components/feedback_collector.py"
    click RDComp "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/ui/components/results_display.py"
    click TP "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/utils/data_processor.py"
    click EU "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/utils/embedding_utils.py"
    click MP "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/models/mood_predictor.py"
    click TE "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/models/text_embedder.py"
    click TR "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/models/recommendation_engine.py"
    click DBG "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/utils/debug_logger.py"

    %% Click Events Voice
    click VController "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/voice_recommendation/app.py"
    click VInput "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/voice_recommendation/app.py"
    click VPre "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/voice_recommendation/voice_processing.py"

    %% Click Events Shared Requirements
    click Req1 "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/face_expression_recommendation/requirements.txt"
    click Req2 "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/text_emoji_recommendation/requirements.txt"
    click Req3 "https://github.com/nikhilrajput63/cs671-hackthon-project-2025/blob/main/voice_recommendation/requirements.txt"

    %% Styles
    classDef face fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32;
    classDef text fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef voice fill:#fff3e0,stroke:#ef6c00,color:#ef6c00;
    classDef shared fill:#f5f5f5,stroke:#616161,color:#424242;
    classDef sharedRequirements fill:#f5f5f5,stroke:#616161,color:#424242;
    class Req1,Req2,Req3 sharedRequirements
    class MDB1,MDB2 shared
```
