# nayara/musicfy-app architecture

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

- Interactive diagram: https://gitdiagram.com/nayara/musicfy-app
- Repository: https://github.com/nayara/musicfy-app

## Overview

##### Project Type and Purpose
- This is a single-page frontend application (“musicfy-app”) built with React and TypeScript.
- It displays Spotify playlists by calling an external Spotify Scraper API, and uses Google OAuth for authentication.
- No custom backend service: all business logic runs in the browser, with build and asset delivery handled by Webpack.

##### File Structure Analysis
- Top‐level:
- public/index.html – static HTML host page
- src/ – all React source code
- environment/ – .env template for API keys
- webpack.*.js – build configurations for dev/prod
- jest.config.js, jest.setup.js – test setup
- src/ divided by concern:
- src/api – HTTP client + React Query hooks for external API
- src/components – UI layers following Atomic Design (atoms, molecules, organisms, layouts)
- src/pages – route‐level containers (Home, Login, PlaylistDetail)
- src/providers – app‐wide context providers (OAuth, React Query, Theme)
- src/contexts/user – user state and token context
- src/routes – react-router setup
- src/utils, src/styles, src/themes – utilities and theming
- Tests alongside units indicate a component‐test driven approach.

##### Key README Insights
- Uses React Query for data fetching/caching.
- Google OAuth provider wraps the app to retrieve and store access tokens.
- Environment variables store Spotify API credentials.

##### Main Components
a. Client Side
- Browser + Webpack Dev/Prod Server – delivers bundled JS/CSS/HTML.
- React App Root (src/index.tsx)
- Providers Layer
– GoogleOAuth.provider → handles OAuth flow with Google
– ReactQuery.provider → configures query client and cache
– Theme.provider → injects styled-components theme
- Context Layer
– User.context → holds authenticated user & token
- Routing Layer
– src/routes/index.tsx → maps URLs to pages
- Pages
– Login Page
– Home Page
– PlaylistDetail Page
- Component Hierarchy
– Organisms (Home, Login, PlaylistDetail) build pages with Molecules (Header, LoginButton, Track) and Atoms (Button, Card)
- API Layer
– api/client.ts → Axios or fetch wrapper injecting token from context
– api/queries → React Query hooks use-get-home, use-get-playlist-metadata, use-get-playlist-musics
b. External Services
- Google OAuth Service – for user authentication
- Spotify Scraper API – external RapidAPI endpoint returning playlist data

##### Relationships and Data Flow
- User Interaction → React Router → Page component
- Page triggers React Query hook → API client (attached with user token) → External Spotify API → Query cache → UI updates
- GoogleOAuth.provider encapsulates OAuth redirects and token refresh, updates User.context
- Theme.provider supplies styling object consumed by styled-components in UI atoms/molecules/organisms

##### Architectural Patterns & Principles
- Atomic Design (atoms → molecules → organisms → pages) for UI composition
- Provider pattern for cross-cutting concerns (auth, data fetching, theming)
- React Query for server state management and caching
- Separation of concerns: routing, state, API, presentation all in distinct folders

