# blackdevil-com/patta-kelu architecture

> Architecture diagram of the GitHub repository blackdevil-com/patta-kelu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blackdevil-com/patta-kelu
- Repository: https://github.com/blackdevil-com/patta-kelu

## Overview

Patta Kelu is a full-stack music-streaming platform: listeners browse or search a catalog, select tracks, and stream audio; they can also manage playlists and a personal library. The React client calls the Spring REST API, whose services implement catalog, account, library, streaming, recommendation, and administration capabilities over relational data and file storage. The graph preserves documented major features, but several service and controller relationships are represented at directory level because their source was not sampled.

Main entry points: [`backend/src/main/java/com/pattakelu/controller`](https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/controller) (REST endpoints), [`backend/src/main/java/com/pattakelu/repository`](https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/repository) (Data repositories), [`backend/src/main/java/com/pattakelu/storage/StorageService.java`](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/StorageService.java) (Storage interface), [`frontend/src/App.tsx`](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/App.tsx) (Web app routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Listener application"]
  node_webapp["Web app routing<br/>[App.tsx]"]
  node_searchpage["Search and browse<br/>[SearchPage.tsx]"]
  node_player["Audio player<br/>[useAudioPlayer.ts]"]
  node_httpclient["API client<br/>[client.ts]"]
  node_authstate["Auth state<br/>[authStore.ts]"]
end

subgraph group_api["Backend capabilities"]
  node_controllers["REST endpoints"]
  node_search["Catalog search<br/>[SearchService.java]"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_admin["Administration<br/>[AdminService.java]"]
  node_domainservices["Catalog and listener services"]
  node_streaming["Audio streaming<br/>[StreamService.java]"]
  node_recommendations["Recommendations"]
end

subgraph group_data["Data and media"]
  node_repositories["Data repositories"]
  node_catalogmapper["Catalog mapping<br/>[CatalogMapper.java]"]
  node_storageinterface["Storage interface"]
  node_localstorage["Local storage"]
  node_supabase["Supabase storage"]
  node_database[("Relational database")]
end

subgraph group_security["Identity and access"]
  node_jwt["JWT services<br/>[JwtService.java]"]
end

node_listener(("Listener or admin"))

node_listener -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_searchpage
node_searchpage -->|"requests through"| node_httpclient
node_player -->|"requests through"| node_httpclient
node_webapp -->|"checks auth"| node_authstate
node_httpclient -->|"calls REST API"| node_controllers
node_controllers -.->|"delegates search"| node_search
node_controllers -->|"delegates auth"| node_auth
node_controllers -.->|"delegates admin"| node_admin
node_controllers -.->|"handles domain actions"| node_domainservices
node_controllers -.->|"requests streams"| node_streaming
node_search -->|"queries catalog"| node_repositories
node_search -->|"maps results"| node_catalogmapper
node_auth -->|"reads and writes"| node_repositories
node_auth -->|"creates tokens"| node_jwt
node_admin -->|"manages records"| node_repositories
node_admin -->|"deletes media"| node_storageinterface
node_repositories -.->|"persists entities"| node_database
node_storageinterface -->|"implemented by"| node_localstorage
node_storageinterface -->|"implemented by"| node_supabase
node_streaming -.->|"reads audio ranges"| node_storageinterface
node_recommendations -.->|"uses catalog data"| node_repositories

click node_webapp "https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/App.tsx"
click node_searchpage "https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/pages/SearchPage.tsx"
click node_player "https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/hooks/useAudioPlayer.ts"
click node_httpclient "https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/api/client.ts"
click node_authstate "https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/stores/authStore.ts"
click node_controllers "https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/controller"
click node_search "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/SearchService.java"
click node_auth "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/AuthService.java"
click node_admin "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/AdminService.java"
click node_domainservices "https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/service"
click node_streaming "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/StreamService.java"
click node_recommendations "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/RecommendationService.java"
click node_repositories "https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/repository"
click node_catalogmapper "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/mapper/CatalogMapper.java"
click node_storageinterface "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/StorageService.java"
click node_localstorage "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/LocalStorageService.java"
click node_supabase "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/SupabaseStorageService.java"
click node_jwt "https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/security/JwtService.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_searchpage,node_player,node_httpclient,node_authstate toneBlue
class node_controllers,node_search,node_auth,node_admin,node_domainservices,node_streaming,node_recommendations toneAmber
class node_repositories,node_catalogmapper,node_storageinterface,node_localstorage,node_supabase,node_database toneMint
class node_jwt toneRose
class node_listener toneIndigo
```

## Components

### Listener application

- [Web app routing](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Search and browse](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/pages/SearchPage.tsx): `frontend/src/pages/SearchPage.tsx`
- [Audio player](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/hooks/useAudioPlayer.ts): `frontend/src/hooks/useAudioPlayer.ts`
- [API client](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Auth state](https://github.com/blackdevil-com/patta-kelu/blob/main/frontend/src/stores/authStore.ts): `frontend/src/stores/authStore.ts`

### Backend capabilities

- [REST endpoints](https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/controller): `backend/src/main/java/com/pattakelu/controller`
- [Catalog search](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/SearchService.java): `backend/src/main/java/com/pattakelu/service/SearchService.java`
- [Authentication](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/AuthService.java): `backend/src/main/java/com/pattakelu/service/AuthService.java`
- [Administration](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/AdminService.java): `backend/src/main/java/com/pattakelu/service/AdminService.java`
- [Catalog and listener services](https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/service): `backend/src/main/java/com/pattakelu/service`
- [Audio streaming](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/StreamService.java): `backend/src/main/java/com/pattakelu/service/StreamService.java`
- [Recommendations](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/service/RecommendationService.java): `backend/src/main/java/com/pattakelu/service/RecommendationService.java`

### Data and media

- [Data repositories](https://github.com/blackdevil-com/patta-kelu/tree/main/backend/src/main/java/com/pattakelu/repository): `backend/src/main/java/com/pattakelu/repository`
- [Catalog mapping](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/mapper/CatalogMapper.java): `backend/src/main/java/com/pattakelu/mapper/CatalogMapper.java`
- [Storage interface](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/StorageService.java): `backend/src/main/java/com/pattakelu/storage/StorageService.java`
- [Local storage](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/LocalStorageService.java): `backend/src/main/java/com/pattakelu/storage/LocalStorageService.java`
- [Supabase storage](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/storage/SupabaseStorageService.java): `backend/src/main/java/com/pattakelu/storage/SupabaseStorageService.java`
- **Relational database**

### Identity and access

- [JWT services](https://github.com/blackdevil-com/patta-kelu/blob/main/backend/src/main/java/com/pattakelu/security/JwtService.java): `backend/src/main/java/com/pattakelu/security/JwtService.java`

### Other components

- **Listener or admin**

## Connections

- Listener or admin → Web app routing: uses
- Web app routing → Search and browse: routes to (evidence: `frontend/src/App.tsx`)
- Search and browse → API client: requests through (evidence: `frontend/src/pages/SearchPage.tsx`)
- Audio player → API client: requests through (evidence: `frontend/src/hooks/useAudioPlayer.ts`)
- Web app routing → Auth state: checks auth (evidence: `frontend/src/App.tsx`)
- API client → REST endpoints: calls REST API
- REST endpoints → Catalog search: delegates search
- REST endpoints → Authentication: delegates auth (evidence: `backend/src/main/java/com/pattakelu/controller/AuthController.java`)
- REST endpoints → Administration: delegates admin (evidence: `backend/src/main/java/com/pattakelu/controller/AdminController.java`)
- REST endpoints → Catalog and listener services: handles domain actions (evidence: `backend/src/main/java/com/pattakelu/controller/AuthController.java`)
- REST endpoints → Audio streaming: requests streams
- Catalog search → Data repositories: queries catalog (evidence: `backend/src/main/java/com/pattakelu/service/SearchService.java`)
- Catalog search → Catalog mapping: maps results (evidence: `backend/src/main/java/com/pattakelu/service/SearchService.java`)
- Authentication → Data repositories: reads and writes (evidence: `backend/src/main/java/com/pattakelu/service/AuthService.java`)
- Authentication → JWT services: creates tokens (evidence: `backend/src/main/java/com/pattakelu/service/AuthService.java`)
- Administration → Data repositories: manages records (evidence: `backend/src/main/java/com/pattakelu/service/AdminService.java`)
- Administration → Storage interface: deletes media (evidence: `backend/src/main/java/com/pattakelu/service/AdminService.java`)
- Data repositories → Relational database: persists entities
- Storage interface → Local storage: implemented by (evidence: `backend/src/main/java/com/pattakelu/configuration/StorageConfiguration.java`)
- Storage interface → Supabase storage: implemented by (evidence: `backend/src/main/java/com/pattakelu/configuration/StorageConfiguration.java`)
- Audio streaming → Storage interface: reads audio ranges
- Recommendations → Data repositories: uses catalog data
