# adil-pathan/angular-spotify architecture

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

- Interactive diagram: https://gitdiagram.com/adil-pathan/angular-spotify
- Repository: https://github.com/adil-pathan/angular-spotify

## Overview

##### Project Type & Purpose
- This is a front-end single-page Angular 15 application (“Angular-Spotify”) housed in an Nx monorepo. There is no custom backend—data comes directly from the Spotify Web API and the Spotify Web Playback SDK.

##### File Structure Analysis
- Top-level “apps/angular-spotify”: the host SPA with shell module, PWA config, main.ts, index.html, ngsw-config.
- “libs/web”: domain‐driven directories (auth, home, browse, album, artist, playlist, search, settings, tracks, visualizer, container-queries, future-responsive). Each domain contains three lib types:
- data-access (NgRx stores + services)
- feature (smart modules/components)
- ui (SCAMs—single component Angular modules)
- “libs/shared”: cross-cutting concerns (app-init, app-config, assets, data-access/model & API wrappers, data-access/store, ui primitives, pipes, directives, utils).
- CI/CD & tooling: Netlify deploy config, Nx Cloud caching, Husky, ESLint, Jest.

##### Components
- Browser / Client: where the Angular SPA runs, including Service Worker (ngsw-config) and PWA manifest.
- Angular-Spotify App:
- Shell Module (router outlets, nav-bar, now-playing bar, layout)
- Feature Modules (home, browse, album, artist, playlist, search, tracks, visualizer)
- UI SCAM Modules (buttons, inputs, tables, cards, media-cover, play-button, spinners, etc.)
- State Management Layer:
- NgRx Store (global feature stores in data-access libs)
- NgRx Effects (api calls in data-access)
- Component Store (AuthStore, UIStore)
- Data-Access Layer:
- Shared Spotify-API wrappers (libs/shared/data-access/spotify-api)
- Shared model definitions (libs/shared/data-access/models)
- Domain data-access libs calling Spotify API endpoints
- External Services:
- Spotify Web API (REST endpoints for albums, tracks, artists, etc.)
- Spotify Web Playback SDK (audio playback engine)
- Netlify (hosting & CI/CD)
- Nx Cloud (remote cache)

##### Relationships & Data Flows
- User → Browser SPA (HTTP GET index.html)
- SPA loads Angular Shell → lazy-loads Feature Modules via Router
- Feature Component dispatches NgRx Action → handled by Effects in data-access lib → makes HTTP call to Spotify API via shared Spotify-API wrapper → response → reducer updates Store → selector provides data back to Component (async pipes)
- Play track: Component dispatches play action → effect calls Spotify-API play endpoint & initializes Web Playback SDK → audio events streamed in browser audio context → visualizer store picks up audio levels → visualizer UI renders canvas/particles
- Settings flows: UI interacts with settings feature → persists in local storage via shared settings data-access
- PWA: Service Worker intercepts asset/API calls for caching
- CI/CD: Nx builds & tests libs and apps, pushes artifacts to Netlify; Nx Cloud caches build artifacts

