# kartikeya-datta/tv-series-analysis-system architecture

> Architecture diagram of the GitHub repository kartikeya-datta/tv-series-analysis-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kartikeya-datta/tv-series-analysis-system
- Repository: https://github.com/kartikeya-datta/tv-series-analysis-system

## Overview

##### Project type and purpose
- This is a full-stack, Python-based ML web application for “Naruto” subtitle analysis. It provides four core features—theme analysis, named-entity recognition + character network, jutsu text classification, and a Naruto character chatbot—all exposed via a Gradio UI.

##### File structure
- Top level
- gradio_app.py – entrypoint for the web interface (Presentation + Controller)
- requirements.txt, .gitignore, .env_example – config & dependencies
- data/ – raw subtitles, jutsu JSON, CSVs, images
- stubs/ – sample outputs for fast front-end rendering
- notebooks (.ipynb) under each module for experimentation and model training
- Feature modules (each acts like its own service within the monolith)
- theme_classifier/ – zero-shot theme classification using Hugging Face BART
- text_classification/ – jutsu classifier training & inference with DistilBERT
- character_network/ – spaCy NER + NetworkX/PyVis graph generation
- crawler/ – web crawler for jutsu data collection
- utils/ – shared data loaders and training utilities

##### README for additional insights
- It describes four feature pipelines (theme, NER/network, jutsu, chatbot), their data-processing steps, and the tech stack (Gradio, Hugging Face Transformers, spaCy, NetworkX, PyVis, scikit-learn, LoRA, 4-bit quantization, etc.).
- It mentions model training flows in notebooks and inference flows in the Gradio app.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::frontend
        GradioWebApp["Gradio Web App"]:::frontend
    end

    %% Application/Orchestration Layer
    subgraph "Application Layer"
        direction TB
        GradioWebApp -->|"route requests"| ThemeService
        GradioWebApp -->|"route requests"| JutsuService
        GradioWebApp -->|"route requests"| NERService
        GradioWebApp -->|"route requests"| ChatbotService
    end

    %% Services Layer
    subgraph "Feature Services Layer"
        direction TB
        ThemeService["ThemeClassifierService"]:::service
        JutsuService["JutsuClassifierService"]:::service
        NERService["NERCharacterNetworkService"]:::service
        ChatbotService["CharacterChatbotService"]:::service
        CrawlerService["CrawlerService"]:::service
        Utils["Shared Utils"]:::util
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataStorage["Local File System"]:::storage
        Stubs["Stubs (sample outputs)"]:::storage
        ModelRegistry["Model Registry (Hub + Cache)"]:::storage
    end

    %% External Layer
    subgraph "External Services Layer"
        direction TB
        HuggingFaceHub["Hugging Face Hub"]:::external
        spaCyModel["spaCy Model"]:::external
        VisLibs["NetworkX & PyVis"]:::external
    end

    %% Training Environment
    subgraph "Training Environment"
        direction TB
        Notebooks["Jupyter Notebooks"]:::training
        Notebooks -->|uses| Utils
        Notebooks -->|train models| ModelRegistry
        Utils -->|push models| ModelRegistry
    end

    %% Inference Flows (solid)
    Browser -->|access UI| GradioWebApp
    ThemeService -->|load model| ModelRegistry
    JutsuService -->|load model| ModelRegistry
    NERService -->|load spaCy model| spaCyModel
    ChatbotService -->|load model| ModelRegistry
    CrawlerService -->|write data| DataStorage
    ThemeService -->|read data| DataStorage
    JutsuService -->|read data| DataStorage
    NERService -->|read data| DataStorage
    ChatbotService -->|read data| DataStorage
    GradioWebApp -->|response| Browser

    %% Training Flows (dashed)
    Notebooks -.->|train theme model| ThemeService
    Notebooks -.->|train jutsu model| JutsuService
    Notebooks -.->|train ner model| NERService
    Notebooks -.->|fine-tune chatbot| ChatbotService

    %% Model Registry to Hub
    ModelRegistry -->|sync| HuggingFaceHub
    HuggingFaceHub -->|fetch models| ModelRegistry

    %% External Visual libs
    NERService -->|generate graph| VisLibs

    %% Click Events
    click GradioWebApp "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/gradio_app.py"
    click ThemeService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/theme_classifier/theme_classifier.py"
    click ThemeService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/theme_classifier/theme_classification_development.ipynb"
    click JutsuService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/text_classification/jutsu_classifier.py"
    click JutsuService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/text_classification/cleaner.py"
    click JutsuService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/text_classification/custom_trainer.py"
    click JutsuService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/text_classification/training_utils.py"
    click JutsuService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/text_classification/jutsu_classifier_development.ipynb"
    click NERService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/character_network/character_network_generator.py"
    click NERService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/character_network/named_entity_recognizer.py"
    click NERService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/character_network/character_network_generator.ipynb"
    click ChatbotService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/character_chatbot/character_chatbot.py"
    click ChatbotService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/character_chatbot/character_chatbot_development.ipynb"
    click CrawlerService "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/crawler/jutsu_crawler.py"
    click Utils "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/utils/data_loader.py"
    click DataStorage "https://github.com/kartikeya-datta/tv-series-analysis-system/tree/main/data/Subtitles/"
    click DataStorage "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/data/jutsus.json"
    click DataStorage "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/data/jutsus.jsonl"
    click DataStorage "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/data/naruto.csv"
    click DataStorage "https://github.com/kartikeya-datta/tv-series-analysis-system/tree/main/data/images/"
    click Stubs "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/stubs/ner_output.csv"
    click Stubs "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/stubs/theme_classsifier-output.csv"
    click TestScript "https://github.com/kartikeya-datta/tv-series-analysis-system/blob/main/test_dataset.py"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0275d8,stroke-width:1px
    classDef service fill:#DFF7DF,stroke:#28a745,stroke-width:1px
    classDef util fill:#FFF3CD,stroke:#f0ad4e,stroke-width:1px
    classDef storage fill:#FFE3E3,stroke:#d9534f,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#6c757d,stroke-width:1px
    classDef training fill:#E2E3E5,stroke:#5a6268,stroke-width:1px
```
