# omerbsezer/lstm_rnn_tutorials_with_demo architecture

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

- Interactive diagram: https://gitdiagram.com/omerbsezer/lstm_rnn_tutorials_with_demo
- Repository: https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo

## Overview

##### Project type and purpose
- This repo is an educational “Sequential Models” tutorial that demos basic RNN/LSTM building blocks plus four sample end-to-end projects:
- BasicRNN (toy implementation)
- BasicLSTM (toy implementation)
- StockPricesPredictionProject
- SentimentAnalysisProject
- MusicGenerationProject
- The root README explains the goal: teach RNN/LSTM concepts via code, from cell math up through real-world demos.

##### File structure
- Top-level directories are one per demo. Each contains:
- main script(s) (e.g. main.py or pricePredictionLSTM.py)
- utility modules (rnn_utils.py, data_utils.py, emo_utils.py, music_utils.py, midi.py, grammar.py, etc.)
- local data (CSV files, .mid files, preprocessed caches, output subfolders)
- No single “frontend/backend” split—each demo is a standalone pipeline.
- Shared pattern: Data → Preprocess → Model Definition → Train → Inference → Output.

##### README for architecture clues
- Each demo uses Keras/TensorFlow under the hood.
- External data sources: Yahoo Finance CSV, Kaggle GloVe embeddings, music21 toolkit for MIDI parsing.
- Each project follows the same LSTM structure but with different data types.

##### Main components and interactions
a. Shared core layer (center):
– RNN utilities (BasicRNN/rnn_utils.py)
– LSTM utilities (BasicLSTM/rnn_utils.py)
– Data-preprocessing utilities (data_utils.py, emo_utils.py, music_utils.py)
– Grammar & MIDI helpers (grammar.py, midi.py)
b. Four demo pipelines (clustered around the core):
1) Stock Predictor
- Input: DIS.csv (finance.yahoo.com)
- Preprocess: normalize, windowing
- Model: Keras LSTM (25 units)
- Output: lstm_result.csv, price plot
2) Sentiment Emojifier
- Input: train_emoji.csv/test_emoji.csv (local)
- Preprocess: Glove embeddings (external Kaggle file)
- Model: Keras LSTM classifier
- Output: emoji predictions, confusion results
3) Music Generator
- Input: original_metheny.mid (music21 toolkit)
- Preprocess: one-hot sequence (Tx=30, n_values=78)
- Model: stacked LSTM, inference model
- Output: my_music.midi
4) Basic RNN/LSTM demos
- Input: toy sequences
- Preprocess & model: manual forward/backward implementations
- Output: console logs, unit-test style outputs
c. External services & data stores (placed outside system boundary):
– Yahoo Finance CSV
– Kaggle GloVe vectors
– music21 toolkit / MIDI files
– Python environment (Keras, TensorFlow)

##### Architectural patterns & design principles
- Layered pipeline per demo:
Data Layer → Preprocess Layer → Model Layer → Training/Inference Layer → Output Layer
- Reuse via shared utilities (DRY)
- Directory-per-demo isolation (modular, pluggable)
- Consistent LSTM/RNN abstraction across demos

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Sequential Models Tutorial Repo"
        subgraph "Shared Utilities"
            SU1["RNN Utils (BasicRNN)"]:::shared
            SU2["RNN Utils (BasicLSTM)"]:::shared
            SU3["Emo Utils"]:::shared
            SU4["Music Data Utils"]:::shared
            SU5["Grammar Helper"]:::shared
            SU6["MIDI Helper"]:::shared
            SU7["Music Utils"]:::shared
        end

        subgraph "Basic RNN Demo"
            BR1["main.py"]:::model
            BR2["toy RNN fwd/bwd"]:::shared
        end

        subgraph "Basic LSTM Demo"
            BL1["main.py"]:::model
            BL2["toy LSTM impl"]:::shared
        end

        subgraph "Stock Prices Prediction"
            SP1["DIS.csv"]:::data
            SP2["pricePredictionLSTM.py"]:::model
            SP3["lstm_result.csv"]:::output
        end

        subgraph "Sentiment Analysis"
            SA1["train_emoji.csv"]:::data
            SA2["test_emoji.csv"]:::data
            SA4["Glove embeddings"]:::data
            SA3["main.py"]:::model
        end

        subgraph "Music Generation"
            MG1["original_metheny.mid"]:::data
            MG2["preprocess.py"]:::data
            MG4["main.py"]:::model
            MG3["inference_code.py"]:::output
            MG8["my_music.midi"]:::output
            MG5["midi.py"]:::shared
            MG6["grammar.py"]:::shared
            MG7["music_utils.py"]:::shared
        end
    end

    %% External dependencies
    Yahoo["Yahoo Finance CSV"]:::external
    Kaggle["Kaggle GloVe"]:::external
    Music21["music21 toolkit"]:::external
    PythonEnv["Python Env (Keras/TensorFlow)"]:::external

    %% Data flows
    Yahoo --> SP1
    Kaggle --> SA4
    Music21 --> MG1

    SP1 -->|"raw CSV"| SP2
    SP2 -->|"predicted prices"| SP3

    SA1 --> SA3
    SA2 --> SA3
    SA4 --> SA3
    SA3 -->|"emoji predictions"| SU3

    MG1 --> MG2
    MG2 --> MG4
    MG4 --> MG3
    MG3 --> MG8

    BR1 --> BR2
    BL1 --> BL2

    %% Utility reuse
    SU1 -.-> BR2
    SU2 -.-> BL2
    SU3 -.-> SA3
    SU4 -.-> MG2
    SU5 -.-> MG4
    SU6 -.-> MG4
    SU7 -.-> MG2

    %% Click events
    click SU1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicRNN/rnn_utils.py"
    click SU2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicLSTM/rnn_utils.py"
    click SU3 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/SentimentAnalysisProject/emo_utils.py"
    click SU4 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/data_utils.py"
    click SU5 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/grammar.py"
    click SU6 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/midi.py"
    click SU7 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/music_utils.py"
    click BR1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicRNN/main.py"
    click BR2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicRNN/rnn_utils.py"
    click BL1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicLSTM/main.py"
    click BL2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/BasicLSTM/rnn_utils.py"
    click SP1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/StockPricesPredictionProject/DIS.csv"
    click SP2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/StockPricesPredictionProject/pricePredictionLSTM.py"
    click SP3 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/StockPricesPredictionProject/lstm_result.csv"
    click SA1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/SentimentAnalysisProject/train_emoji.csv"
    click SA2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/SentimentAnalysisProject/test_emoji.csv"
    click SA3 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/SentimentAnalysisProject/main.py"
    click MG1 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/data/original_metheny.mid"
    click MG2 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/preprocess.py"
    click MG3 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/inference_code.py"
    click MG4 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/main.py"
    click MG5 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/midi.py"
    click MG6 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/grammar.py"
    click MG7 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/music_utils.py"
    click MG8 "https://github.com/omerbsezer/lstm_rnn_tutorials_with_demo/blob/master/MusicGenerationProject/output/my_music.midi"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000;
    classDef model fill:#90EE90,stroke:#000;
    classDef output fill:#FFA500,stroke:#000;
    classDef shared fill:#D3D3D3,stroke:#000;
    classDef external fill:#FFF,stroke:#000,stroke-dasharray:5 5;
```
