# th7mo/trackshop-api architecture

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

- Interactive diagram: https://gitdiagram.com/th7mo/trackshop-api
- Repository: https://github.com/th7mo/trackshop-api

## Overview

This is a Spring-based music-store backend: clients authenticate, browse track and genre catalogs, manage customer accounts, and add or remove tracks in a shopping cart. The main domain stages are authentication, catalog access, customer management, and cart operations, with repository interfaces and JPA entities forming the persistence layer. The README only notes a Docker Compose requirement and documents no product behavior; the workflow and links here rely on the indexed source references and sampled code, so unsampled details are omitted.

Main entry points: [`src/main/java/com/th7mo/customer/CustomerService.java`](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerService.java) (Customer Service), [`src/main/java/com/th7mo/shopping_cart/ShoppingCart.java`](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCart.java) (Cart Model), [`src/main/java/com/th7mo/auth/DatabaseSeeder.java`](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/DatabaseSeeder.java) (Database Seeder), [`src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java`](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java) (Cart Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_auth["Authentication"]
  node_auth_api["Auth API"]
  node_jwt["JWT Utilities<br/>[JwtUtil.java]"]
  node_security["Security Configuration"]
  node_jwt_filter["Token Filter"]
  node_auth_entry["Auth Entry Point"]
  node_user_details["User Details Service"]
end

subgraph group_customer["Customer Accounts"]
  node_customer_api["Customer API"]
  node_customer_service["Customer Service"]
  node_customer_repository["Customer Repository"]
  node_customer_model["Customer Model<br/>[Customer.java]"]
  node_role_model["Customer Roles<br/>[Role.java]"]
end

subgraph group_catalog["Music Catalog"]
  node_track_api["Track API"]
  node_track_service["Track Service<br/>[TrackService.java]"]
  node_track_repository["Track Repository"]
  node_track_model["Track Model<br/>[Track.java]"]
  node_genre_api["Genre API"]
  node_genre_service["Genre Service<br/>[GenreService.java]"]
  node_genre_repository["Genre Repository"]
  node_genre_model["Genre Model<br/>[Genre.java]"]
end

subgraph group_cart["Shopping Cart"]
  node_cart_api["Cart API"]
  node_cart_service["Cart Service"]
  node_cart_model["Cart Model<br/>[ShoppingCart.java]"]
  node_cart_item["Cart Item"]
end

node_client(("API Client"))
node_seeder["Database Seeder"]

node_client -->|"requests auth"| node_auth_api
node_auth_api -->|"manages accounts"| node_customer_service
node_auth_api -->|"creates tokens"| node_jwt
node_security -->|"registers filter"| node_jwt_filter
node_security -->|"configures entry"| node_auth_entry
node_security -->|"configures lookup"| node_user_details
node_jwt_filter -->|"validates tokens"| node_jwt
node_jwt_filter -->|"loads user"| node_user_details
node_user_details -->|"finds customer"| node_customer_repository
node_customer_api -->|"delegates requests"| node_customer_service
node_customer_service -->|"reads and saves"| node_customer_repository
node_customer_service -->|"creates customer"| node_customer_model
node_customer_service -->|"initializes cart"| node_cart_model
node_customer_model -->|"stores role"| node_role_model
node_customer_model -->|"owns cart"| node_cart_model
node_track_api -->|"delegates requests"| node_track_service
node_track_service -->|"reads and writes"| node_track_repository
node_track_repository -->|"persists tracks"| node_track_model
node_genre_api -->|"delegates requests"| node_genre_service
node_genre_service -->|"reads and writes"| node_genre_repository
node_genre_repository -->|"persists genres"| node_genre_model
node_cart_api -->|"delegates requests"| node_cart_service
node_cart_api -->|"resolves customer"| node_customer_service
node_cart_service -->|"loads and saves"| node_customer_repository
node_cart_service -->|"loads track"| node_track_repository
node_cart_service -->|"updates items"| node_cart_model
node_cart_model -->|"contains items"| node_cart_item
node_cart_item -->|"references track"| node_track_model
node_seeder -->|"seeds customers"| node_customer_repository
node_seeder -->|"seeds tracks"| node_track_repository
node_seeder -->|"creates customer data"| node_customer_model
node_seeder -->|"creates cart data"| node_cart_model

click node_auth_api "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthController.java"
click node_jwt "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/JwtUtil.java"
click node_security "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/WebSecurityConfig.java"
click node_jwt_filter "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthTokenFilter.java"
click node_auth_entry "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthEntryPointJwt.java"
click node_user_details "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomUserDetailsService.java"
click node_customer_api "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerController.java"
click node_customer_service "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerService.java"
click node_customer_repository "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerRepository.java"
click node_customer_model "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/Customer.java"
click node_role_model "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/Role.java"
click node_track_api "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackController.java"
click node_track_service "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackService.java"
click node_track_repository "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackRepository.java"
click node_track_model "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/Track.java"
click node_genre_api "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreController.java"
click node_genre_service "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreService.java"
click node_genre_repository "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreRepository.java"
click node_genre_model "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/Genre.java"
click node_cart_api "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartController.java"
click node_cart_service "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java"
click node_cart_model "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCart.java"
click node_cart_item "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartItem.java"
click node_seeder "https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/DatabaseSeeder.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_auth_api,node_jwt,node_security,node_jwt_filter,node_auth_entry,node_user_details,node_client toneBlue
class node_customer_api,node_customer_service,node_customer_repository,node_customer_model,node_role_model,node_seeder toneAmber
class node_track_api,node_track_service,node_track_repository,node_track_model,node_genre_api,node_genre_service,node_genre_repository,node_genre_model toneMint
class node_cart_api,node_cart_service,node_cart_model,node_cart_item toneRose
```

## Components

### Authentication

- [Auth API](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthController.java): `src/main/java/com/th7mo/auth/AuthController.java`
- [JWT Utilities](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/JwtUtil.java): `src/main/java/com/th7mo/auth/JwtUtil.java`
- [Security Configuration](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/WebSecurityConfig.java): `src/main/java/com/th7mo/auth/WebSecurityConfig.java`
- [Token Filter](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthTokenFilter.java): `src/main/java/com/th7mo/auth/AuthTokenFilter.java`
- [Auth Entry Point](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/AuthEntryPointJwt.java): `src/main/java/com/th7mo/auth/AuthEntryPointJwt.java`
- [User Details Service](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomUserDetailsService.java): `src/main/java/com/th7mo/customer/CustomUserDetailsService.java`

### Customer Accounts

- [Customer API](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerController.java): `src/main/java/com/th7mo/customer/CustomerController.java`
- [Customer Service](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerService.java): `src/main/java/com/th7mo/customer/CustomerService.java`
- [Customer Repository](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/CustomerRepository.java): `src/main/java/com/th7mo/customer/CustomerRepository.java`
- [Customer Model](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/Customer.java): `src/main/java/com/th7mo/customer/Customer.java`
- [Customer Roles](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/customer/Role.java): `src/main/java/com/th7mo/customer/Role.java`

### Music Catalog

- [Track API](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackController.java): `src/main/java/com/th7mo/track/TrackController.java`
- [Track Service](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackService.java): `src/main/java/com/th7mo/track/TrackService.java`
- [Track Repository](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/TrackRepository.java): `src/main/java/com/th7mo/track/TrackRepository.java`
- [Track Model](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/track/Track.java): `src/main/java/com/th7mo/track/Track.java`
- [Genre API](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreController.java): `src/main/java/com/th7mo/genre/GenreController.java`
- [Genre Service](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreService.java): `src/main/java/com/th7mo/genre/GenreService.java`
- [Genre Repository](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/GenreRepository.java): `src/main/java/com/th7mo/genre/GenreRepository.java`
- [Genre Model](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/genre/Genre.java): `src/main/java/com/th7mo/genre/Genre.java`

### Shopping Cart

- [Cart API](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartController.java): `src/main/java/com/th7mo/shopping_cart/ShoppingCartController.java`
- [Cart Service](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java): `src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java`
- [Cart Model](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCart.java): `src/main/java/com/th7mo/shopping_cart/ShoppingCart.java`
- [Cart Item](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/shopping_cart/ShoppingCartItem.java): `src/main/java/com/th7mo/shopping_cart/ShoppingCartItem.java`

### Other components

- **API Client**
- [Database Seeder](https://github.com/th7mo/trackshop-api/blob/main/src/main/java/com/th7mo/auth/DatabaseSeeder.java): `src/main/java/com/th7mo/auth/DatabaseSeeder.java`

## Connections

- API Client → Auth API: requests auth (evidence: `src/main/java/com/th7mo/auth/AuthController.java`)
- Auth API → Customer Service: manages accounts (evidence: `src/main/java/com/th7mo/auth/AuthController.java`)
- Auth API → JWT Utilities: creates tokens (evidence: `src/main/java/com/th7mo/auth/AuthController.java`)
- Security Configuration → Token Filter: registers filter (evidence: `src/main/java/com/th7mo/auth/WebSecurityConfig.java`)
- Security Configuration → Auth Entry Point: configures entry (evidence: `src/main/java/com/th7mo/auth/WebSecurityConfig.java`)
- Security Configuration → User Details Service: configures lookup (evidence: `src/main/java/com/th7mo/auth/WebSecurityConfig.java`)
- Token Filter → JWT Utilities: validates tokens (evidence: `src/main/java/com/th7mo/auth/AuthTokenFilter.java`)
- Token Filter → User Details Service: loads user (evidence: `src/main/java/com/th7mo/auth/AuthTokenFilter.java`)
- User Details Service → Customer Repository: finds customer (evidence: `src/main/java/com/th7mo/customer/CustomUserDetailsService.java`)
- Customer API → Customer Service: delegates requests (evidence: `src/main/java/com/th7mo/customer/CustomerController.java`)
- Customer Service → Customer Repository: reads and saves (evidence: `src/main/java/com/th7mo/customer/CustomerService.java`)
- Customer Service → Customer Model: creates customer (evidence: `src/main/java/com/th7mo/customer/CustomerService.java`)
- Customer Service → Cart Model: initializes cart (evidence: `src/main/java/com/th7mo/customer/CustomerService.java`)
- Customer Model → Customer Roles: stores role (evidence: `src/main/java/com/th7mo/customer/Customer.java`)
- Customer Model → Cart Model: owns cart (evidence: `src/main/java/com/th7mo/customer/Customer.java`)
- Track API → Track Service: delegates requests (evidence: `src/main/java/com/th7mo/track/TrackController.java`)
- Track Service → Track Repository: reads and writes (evidence: `src/main/java/com/th7mo/track/TrackService.java`)
- Track Repository → Track Model: persists tracks (evidence: `src/main/java/com/th7mo/track/TrackRepository.java`)
- Genre API → Genre Service: delegates requests (evidence: `src/main/java/com/th7mo/genre/GenreController.java`)
- Genre Service → Genre Repository: reads and writes (evidence: `src/main/java/com/th7mo/genre/GenreService.java`)
- Genre Repository → Genre Model: persists genres (evidence: `src/main/java/com/th7mo/genre/GenreRepository.java`)
- Cart API → Cart Service: delegates requests (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartController.java`)
- Cart API → Customer Service: resolves customer (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartController.java`)
- Cart Service → Customer Repository: loads and saves (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java`)
- Cart Service → Track Repository: loads track (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java`)
- Cart Service → Cart Model: updates items (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartService.java`)
- Cart Model → Cart Item: contains items (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCart.java`)
- Cart Item → Track Model: references track (evidence: `src/main/java/com/th7mo/shopping_cart/ShoppingCartItem.java`)
- Database Seeder → Customer Repository: seeds customers (evidence: `src/main/java/com/th7mo/auth/DatabaseSeeder.java`)
- Database Seeder → Track Repository: seeds tracks (evidence: `src/main/java/com/th7mo/auth/DatabaseSeeder.java`)
- Database Seeder → Customer Model: creates customer data (evidence: `src/main/java/com/th7mo/auth/DatabaseSeeder.java`)
- Database Seeder → Cart Model: creates cart data (evidence: `src/main/java/com/th7mo/auth/DatabaseSeeder.java`)