##### Essential Elements
- Component containers: Providers, Context, Router, Pages, Components, API
- External endpoints: Google OAuth, Spotify Scraper API
- Build tools: Webpack (with dev vs. prod modes)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Tools
    subgraph "Build & Config"
        direction TB
        Env[".env template"]:::build
        WebpackCommon["webpack.common.js"]:::build
        WebpackDev["webpack.local.js"]:::build
        WebpackProd["webpack.prod.js"]:::build
        JestConfig["jest.config.js"]:::build
        JestSetup["jest.setup.js"]:::build
    end

    %% Browser and Host
    Browser["Browser"]:::ext
    StaticPage["public/index.html"]:::build

    %% Data & Auth Services
    subgraph "External Services"
        direction TB
        OAuthService["Google OAuth Service"]:::authExt
        SpotifyAPI["Spotify Scraper API"]:::dataExt
    end

    %% Application Layers
    subgraph "App Initialization"
        direction TB
        StaticPage -->|hosts| Browser
        Browser -->|loads bundle| ReactRoot
        ReactRoot["src/index.tsx"]:::ui
    end

    subgraph "Providers Layer"
        direction TB
        GoogleOAuthProv["GoogleOAuth.provider"]:::auth
        ReactQueryProv["ReactQuery.provider"]:::data
        ThemeProv["Theme.provider"]:::ui
        ProvidersBarrel["src/providers/index.tsx"]:::ui
        ReactRoot --> ProvidersBarrel
        ProvidersBarrel --> GoogleOAuthProv
        ProvidersBarrel --> ReactQueryProv
        ProvidersBarrel --> ThemeProv
        OAuthService -->|auth flow| GoogleOAuthProv
    end

    subgraph "Context Layer"
        direction TB
        UserContext["User.context"]:::auth
        GoogleOAuthProv --> UserContext
        UserContext --> ReactQueryProv
        UserContext --> APIClient
    end

    subgraph "Routing & Pages"
        direction TB
        Router["src/routes/index.tsx"]:::ui
        LoginPage["Login Page"]:::ui
        HomePage["Home Page"]:::ui
        PlaylistPage["PlaylistDetail Page"]:::ui
        ReactQueryProv --> Router
        ThemeProv --> Router
        Router --> LoginPage
        Router --> HomePage
        Router --> PlaylistPage
    end

    subgraph "UI Components"
        direction TB
        Atoms["Atoms"]:::ui
        Molecules["Molecules"]:::ui
        Organisms["Organisms"]:::ui

        Atoms --> Button
        Atoms --> Card
        Molecules --> Header
        Molecules --> LoginButton
        Molecules --> Logo
        Molecules --> Track
        Organisms --> HomeSection
        Organisms --> LoginSection
        Organisms --> PlaylistDetailSection

        LoginPage -->|composed of| Organisms
        HomePage -->|composed of| Organisms
        PlaylistPage -->|composed of| Organisms
    end

    subgraph "Data Layer"
        direction TB
        APIClient["src/api/client.ts"]:::data
        UseHome["use-get-home hook"]:::data
        UsePlaylistMeta["use-get-playlist-metadata hook"]:::data
        UsePlaylistMusics["use-get-playlist-musics hook"]:::data

        ReactQueryProv --> UseHome
        ReactQueryProv --> UsePlaylistMeta
        ReactQueryProv --> UsePlaylistMusics
        UseHome --> APIClient
        UsePlaylistMeta --> APIClient
        UsePlaylistMusics --> APIClient
        APIClient -->|calls| SpotifyAPI
    end

    %% Environment to Webpack
    Env --> WebpackCommon
    WebpackCommon --> WebpackDev
    WebpackCommon --> WebpackProd
    WebpackDev --> Browser
    WebpackProd --> Browser

    %% Test Setup
    JestConfig --> JestSetup

    %% Styles & Themes
    subgraph "Styling & Theming"
        direction TB
        GlobalStyles["Global.styles.tsx"]:::ui
        DefaultTheme["default.theme.ts"]:::ui
        ThemeTypes["themes.d.ts"]:::ui
        ThemeProv --> GlobalStyles
        ThemeProv --> DefaultTheme
        ThemeProv --> ThemeTypes
    end

    %% Click Events
    click ReactRoot "https://github.com/nayara/musicfy-app/blob/main/src/index.tsx"
    click StaticPage "https://github.com/nayara/musicfy-app/blob/main/public/index.html"
    click Env "https://github.com/nayara/musicfy-app/blob/main/environment/.env.exemple"
    click WebpackCommon "https://github.com/nayara/musicfy-app/blob/main/webpack.common.js"
    click WebpackDev "https://github.com/nayara/musicfy-app/blob/main/webpack.local.js"
    click WebpackProd "https://github.com/nayara/musicfy-app/blob/main/webpack.prod.js"
    click JestConfig "https://github.com/nayara/musicfy-app/blob/main/jest.config.js"
    click JestSetup "https://github.com/nayara/musicfy-app/blob/main/jest.setup.js"
    click APIClient "https://github.com/nayara/musicfy-app/blob/main/src/api/client.ts"
    click UseHome "https://github.com/nayara/musicfy-app/blob/main/src/api/queries/Home/use-get-home.ts"
    click UsePlaylistMeta "https://github.com/nayara/musicfy-app/blob/main/src/api/queries/Playlist/use-get-playlist-metadata.ts"
    click UsePlaylistMusics "https://github.com/nayara/musicfy-app/blob/main/src/api/queries/Playlist/use-get-playlist-musics.ts"
    click GoogleOAuthProv "https://github.com/nayara/musicfy-app/blob/main/src/providers/GoogleOAuth.provider.tsx"
    click ReactQueryProv "https://github.com/nayara/musicfy-app/blob/main/src/providers/ReactQuery.provider.tsx"
    click ThemeProv "https://github.com/nayara/musicfy-app/blob/main/src/providers/Theme.provider.tsx"
    click ProvidersBarrel "https://github.com/nayara/musicfy-app/blob/main/src/providers/index.tsx"
    click UserContext "https://github.com/nayara/musicfy-app/blob/main/src/contexts/user/User.context.tsx"
    click Router "https://github.com/nayara/musicfy-app/blob/main/src/routes/index.tsx"
    click LoginPage "https://github.com/nayara/musicfy-app/blob/main/src/pages/Login/index.tsx"
    click HomePage "https://github.com/nayara/musicfy-app/blob/main/src/pages/Home/index.tsx"
    click PlaylistPage "https://github.com/nayara/musicfy-app/blob/main/src/pages/PlaylistDetail/index.tsx"
    click Button "https://github.com/nayara/musicfy-app/blob/main/src/components/atoms/Button/index.tsx"
    click Card "https://github.com/nayara/musicfy-app/blob/main/src/components/atoms/Card/index.tsx"
    click Header "https://github.com/nayara/musicfy-app/blob/main/src/components/molecules/Header/index.tsx"
    click LoginButton "https://github.com/nayara/musicfy-app/blob/main/src/components/molecules/LoginButton/index.tsx"
    click Logo "https://github.com/nayara/musicfy-app/blob/main/src/components/molecules/Logo/index.tsx"
    click Track "https://github.com/nayara/musicfy-app/blob/main/src/components/molecules/Track/index.tsx"
    click HomeSection "https://github.com/nayara/musicfy-app/blob/main/src/components/organisms/Home/index.tsx"
    click LoginSection "https://github.com/nayara/musicfy-app/blob/main/src/components/organisms/Login/index.tsx"
    click PlaylistDetailSection "https://github.com/nayara/musicfy-app/blob/main/src/components/organisms/PlaylistDetail/index.tsx"
    click GlobalStyles "https://github.com/nayara/musicfy-app/blob/main/src/styles/Global.styles.tsx"
    click DefaultTheme "https://github.com/nayara/musicfy-app/blob/main/src/themes/default.theme.ts"
    click ThemeTypes "https://github.com/nayara/musicfy-app/blob/main/src/themes.d.ts"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,color:#004085
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef auth fill:#fff3cd,stroke:#856404,color:#856404
    classDef build fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef ext fill:#f8f9fa,stroke:#343a40,color:#343a40
    classDef authExt fill:#ffe5d9,stroke:#ff7f11,color:#ff7f11
    classDef dataExt fill:#d1ecf1,stroke:#0c5460,color:#0c5460
```
