# bentrevett/pytorch-sentiment-analysis architecture

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

- Interactive diagram: https://gitdiagram.com/bentrevett/pytorch-sentiment-analysis
- Repository: https://github.com/bentrevett/pytorch-sentiment-analysis

## Overview

##### Project Type and Purpose
- This is an educational “tutorial” repository demonstrating how to build and train sequence-classification (sentiment analysis) models in PyTorch.
- It is not a deployed application or microservice, but a sequence of Jupyter notebooks that walk through:
- Neural Bag-of-Words model
- Recurrent Neural Networks (LSTM)
- Convolutional Neural Networks for text
- Transformer (BERT) fine-tuning
- A `legacy` folder contains older TorchText-based tutorials.

##### File Structure Analysis
Top level:
- 1-4 .ipynb files – one per tutorial step
- `assets/` – saved XML artifacts (e.g., nbow_model.xml)
- `legacy/` – legacy tutorials, datasets, embeddings, assets
- `requirements.txt`, `README.md`

The notebooks all follow the same high-level workflow:
1. Data loading & preprocessing
2. Vocabulary/embeddings setup
3. Model definition
4. Training & evaluation
5. Saving/loading artifacts

##### Key Technical Insights from README
- Python 3.9, PyTorch, TorchText (in legacy), HuggingFace Transformers
- Uses IMDB movie reviews dataset via torchtext/datasets or custom CSV/JSON/TSV in `legacy/data`
- Demonstrates data pipelines, model classes, training loops, evaluation metrics

a. Main Components
1. Data Source(s)
– Built-in torchtext IMDB splits OR custom CSV/JSON/TSV in `legacy/data`
2. Preprocessing Module
– Tokenization (basic split or pretrained tokenizer for BERT)
– Vocabulary & Embedding setup (XML assets or pretrained vectors)
3. Model Architectures
– NBOW model
– RNN (LSTM) model
– CNN model
– Transformer (BERT) model
4. Training Engine
– PyTorch training loop, optimizer, loss, metrics
5. Artifact Storage
– XML model exports (`assets/nbow_model.xml`, etc.)
– PyTorch state_dict or HuggingFace checkpoints
6. Notebook Runner / User Interface
– Jupyter environment or Colab integration button

b. Relationships & Interactions
– Data Source → Preprocessing → Model → Training Engine → Artifact Storage
– Legacy pipeline parallels the above using TorchText’s old API

c. Architectural Patterns & Principles
– Modular: Separate data, model, training
– Extensible: Swap in new architectures without changing preprocessing
– Reusable artifacts: Save/load models via XML or PyTorch’s checkpointing
– Educational layering: each notebook builds on prior components

d. Relevant Technologies
– PyTorch (core)
– TorchText (legacy)
– HuggingFace Transformers
– Python CSV/JSON/TSV I/O
– Jupyter / Colab interface

##### Don’t Overthink—Capture All Essential Elements
- Break the project into these modules, then represent how code/data flows through them in each notebook.
- Be exhaustive: include both current and legacy data sources, all four model types, and artifact storage.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Sources
    DataSource["IMDB Dataset\n(torchtext)"]:::data
    LegacyData["Legacy Data\n(CSV/JSON/TSV)"]:::legacy
    click LegacyData "https://github.com/bentrevett/pytorch-sentiment-analysis/tree/main/legacy/data/"

    %% Preprocessing
    Tokenizer["Tokenizer\n(basic & pretrained)"]:::data
    Embedding["Vocabulary & Embedding Setup"]:::data
    click Embedding "https://github.com/bentrevett/pytorch-sentiment-analysis/tree/main/assets/"
    click Embedding "https://github.com/bentrevett/pytorch-sentiment-analysis/tree/main/legacy/assets/"
    click Embedding "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/legacy/custom_embeddings/embeddings.txt"

    %% Models
    NBOW["Neural Bag-of-Words Model"]:::model
    click NBOW "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/1 - Neural Bag of Words.ipynb"
    RNN["RNN (LSTM) Model"]:::model
    click RNN "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/2 - Recurrent Neural Networks.ipynb"
    CNN["CNN Model"]:::model
    click CNN "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/3 - Convolutional Neural Networks.ipynb"
    BERT["Transformer (BERT) Model"]:::model
    click BERT "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/4 - Transformers.ipynb"

    %% Training & Evaluation
    Trainer["Training & Evaluation Engine"]:::training

    %% Artifact Storage
    Artifacts["Artifact Storage\n(XML & Checkpoints)"]:::storage
    click Artifacts "https://github.com/bentrevett/pytorch-sentiment-analysis/blob/main/assets/nbow_model.xml"

    %% Legacy Tutorials
    subgraph "Legacy Tutorial Pipeline" 
        direction TB
        LegacyDocs["Legacy Tutorials"]:::legacy
        click LegacyDocs "https://github.com/bentrevett/pytorch-sentiment-analysis/tree/main/legacy/"
        LegacyDocs --> LegacyProc["Legacy Preprocessing"]:::legacy
        LegacyProc --> LegacyModel["Legacy Models (TorchText)"]:::legacy
        LegacyModel --> LegacyAssets["Legacy Artifact Storage"]:::legacy
        click LegacyAssets "https://github.com/bentrevett/pytorch-sentiment-analysis/tree/main/legacy/assets/"
    end

    %% Flow Connections
    DataSource --> Tokenizer
    LegacyData --> Tokenizer
    Tokenizer --> Embedding
    Embedding --> NBOW
    Embedding --> RNN
    Embedding --> CNN
    Embedding --> BERT
    NBOW --> Trainer
    RNN --> Trainer
    CNN --> Trainer
    BERT --> Trainer
    Trainer --> Artifacts

    %% Styles
    classDef data fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef model fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef training fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef storage fill:#E0E0E0,stroke:#9E9E9E,color:#424242;
    classDef legacy fill:#F5F5F5,stroke-dasharray: 5 5,stroke:#9E9E9E,color:#757575;
```
