# gorantlasadwik/sync-tunes architecture

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

- Interactive diagram: https://gitdiagram.com/gorantlasadwik/sync-tunes
- Repository: https://github.com/gorantlasadwik/sync-tunes

## Overview

##### Project type and purpose
- Sync Tunes is a full-stack web application built on Flask.
- Purpose: provide AI-powered, cross-platform playlist synchronization between Spotify and YouTube Music, with secure OAuth, detailed logging, and user isolation.

##### File structure
- Top-level files:
- app.py – main Flask app/routes
- init_db.py – database schema creation
- requirements.txt, env.example – dependencies and config
- Procfile, render.yaml – deployment on Render.com
- templates/ – Jinja2 HTML templates (login, dashboard, playlist, logs, etc.)
- No separate “static/” folder shown but Bootstrap and custom CSS likely served via templates or CDN.

##### README for additional insights
- Backend uses Flask, SQLAlchemy ORM, Flask-Login, bcrypt.
- External integrations: Spotify Web API, YouTube Data API/YouTube Music API, Google Gemini AI, Groq AI.
- Deployment: Render.com with Gunicorn, PostgreSQL.
- Architecture: MVC pattern (Flask views + Jinja2 templates + ORM models), layered service calls, lazy loading, caching, error handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Web Browser UI"]:::frontend
        subgraph "Templates (Jinja2)"
            direction TB
            BaseLayout["Base HTML Layout"]:::frontend
            Index["Home / Landing Page"]:::frontend
            Login["Login View"]:::frontend
            Register["Register View"]:::frontend
            Profile["Profile View"]:::frontend
            Dashboard["Dashboard View"]:::frontend
            AdminDashboard["Admin Dashboard View"]:::frontend
            ConnectPlatform["Connect Platform View"]:::frontend
            PlaylistDetails["Playlist Details View"]:::frontend
            ConfirmFallback["Confirm Fallback Tracks View"]:::frontend
            LogsUI["Logs & Analytics View"]:::frontend
        end
    end

    %% Deployment & Server Layer
    subgraph "Deployment Environment (Render.com)"
        direction TB
        ProcfileNode["Procfile"]:::backend
        RenderYAML["render.yaml"]:::backend
        LoadBalancer["Load Balancer"]:::backend
        Gunicorn["Gunicorn WSGI Server"]:::backend
    end

    %% Backend Application Layer
    subgraph "Flask Application"
        direction TB
        Controllers["Controllers & Routes"]:::backend
        Services["Business Logic Services"]:::backend
        DataAccess["Data Access Layer"]:::backend
        EnvConfig["Environment Config"]:::backend
        Requirements["Package Dependencies"]:::backend
    end

    %% Database
    Database[(PostgreSQL Database)]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        SpotifyOAuth["Spotify OAuth/API"]:::external
        GoogleOAuth["Google OAuth & YouTube APIs"]:::external
        GeminiAI["Google Gemini AI"]:::external
        GroqAI["Groq AI (Fallback)"]:::external
    end

    %% Connections
    Browser -->|HTTP GET/POST| LoadBalancer
    LoadBalancer --> Gunicorn
    Gunicorn --> Controllers
    Controllers -->|renders| BaseLayout
    Controllers -->|uses| Services
    Services -->|queries| DataAccess
    DataAccess -->|reads/writes| Database
    Controllers -->|serves| Index
    Controllers -->|serves| Login
    Controllers -->|serves| Register
    Controllers -->|serves| Profile
    Controllers -->|serves| Dashboard
    Controllers -->|serves| AdminDashboard
    Controllers -->|serves| ConnectPlatform
    Controllers -->|serves| PlaylistDetails
    Controllers -->|serves| ConfirmFallback
    Controllers -->|serves| LogsUI
    Services -->|OAuth flow| SpotifyOAuth
    Services -->|OAuth flow| GoogleOAuth
    Services -->|fetch playlists| SpotifyOAuth
    Services -->|fetch playlists| GoogleOAuth
    Services -->|AI extraction| GeminiAI
    Services -->|AI fallback| GroqAI

    %% Configuration & Dependencies
    Controllers --> EnvConfig
    Controllers --> Requirements

    %% Click Events
    click Controllers "https://github.com/gorantlasadwik/sync-tunes/blob/main/app.py"
    click DataAccess "https://github.com/gorantlasadwik/sync-tunes/blob/main/init_db.py"
    click EnvConfig "https://github.com/gorantlasadwik/sync-tunes/blob/main/env.example"
    click ProcfileNode "https://github.com/gorantlasadwik/sync-tunes/tree/main/Procfile"
    click RenderYAML "https://github.com/gorantlasadwik/sync-tunes/blob/main/render.yaml"
    click Requirements "https://github.com/gorantlasadwik/sync-tunes/blob/main/requirements.txt"
    click BaseLayout "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/base.html"
    click Index "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/index.html"
    click Login "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/login.html"
    click Register "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/register.html"
    click Profile "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/profile.html"
    click Dashboard "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/dashboard.html"
    click AdminDashboard "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/admin_dashboard.html"
    click ConnectPlatform "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/connect_platform.html"
    click PlaylistDetails "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/playlist_details.html"
    click ConfirmFallback "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/confirm_fallback_tracks.html"
    click LogsUI "https://github.com/gorantlasadwik/sync-tunes/blob/main/templates/logs.html"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef database fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
