# pupupu-core/spotify-clone architecture

> Architecture diagram of the GitHub repository pupupu-core/spotify-clone, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pupupu-core/spotify-clone
- Repository: https://github.com/pupupu-core/spotify-clone

## Overview

#### Purpose and Workspace
Pupufy is a music-streaming system backed by the Jamendo catalog, with account auth, personal uploads, playlists, discovery, search, and audio streaming/download. It is an Nx/pnpm TypeScript monorepo: Angular SPA, NestJS API, Playwright E2E app, and shared API contracts/configuration.

#### Runtime Entry Points
- Web SPA bootstraps from `apps/web/src/main.ts`; application routing and provider setup are centered in `apps/web/src/app/app.routes.ts` and `apps/web/src/app/app.config.ts`.
- NestJS boots from `apps/api/src/main.ts`, composing application dependencies in `apps/api/src/app/app.module.ts`.
- Containers are defined per application (`apps/web/dockerfile`, `apps/api/dockerfile`) and orchestrated with `docker-compose.yml`; web includes Nginx configuration at `apps/web/nginx.conf`.

#### API Boundary and Application Layer
REST v1 controllers validate/transform requests, enforce authentication, and invoke use-case workflows. Authentication is guarded at the gateway boundary and API-domain failures are translated through a common filter.
- Gateway examples: `apps/api/src/app/gateway/rest/v1/auth/auth.controller.ts`, `apps/api/src/app/gateway/rest/v1/track/track.controller.ts`, `apps/api/src/app/gateway/rest/guards/access-token.guard.ts`.
- Workflows orchestrate domain steps for auth, tracks, playlists, search, artists, and albums: `apps/api/src/app/core/workflows/auth/login-user.workflow.ts`, `apps/api/src/app/core/workflows/track/upload-track.workflow.ts`, `apps/api/src/app/core/workflows/playlist/reorder-playlist-entries.workflow.ts`.
- Steps contain focused business operations and domain constraints, such as resolving playlist track references, issuing/revoking sessions, and fetching catalog data: `apps/api/src/app/core/steps/resolve-playlist-track-references.step.ts`, `apps/api/src/app/core/steps/issue-auth-session.step.ts`.

#### Identity, Persistence, and Uploaded Music
Local accounts, identities/sessions, uploaded tracks, playlists, visibility, genres, and playlist entries are persisted through Prisma against PostgreSQL. The schema and migrations are the durable data-model boundary.
- `apps/api/prisma/schema.prisma`
- `apps/api/src/app/infrastructure/prisma/prisma.service.ts`
- `apps/api/src/app/core/steps/upload-track.step/upload-track.step.ts`
Uploaded media is stored separately through an S3-compatible storage abstraction; streaming supports HTTP range behavior at the REST layer.
- `apps/api/src/app/infrastructure/storage/s3-storage.service.ts`
- `apps/api/src/app/gateway/rest/v1/track/track-stream.service.ts`
- `apps/api/src/app/shared/lib/parse-http-range-header.ts`

#### External Catalog and Token Integration
Jamendo is accessed only through its infrastructure client, DTOs, and mappers. Core fetch steps/workflows isolate the rest of the API from Jamendo-specific response shapes and availability errors.
- `apps/api/src/app/infrastructure/jamendo/jamendo.client.ts`
- `apps/api/src/app/infrastructure/jamendo/jamendo.module.ts`
- `apps/api/src/app/infrastructure/jamendo/mappers/track.ts`
Access/refresh token mechanics are likewise infrastructure services consumed by auth workflows and REST guards: `apps/api/src/app/infrastructure/token/auth-token.service.ts`, `apps/api/src/app/gateway/rest/v1/auth/auth-cookie.service.ts`.

#### Web Client Flow
Angular pages and feature components call API services, hold UI/session state in stores, and use interceptors to attach access tokens and refresh on unauthorized responses. Route guards divide guest and authenticated experiences.
- `apps/web/src/app/core/interceptors/access-token/access-token.interceptor.ts`
- `apps/web/src/app/core/stores/auth-session.service.ts`
- `apps/web/src/app/core/guards/auth-guard.ts`
Player services manage browser audio and queue behavior independently of catalog/UI presentation: `apps/web/src/app/features/player/services/html-audio.service.ts`, `apps/web/src/app/features/player/services/track-player.service.ts`. Feature API/store pairs serve artist, album, playlist, and search pages.

#### Shared Contracts and Operational Boundaries
The API and SPA share request/response models, endpoint constants, and utility functions, preventing duplicated HTTP contract definitions.
- `packages/shared/model/src/index.ts`
- `packages/shared/config/src/lib/api/endpoints.ts`
- `packages/shared/utils/src/lib/build-api-path/index.ts`
Swagger initialization exposes API documentation (`apps/api/src/app/infrastructure/swagger/init-swagger.ts`). CI/deployment workflows live under `.github/workflows`; E2E exercises the deployed user-facing routes from `apps/e2e/src/smoke.spec.ts`.