##### Architectural Patterns & Principles
- Monorepo with Nx workspace, domain-driven libs
- Feature-driven lazy loading + SCAM modules for tree-shaking
- Unidirectional data flow via NgRx / Component Store
- Separation of concerns: UI vs feature vs data-access vs shared
- PWA capabilities via Angular service worker

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Presentation Layer
  subgraph "Presentation Layer"
    direction TB
    Browser["Browser / Client SPA"]:::external
    SPA["Angular-Spotify SPA"]:::frontend
    subgraph "Shell Module"
      direction TB
      Shell["Web Shell Module"]:::frontend
    end
    subgraph "Feature Modules"
      direction TB
      HomeF["Home Feature Module"]:::frontend
      BrowseF["Browse Feature Module"]:::frontend
      AlbumF["Album Feature Module"]:::frontend
      ArtistF["Artist Feature Module"]:::frontend
      PlaylistF["Playlist Feature Module"]:::frontend
      SearchF["Search Feature Module"]:::frontend
      TracksF["Tracks Feature Module"]:::frontend
      VisualizerF["Visualizer Feature Module"]:::frontend
    end
    subgraph "UI SCAMs"
      direction TB
      UIS["Shared UI Components"]:::frontend
    end
  end

  %% State Layer
  subgraph "State Layer"
    direction TB
    NGRX["NgRx Store & Effects"]:::state
    CS["Component Stores"]:::state
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    APIWRAP["Spotify API Wrappers"]:::api
    MODELS["Shared Models"]:::api
    DOMAINDA["Domain Data-Access"]:::api
  end

  %% External Systems
  subgraph "External Systems"
    direction TB
    SpotifyAPI["Spotify Web API"]:::external
    SDK["Web Playback SDK"]:::external
    SW["Service Worker"]:::external
  end

  %% Hosting & CI/CD
  subgraph "Hosting & CI/CD"
    direction TB
    Netlify["Netlify Deploy"]:::hosting
    NXCloud["Nx Cloud"]:::hosting
    Tooling["VSCode, Husky, ESLint, Jest"]:::hosting
  end

  %% Data Flows
  Browser -->|HTTP GET index.html| SPA
  SPA -->|loads| Shell
  Shell -->|lazy-loads via Router| HomeF
  Shell --> BrowseF
  Shell --> AlbumF
  Shell --> ArtistF
  Shell --> PlaylistF
  Shell --> SearchF
  Shell --> TracksF
  Shell --> VisualizerF
  HomeF -->|Dispatch Action| NGRX
  BrowseF --> NGRX
  AlbumF --> NGRX
  ArtistF --> NGRX
  PlaylistF --> NGRX
  SearchF --> NGRX
  TracksF --> NGRX
  VisualizerF --> NGRX
  NGRX -->|Effect HTTP| APIWRAP
  APIWRAP -->|HTTP GET/POST| SpotifyAPI
  VisualizerF -->|play action| SDK
  SDK -->|audio events| VisualizerF
  SPA -->|controls caching| SW
  SW -->|intercepts| APIWRAP
  SPA -->|CI/CD build| Netlify
  NXCloud -->|caches| Netlify

  %% Component Store Connections
  Shell --> CS
  UIS --> CS

  %% Dependencies
  Shell -.-> UIS
  HomeF -.-> UIS
  BrowseF -.-> UIS
  AlbumF -.-> UIS
  ArtistF -.-> UIS
  PlaylistF -.-> UIS
  SearchF -.-> UIS
  TracksF -.-> UIS
  VisualizerF -.-> UIS

  %% Click Events
  click Browser "https://github.com/adil-pathan/angular-spotify/blob/main/apps/angular-spotify/src/main.ts"
  click Shell "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/shell/feature/src/lib/web-shell.module.ts"
  click HomeF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/home/feature/src/lib/home.component.ts"
  click BrowseF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/browse/feature/shell/src/lib/browse-shell.module.ts"
  click AlbumF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/album/feature/shell/src/lib/album-shell.module.ts"
  click ArtistF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/artist/feature/src/lib/artist.component.ts"
  click PlaylistF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/playlist/feature/detail/src/lib/playlist.component.ts"
  click SearchF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/search/feature/src/lib/search.component.ts"
  click TracksF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/tracks/feature/src/lib/tracks.component.ts"
  click VisualizerF "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/visualizer/feature/src/lib/visualizer.component.ts"
  click APIWRAP "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/shared/data-access/spotify-api/src/lib/spotify-api.ts"
  click MODELS "https://github.com/adil-pathan/angular-spotify/blob/main/libs/web/shared/data-access/models/src/lib/store/generic-state.ts"

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
  classDef state fill:#FFE8C8,stroke:#d67e00,stroke-width:1px
  classDef api fill:#E2F7E1,stroke:#2d8a00,stroke-width:1px
  classDef external fill:#E0E0E0,stroke:#666666,stroke-width:1px
  classDef hosting fill:#F3E5F5,stroke:#7B1FA2,stroke-width:1px,stroke-dasharray: 5 5
```
