# iborntowin/nasmytunes architecture

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

- Interactive diagram: https://gitdiagram.com/iborntowin/nasmytunes
- Repository: https://github.com/iborntowin/nasmytunes

## Overview

##### Project type and purpose
- This is a full-stack, monolithic web application written in Python (Flask or Flask-style), with a static front-end (HTML/CSS/JS) served from the same server.
- Its goal: take a Spotify playlist URL, fetch track metadata via the Spotify API, search and download audio from YouTube, convert tracks to MP3 (using FFmpeg), bundle them in a ZIP, and serve them to the user.

##### File structure (layers and modules)
- Top-level entrypoints:
- app.py / src/main.py: Flask app startup
- start.sh / start_production.py: production launch scripts
- Routes/controllers (src/routes): conversion.py, spotify.py, youtube.py, user.py
- Business logic/services (src/utils): YouTube bypass/download modules, alternative platform modules, cookie bypass, FFmpeg invocation
- Data models (src/models) + database (src/database/app.db): user and session persistence (SQLite)
- Static assets (src/static): front-end UI (index.html, styles.css, app.js, glassmorphism demo notice)
- Config/deployment: Dockerfile, railway.json, render.yaml, vercel.json, Procfile

##### Main components
a. Client (Web Browser)
- Loads static HTML/CSS/JS, initiates REST calls.
b. Web Server (Flask Application)
- HTTP layer (Flask routes/controllers)
- Service layer (Spotify API client, YouTube downloader, bypass modules)
- Conversion engine (FFmpeg process)
- ZIP bundling module
- Persistence layer (SQLite via ORM in src/models)
c. Database (SQLite file)
d. File storage / temp workspace
- Intermediate MP3 files, ZIP archives on local disk (or ephemeral container storage)
e. External Services
- Spotify Web API
- YouTube (unofficial bypass download endpoints)
- (Optional) Genius API for metadata

##### Relationships and data flows
- Browser → (HTTP GET/POST) → Flask
- Flask → (API calls over HTTPS) → Spotify API
- Flask → (HTTP requests + bypass logic) → YouTube download servers
- Flask → (shell invocation) → FFmpeg for MP3 conversion
- Flask → (filesystem I/O) → Local storage (MP3 + ZIP)
- Browser ← (HTTP file stream) ← Flask (ZIP download)
- Flask ↔ (SQLite queries) ↔ Database

##### Architectural patterns and design principles
- Layered architecture:
- Presentation layer (static front-end + Flask view functions)
- Application layer (controllers + service modules under src/utils)
- Data layer (ORM models + SQLite DB)
- Single-container monolith deployed via Docker/Railway/Render/Vercel
- Plugin-style downloader modules: utility classes in src/utils
- Synchronous request flow (no separate background worker, though could be extended)