Main entry points: [`apps/api/src/app/gateway/rest/v1/track/track.controller.ts`](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/gateway/rest/v1/track/track.controller.ts) (REST v1 gateway), [`apps/api/src/app/core/workflows/auth/login-user.workflow.ts`](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/core/workflows/auth/login-user.workflow.ts) (Use-case workflows), [`apps/web/src/app/app.routes.ts`](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/app.routes.ts) (Routes & providers), [`apps/api/src/app/app.module.ts`](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/app.module.ts) (Application module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Angular Web"]
  node_web_bootstrap["SPA bootstrap<br/>Angular entry<br/>[main.ts]"]
  node_web_routes["Routes &amp; providers<br/>Angular configuration<br/>[app.routes.ts]"]
  node_web_features["Feature pages<br/>Angular features"]
  node_web_session["Session state &amp; guards<br/>Angular auth"]
  node_web_interceptor["Token interceptor<br/>Angular HTTP"]
  node_web_player["Browser player<br/>Angular audio"]
end

subgraph group_api["NestJS API"]
  node_api_bootstrap["API bootstrap<br/>NestJS entry<br/>[main.ts]"]
  node_api_module["Application module<br/>NestJS composition<br/>[app.module.ts]"]
  node_rest_gateway["REST v1 gateway<br/>Controllers &amp; guards"]
  node_workflows["Use-case workflows<br/>Application core"]
  node_domain_steps["Domain steps<br/>Business operations"]
  node_token_service["Token services<br/>Auth infrastructure"]
  node_prisma[("Prisma persistence<br/>Data access<br/>[prisma.service.ts]")]
  node_jamendo["Jamendo client<br/>Catalog integration<br/>[jamendo.client.ts]"]
  node_swagger["Swagger docs<br/>API documentation<br/>[init-swagger.ts]"]
end

subgraph group_external["Data &amp; External Services"]
  node_postgres[("PostgreSQL<br/>Database<br/>[schema.prisma]")]
  node_object_storage[("S3-compatible storage<br/>Media storage")]
end

node_shared_contracts["Shared API contracts<br/>Shared package<br/>[index.ts]"]
node_containers{{"Container deployment<br/>Docker Compose<br/>[docker-compose.yml]"}}

node_web_bootstrap -->|"initializes"| node_web_routes
node_web_routes -->|"routes to"| node_web_features
node_web_routes -->|"protects routes"| node_web_session
node_web_features -->|"API requests"| node_web_interceptor
node_web_interceptor -->|"REST v1"| node_rest_gateway
node_web_session -->|"access session"| node_web_interceptor
node_web_features -->|"plays tracks"| node_web_player
node_api_bootstrap -->|"starts"| node_api_module
node_api_module -->|"registers"| node_rest_gateway
node_api_module -->|"publishes"| node_swagger
node_rest_gateway -->|"invokes"| node_workflows
node_rest_gateway -->|"auth guard"| node_token_service
node_workflows -->|"composes"| node_domain_steps
node_workflows -->|"issues and revokes sessions"| node_token_service
node_domain_steps -->|"persists domain data"| node_prisma
node_prisma -->|"queries"| node_postgres
node_domain_steps -->|"uploads media"| node_object_storage
node_workflows -->|"fetches catalog"| node_jamendo
node_web_features -.->|"uses contracts"| node_shared_contracts
node_rest_gateway -.->|"uses contracts"| node_shared_contracts
node_containers -->|"serves SPA"| node_web_bootstrap
node_containers -->|"runs API"| node_api_bootstrap

click node_web_bootstrap "https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/main.ts"
click node_web_routes "https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/app.routes.ts"
click node_web_session "https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/core/stores/auth-session.service.ts"
click node_web_interceptor "https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/core/interceptors/access-token/access-token.interceptor.ts"
click node_web_player "https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/features/player/services/track-player.service.ts"
click node_api_bootstrap "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/main.ts"
click node_api_module "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/app.module.ts"
click node_rest_gateway "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/gateway/rest/v1/track/track.controller.ts"
click node_workflows "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/core/workflows/auth/login-user.workflow.ts"
click node_domain_steps "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/core/steps/resolve-playlist-track-references.step.ts"
click node_token_service "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/token/auth-token.service.ts"
click node_prisma "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/prisma/prisma.service.ts"
click node_jamendo "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/jamendo/jamendo.client.ts"
click node_swagger "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/swagger/init-swagger.ts"
click node_postgres "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/prisma/schema.prisma"
click node_object_storage "https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/storage/s3-storage.service.ts"
click node_shared_contracts "https://github.com/pupupu-core/spotify-clone/blob/main/packages/shared/model/src/index.ts"
click node_containers "https://github.com/pupupu-core/spotify-clone/blob/main/docker-compose.yml"

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_web_bootstrap,node_web_routes,node_web_features,node_web_session,node_web_interceptor,node_web_player toneBlue
class node_api_bootstrap,node_api_module,node_rest_gateway,node_workflows,node_domain_steps,node_token_service,node_prisma,node_jamendo,node_swagger toneAmber
class node_postgres,node_object_storage toneMint
class node_shared_contracts,node_containers toneNeutral
```

## Components

### Angular Web

- [SPA bootstrap](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/main.ts): Angular entry · `apps/web/src/main.ts`
- [Routes & providers](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/app.routes.ts): Angular configuration · `apps/web/src/app/app.routes.ts`
- **Feature pages**: Angular features · Artist, album, playlist, search, and account UI.
- [Session state & guards](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/core/stores/auth-session.service.ts): Angular auth · `apps/web/src/app/core/stores/auth-session.service.ts`
- [Token interceptor](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/core/interceptors/access-token/access-token.interceptor.ts): Angular HTTP · Attaches access tokens and refreshes unauthorized requests. · `apps/web/src/app/core/interceptors/access-token/access-token.interceptor.ts`
- [Browser player](https://github.com/pupupu-core/spotify-clone/blob/main/apps/web/src/app/features/player/services/track-player.service.ts): Angular audio · Manages HTML audio playback and queue behavior. · `apps/web/src/app/features/player/services/track-player.service.ts`

### NestJS API

- [API bootstrap](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/main.ts): NestJS entry · `apps/api/src/main.ts`
- [Application module](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/app.module.ts): NestJS composition · `apps/api/src/app/app.module.ts`
- [REST v1 gateway](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/gateway/rest/v1/track/track.controller.ts): Controllers & guards · Validates requests, enforces access tokens, and serves range streaming. · `apps/api/src/app/gateway/rest/v1/track/track.controller.ts`
- [Use-case workflows](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/core/workflows/auth/login-user.workflow.ts): Application core · Orchestrates auth, catalog, upload, playlist, and search operations. · `apps/api/src/app/core/workflows/auth/login-user.workflow.ts`
- [Domain steps](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/core/steps/resolve-playlist-track-references.step.ts): Business operations · Focused constraints, session operations, and reference resolution. · `apps/api/src/app/core/steps/resolve-playlist-track-references.step.ts`
- [Token services](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/token/auth-token.service.ts): Auth infrastructure · `apps/api/src/app/infrastructure/token/auth-token.service.ts`
- [Prisma persistence](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/prisma/prisma.service.ts): Data access · `apps/api/src/app/infrastructure/prisma/prisma.service.ts`
- [Jamendo client](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/jamendo/jamendo.client.ts): Catalog integration · Maps catalog responses behind an infrastructure boundary. · `apps/api/src/app/infrastructure/jamendo/jamendo.client.ts`
- [Swagger docs](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/swagger/init-swagger.ts): API documentation · `apps/api/src/app/infrastructure/swagger/init-swagger.ts`

### Data & External Services

- [PostgreSQL](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/prisma/schema.prisma): Database · Accounts, sessions, uploads, playlists, genres, and entries. · `apps/api/prisma/schema.prisma`
- [S3-compatible storage](https://github.com/pupupu-core/spotify-clone/blob/main/apps/api/src/app/infrastructure/storage/s3-storage.service.ts): Media storage · Stores uploaded audio objects. · `apps/api/src/app/infrastructure/storage/s3-storage.service.ts`

### Other components

- [Shared API contracts](https://github.com/pupupu-core/spotify-clone/blob/main/packages/shared/model/src/index.ts): Shared package · Models, endpoint constants, and API path utilities. · `packages/shared/model/src/index.ts`
- [Container deployment](https://github.com/pupupu-core/spotify-clone/blob/main/docker-compose.yml): Docker Compose · Runs web and API containers; web is served by Nginx. · `docker-compose.yml`

## Connections

- SPA bootstrap → Routes & providers: initializes
- Routes & providers → Feature pages: routes to
- Routes & providers → Session state & guards: protects routes
- Feature pages → Token interceptor: API requests
- Token interceptor → REST v1 gateway: REST v1
- Session state & guards → Token interceptor: access session
- Feature pages → Browser player: plays tracks
- API bootstrap → Application module: starts
- Application module → REST v1 gateway: registers
- Application module → Swagger docs: publishes
- REST v1 gateway → Use-case workflows: invokes
- REST v1 gateway → Token services: auth guard
- Use-case workflows → Domain steps: composes
- Use-case workflows → Token services: issues and revokes sessions
- Domain steps → Prisma persistence: persists domain data
- Prisma persistence → PostgreSQL: queries
- Domain steps → S3-compatible storage: uploads media
- Use-case workflows → Jamendo client: fetches catalog
- Feature pages → Shared API contracts: uses contracts
- REST v1 gateway → Shared API contracts: uses contracts
- Container deployment → SPA bootstrap: serves SPA
- Container deployment → API bootstrap: runs API