# nobody082/pbl3 architecture

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

- Interactive diagram: https://gitdiagram.com/nobody082/pbl3
- Repository: https://github.com/nobody082/pbl3

## Overview

PBL3 is a music-streaming web application: users register or sign in, browse and play music, and manage playlists and favourites; artists can upload music. The frontend presents these workflows and the Spring API supplies account, catalogue, and listening features. Sampled code confirms authentication persistence, artist upload and avatar handling, and recent-play/favourite operations. Other feature areas are represented from the README and source tree; their unsampled call wiring is not asserted.

Main entry points: [`backend/api/src/main/java/com/pbl3/controller/AuthController.java`](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/AuthController.java) (Auth API), [`backend/api/src/main/java/com/pbl3/service/AuthService.java`](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/AuthService.java) (Account logic), [`backend/api/src/main/java/com/pbl3/service/CustomOAuth2UserService.java`](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/CustomOAuth2UserService.java) (Google sign-in), [`backend/api/src/main/java/com/pbl3/controller/ArtistController.java`](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/ArtistController.java) (Artist API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["App pages<br/>[page.tsx]"]
  node_authui["Sign-in forms<br/>[LoginForm.tsx]"]
  node_player["Music player<br/>[MusicPlayer.tsx]"]
  node_queue["Playback queue<br/>[QueuePanel.tsx]"]
  node_playlistui["Playlist views<br/>[page.tsx]"]
  node_uploadui["Song upload<br/>[UploadSong.tsx]"]
  node_authstorage["Session storage<br/>[authStorage.ts]"]
end

subgraph group_identity["Identity and profiles"]
  node_authcontroller["Auth API"]
  node_authservice["Account logic<br/>[AuthService.java]"]
  node_oauthservice["Google sign-in"]
  node_humanservice["Profile and history<br/>[HumanService.java]"]
end

subgraph group_music["Music and discovery"]
  node_artistcontroller["Artist API"]
  node_songservice["Song operations"]
  node_songcontract["Discovery operations<br/>[SongService.java]"]
  node_songmapper["Song responses<br/>[SongMapper.java]"]
  node_cloudinaryservice["Media storage"]
end

subgraph group_persistence["Backend persistence"]
  node_humanrepo[("Account records")]
  node_userrepo[("User records")]
  node_artistrepo[("Artist records")]
  node_songrepo[("Song records")]
  node_recentrepo[("Play history")]
end

node_listener(("Listener / artist"))
node_cloudinary(("Cloudinary"))
node_google(("Google identity"))

node_listener -->|"uses"| node_webapp
node_listener -->|"signs in"| node_authui
node_listener -->|"uploads music"| node_uploadui
node_authui -->|"submits credentials"| node_authcontroller
node_authcontroller -->|"authenticates"| node_authservice
node_authservice -->|"looks up account"| node_humanrepo
node_authservice -->|"saves user"| node_userrepo
node_authservice -->|"saves artist"| node_artistrepo
node_authcontroller -->|"returns session data"| node_authstorage
node_authcontroller -.->|"OAuth callback"| node_oauthservice
node_oauthservice -.->|"loads identity"| node_google
node_oauthservice -.->|"finds or updates"| node_humanrepo
node_oauthservice -.->|"creates user"| node_userrepo
node_webapp -->|"opens playback"| node_player
node_webapp -->|"manages playlists"| node_playlistui
node_player -->|"controls queue"| node_queue
node_uploadui -->|"uploads tracks"| node_artistcontroller
node_artistcontroller -->|"uploads media"| node_cloudinaryservice
node_cloudinaryservice -->|"stores media"| node_cloudinary
node_artistcontroller -->|"creates song"| node_songservice
node_artistcontroller -->|"saves artist"| node_artistrepo
node_songservice -->|"reads and writes"| node_songrepo
node_songservice -->|"maps responses"| node_songmapper
node_humanservice -->|"reads and saves"| node_humanrepo
node_humanservice -->|"looks up songs"| node_songrepo
node_humanservice -->|"records play history"| node_recentrepo

click node_webapp "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/app/(app)/page.tsx"
click node_authui "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/features/auth/ui/LoginForm.tsx"
click node_player "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/widgets/music-player/ui/MusicPlayer.tsx"
click node_queue "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/widgets/queue/ui/QueuePanel.tsx"
click node_playlistui "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/app/(app)/playlist/page.tsx"
click node_uploadui "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/features/upload-song/ui/UploadSong.tsx"
click node_authstorage "https://github.com/nobody082/pbl3/blob/main/frontend/web/src/shared/lib/authStorage.ts"
click node_authcontroller "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/AuthController.java"
click node_authservice "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/AuthService.java"
click node_oauthservice "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/CustomOAuth2UserService.java"
click node_humanservice "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/HumanService.java"
click node_artistcontroller "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/ArtistController.java"
click node_songservice "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/Implement/SongServiceImp.java"
click node_songcontract "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/Interface/SongService.java"
click node_songmapper "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/mapper/SongMapper.java"
click node_cloudinaryservice "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/CloudinaryService.java"
click node_humanrepo "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/HumanRepository.java"
click node_userrepo "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/UserRepository.java"
click node_artistrepo "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/ArtistRepository.java"
click node_songrepo "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/SongRepository.java"
click node_recentrepo "https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/RecentPlayedSongRepository.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_authui,node_player,node_queue,node_playlistui,node_uploadui,node_authstorage toneBlue
class node_authcontroller,node_authservice,node_oauthservice,node_humanservice toneAmber
class node_artistcontroller,node_songservice,node_songcontract,node_songmapper,node_cloudinaryservice toneMint
class node_humanrepo,node_userrepo,node_artistrepo,node_songrepo,node_recentrepo toneRose
class node_listener,node_cloudinary,node_google toneIndigo
```

## Components

### Web experience

- [App pages](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/app/(app)/page.tsx): `frontend/web/src/app/(app)/page.tsx`
- [Sign-in forms](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/features/auth/ui/LoginForm.tsx): `frontend/web/src/features/auth/ui/LoginForm.tsx`
- [Music player](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/widgets/music-player/ui/MusicPlayer.tsx): `frontend/web/src/widgets/music-player/ui/MusicPlayer.tsx`
- [Playback queue](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/widgets/queue/ui/QueuePanel.tsx): `frontend/web/src/widgets/queue/ui/QueuePanel.tsx`
- [Playlist views](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/app/(app)/playlist/page.tsx): `frontend/web/src/app/(app)/playlist/page.tsx`
- [Song upload](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/features/upload-song/ui/UploadSong.tsx): `frontend/web/src/features/upload-song/ui/UploadSong.tsx`
- [Session storage](https://github.com/nobody082/pbl3/blob/main/frontend/web/src/shared/lib/authStorage.ts): `frontend/web/src/shared/lib/authStorage.ts`

### Identity and profiles

- [Auth API](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/AuthController.java): `backend/api/src/main/java/com/pbl3/controller/AuthController.java`
- [Account logic](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/AuthService.java): `backend/api/src/main/java/com/pbl3/service/AuthService.java`
- [Google sign-in](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/CustomOAuth2UserService.java): `backend/api/src/main/java/com/pbl3/service/CustomOAuth2UserService.java`
- [Profile and history](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/HumanService.java): `backend/api/src/main/java/com/pbl3/service/HumanService.java`

### Music and discovery

- [Artist API](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/controller/ArtistController.java): `backend/api/src/main/java/com/pbl3/controller/ArtistController.java`
- [Song operations](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/Implement/SongServiceImp.java): `backend/api/src/main/java/com/pbl3/service/Implement/SongServiceImp.java`
- [Discovery operations](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/Interface/SongService.java): `backend/api/src/main/java/com/pbl3/service/Interface/SongService.java`
- [Song responses](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/mapper/SongMapper.java): `backend/api/src/main/java/com/pbl3/mapper/SongMapper.java`
- [Media storage](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/service/CloudinaryService.java): `backend/api/src/main/java/com/pbl3/service/CloudinaryService.java`

### Backend persistence

- [Account records](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/HumanRepository.java): `backend/api/src/main/java/com/pbl3/repository/HumanRepository.java`
- [User records](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/UserRepository.java): `backend/api/src/main/java/com/pbl3/repository/UserRepository.java`
- [Artist records](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/ArtistRepository.java): `backend/api/src/main/java/com/pbl3/repository/ArtistRepository.java`
- [Song records](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/SongRepository.java): `backend/api/src/main/java/com/pbl3/repository/SongRepository.java`
- [Play history](https://github.com/nobody082/pbl3/blob/main/backend/api/src/main/java/com/pbl3/repository/RecentPlayedSongRepository.java): `backend/api/src/main/java/com/pbl3/repository/RecentPlayedSongRepository.java`

### Other components

- **Listener / artist**
- **Cloudinary**
- **Google identity**

## Connections

- Listener / artist → App pages: uses
- Listener / artist → Sign-in forms: signs in
- Listener / artist → Song upload: uploads music
- Sign-in forms → Auth API: submits credentials
- Auth API → Account logic: authenticates
- Account logic → Account records: looks up account
- Account logic → User records: saves user
- Account logic → Artist records: saves artist
- Auth API → Session storage: returns session data
- Auth API → Google sign-in: OAuth callback
- Google sign-in → Google identity: loads identity
- Google sign-in → Account records: finds or updates
- Google sign-in → User records: creates user
- App pages → Music player: opens playback
- App pages → Playlist views: manages playlists
- Music player → Playback queue: controls queue
- Song upload → Artist API: uploads tracks
- Artist API → Media storage: uploads media
- Media storage → Cloudinary: stores media
- Artist API → Song operations: creates song
- Artist API → Artist records: saves artist
- Song operations → Song records: reads and writes
- Song operations → Song responses: maps responses
- Profile and history → Account records: reads and saves
- Profile and history → Song records: looks up songs
- Profile and history → Play history: records play history