##### Relevant technologies/frameworks
- Python 3.x, Flask (or Flask-like framework)
- SQLite (app.db) via SQLAlchemy or similar ORM
- FFmpeg CLI for audio transcoding
- Front-end: vanilla JS + HTML/CSS (glassmorphism UI)
- Deployment: Docker, Railway, Render, Vercel (serverless)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Frontend
    subgraph "Client / Presentation Layer"
        direction TB
        Browser["Web Browser"]:::external
        subgraph "Static Assets"
            direction TB
            Index["index.html"]:::frontend
            Styles["styles.css"]:::frontend
            AppJS["app.js"]:::frontend
            DemoNotice["demo-notice.html"]:::frontend
        end
    end

    %% Docker Container Boundary
    subgraph "Docker Container"
        direction TB
        %% Entrypoint
        subgraph "Entrypoint" 
            direction TB
            AppPy["app.py"]:::internal
            MainPy["src/main.py"]:::internal
            StartSh["start.sh"]:::internal
            StartProd["start_production.py"]:::internal
        end

        %% Web Server Components
        subgraph "Web Server (Flask App)" 
            direction TB
            %% Controllers Layer
            subgraph "Controllers (src/routes)" 
                direction TB
                SpotifyRoute["spotify.py"]:::internal
                YouTubeRoute["youtube.py"]:::internal
                ConversionRoute["conversion.py"]:::internal
                UserRoute["user.py"]:::internal
            end

            %% Service Layer
            subgraph "Service Layer (src/utils)"
                direction TB
                YTDL["youtube_downloader.py"]:::internal
                SimpleBypass["simple_bypass.py"]:::internal
                AdvBypass["advanced_youtube_bypass.py"]:::internal
                CookieBypass["cookie_bypass.py"]:::internal
                AltDL["alternative_downloader.py"]:::internal
                AltPlatforms["alternative_platforms.py"]:::internal
            end

            %% Conversion Engine & Bundler
            subgraph "Conversion & Bundling"
                direction TB
                FFmpeg["FFmpeg CLI"]:::process
                ZipBundler["ZIP Bundler"]:::process
            end

            %% Persistence Layer
            subgraph "Persistence"
                direction TB
                UserModel["user.py (ORM)"]:::datastore
                SQLiteDB["app.db (SQLite)"]:::datastore
            end

            %% Temp Storage
            TempStorage["File Storage (MP3 & ZIP)"]:::datastore
        end
    end

    %% External Services
    SpotifyAPI["Spotify Web API"]:::external
    YouTubeExt["YouTube Download Servers"]:::external
    GeniusAPI["Genius API (optional)"]:::external

    %% Connections
    Browser -->|"HTTP GET/POST"| Index
    Browser --> Styles
    Browser --> AppJS
    Browser --> DemoNotice

    Browser -->|"HTTP"| SpotifyRoute
    Browser -->|"HTTP"| YouTubeRoute
    Browser -->|"HTTP"| ConversionRoute
    Browser -->|"HTTP"| UserRoute

    SpotifyRoute -->|"HTTPS / playlist metadata"| SpotifyAPI
    YouTubeRoute -->|"HTTP + bypass logic"| YouTubeExt
    ConversionRoute -->|"spawn process"| FFmpeg
    ConversionRoute -->|"invoke"| ZipBundler

    ConversionRoute -->|"Read/Write"| TempStorage
    ZipBundler -->|"Read/Write"| TempStorage

    UserRoute -->|"SQL queries"| SQLiteDB
    UserRoute --> UserModel
    UserModel --> SQLiteDB

    %% Download flow back to client
    ZipBundler -->|"HTTP file stream"| Browser

    %% Service Layer calls
    YouTubeRoute --> YTDL
    YouTubeRoute --> SimpleBypass
    YouTubeRoute --> AdvBypass
    YouTubeRoute --> CookieBypass
    YouTubeRoute --> AltDL
    YouTubeRoute --> AltPlatforms

    %% Legend
    classDef frontend fill:#A9DFBF,stroke:#1D8348,color:#000
    classDef internal fill:#AED6F1,stroke:#21618C,color:#000
    classDef datastore fill:#ABEBC6,stroke:#196F3D,color:#000
    classDef external fill:#D7DBDD,stroke:#424949,color:#000
    classDef process fill:#F5B041,stroke:#B9770E,color:#000

    %% Click Events
    click Index "https://github.com/iborntowin/nasmytunes/blob/main/src/static/index.html"
    click Styles "https://github.com/iborntowin/nasmytunes/blob/main/src/static/styles.css"
    click AppJS "https://github.com/iborntowin/nasmytunes/blob/main/src/static/app.js"
    click DemoNotice "https://github.com/iborntowin/nasmytunes/blob/main/src/static/demo-notice.html"

    click AppPy "https://github.com/iborntowin/nasmytunes/blob/main/app.py"
    click MainPy "https://github.com/iborntowin/nasmytunes/blob/main/src/main.py"
    click StartSh "https://github.com/iborntowin/nasmytunes/blob/main/start.sh"
    click StartProd "https://github.com/iborntowin/nasmytunes/blob/main/start_production.py"

    click SpotifyRoute "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/spotify.py"
    click YouTubeRoute "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/youtube.py"
    click ConversionRoute "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/conversion.py"
    click UserRoute "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/user.py"

    click YTDL "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/youtube_downloader.py"
    click SimpleBypass "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/simple_bypass.py"
    click AdvBypass "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/advanced_youtube_bypass.py"
    click CookieBypass "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/cookie_bypass.py"
    click AltDL "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/alternative_downloader.py"
    click AltPlatforms "https://github.com/iborntowin/nasmytunes/blob/main/src/utils/alternative_platforms.py"

    click UserModel "https://github.com/iborntowin/nasmytunes/blob/main/src/models/user.py"
    click SQLiteDB "https://github.com/iborntowin/nasmytunes/blob/main/src/database/app.db"
    click FFmpeg "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/conversion.py"
    click ZipBundler "https://github.com/iborntowin/nasmytunes/blob/main/src/routes/conversion.py"
```
