pupupu-core/spotify-clone

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.