# salixandom/spotify_isd_backend architecture

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

- Interactive diagram: https://gitdiagram.com/salixandom/spotify_isd_backend
- Repository: https://github.com/salixandom/spotify_isd_backend

## Overview

1. This repository is a Django REST Framework microservices backend for a Spotify-like product. The top-level request path is: client API calls → Traefik gateway → one of four Django services → PostgreSQL. Traefik is the main entry boundary and routes by path prefix, so the public API is unified even though the implementation is split.

2. The system is divided into four service boundaries:
   - Auth service on 8001 for identity and JWT issuance/validation.
   - Core service on 8002 for the main music domain: playlists, tracks, search, and listening history.
   - Collaboration service on 8003 for shared playlist access, collaborators, and share links.
   - Playback service on 8004 for queue state, now-playing, and playback synchronization.

3. Auth is the trust anchor for the rest of the system. It provides registration, login, user/profile management, password reset, and JWT token handling. Other services are expected to consume these tokens rather than reimplement auth logic, which makes auth a cross-cutting dependency boundary.

4. Core is the largest bounded context and is internally split into separate Django apps: `playlistapp`, `trackapp`, `searchapp`, and `historyapp`. That means the “core” service is really a cluster of related subdomains sharing one runtime and database connection. The service also contains utility layers for response formatting, service clients, and shared mixins.

5. The core service shows an important internal data flow: user actions are captured in `historyapp`, where middleware, handlers, and action extractors translate request behavior into persisted user actions and undo/redo-related state. This makes history a behavioral subsystem rather than just a read-only audit log.

6. Collaboration is split into `collabapp` and `shareapp`, which suggests two distinct responsibilities: collaborator membership/permissions and share-link generation/usage tracking. The presence of a `usage_count` migration in `shareapp` implies link analytics or access tracking is part of the design. This service likely coordinates with core playlist data but keeps sharing logic isolated.

7. Playback is intentionally isolated in its own service and app, with a smaller surface area than core. Its responsibility is playback state, queue management, and “now playing” style synchronization rather than track metadata. This separation helps keep time-sensitive playback concerns independent from playlist and search CRUD.

8. Persistence is centered on PostgreSQL, with each service owning its own Django models and migrations. The repository includes many app-specific migrations and seed commands, so the database schema is managed per service boundary even though the runtime is deployed as a composed stack. The repo also includes seeding scripts at the root for bootstrapping test/demo data.

9. Deployment is container-first. Each service has its own Dockerfile and entrypoint, while `docker-compose.yml` and `docker-compose.prod.yml` orchestrate the full stack locally and in production-like environments. The README also references Render deployment, indicating the stack can be published behind the same gateway pattern outside local Docker Compose.

10. The repo has strong operational support files: health checks, deployment checklists, schema docs, migration workflows, and performance notes. This is reflected in code by service-specific tests, integration suites, and a CI workflow under GitHub Actions. For architecture diagrams, it is useful to show not just runtime services but also the supporting delivery pipeline: source control → CI/test → containerized deployment.

11. A good diagram should emphasize these boundaries: gateway, four independently deployable services, shared PostgreSQL backing store, and the auth-token trust relationship that links the services. The most important internal decomposition is inside Core, because it aggregates playlist, track, search, and history into one service while Collaboration and Playback remain separate concerns.

Main entry points: [`services/core`](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core) (Core svc), [`services/auth`](https://github.com/salixandom/spotify_isd_backend/tree/main/services/auth) (Auth svc), [`docker-compose.prod.yml`](https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.prod.yml) (Compose), [`docker-compose.yml`](https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.yml) (Traefik)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_client(("Client API<br/>external client"))
  node_traefik{{"Traefik<br/>gateway<br/>[docker-compose.yml]"}}
  node_ci["CI<br/>pipeline<br/>[ci.yml]"]
  node_compose["Compose<br/>orchestration"]
end

subgraph group_services["Services"]
  node_authsvc["Auth svc<br/>django service"]
  node_authapp["Auth app<br/>domain app"]
  node_coresvc["Core svc<br/>django service"]
  node_playlistapp["Playlists<br/>domain app"]
  node_trackapp["Tracks<br/>domain app"]
  node_searchapp["Search<br/>domain app"]
  node_historyapp["History<br/>behavior app"]
  node_collabsvc["Collab svc<br/>django service"]
  node_collabapp["Members<br/>domain app"]
  node_shareapp["Shares<br/>domain app"]
  node_playbacksvc["Playback svc<br/>django service"]
  node_playbackapp["Playback<br/>state app"]
end

subgraph group_data["Data"]
  node_postgres[("PostgreSQL<br/>database")]
  node_seed["Seed data<br/>bootstrap<br/>[seed_database.py]"]
end

node_client -->|"API requests"| node_traefik
node_traefik -->|"/auth"| node_authsvc
node_traefik -->|"/core"| node_coresvc
node_traefik -->|"/collab"| node_collabsvc
node_traefik -->|"/playback"| node_playbacksvc
node_authsvc -->|"hosts"| node_authapp
node_coresvc -->|"contains"| node_playlistapp
node_coresvc -->|"contains"| node_trackapp
node_coresvc -->|"contains"| node_searchapp
node_coresvc -->|"contains"| node_historyapp
node_collabsvc -->|"contains"| node_collabapp
node_collabsvc -->|"contains"| node_shareapp
node_playbacksvc -->|"hosts"| node_playbackapp
node_authsvc -->|"reads/writes"| node_postgres
node_coresvc -->|"reads/writes"| node_postgres
node_collabsvc -->|"reads/writes"| node_postgres
node_playbacksvc -->|"reads/writes"| node_postgres
node_authsvc -.->|"JWT trust"| node_coresvc
node_authsvc -.->|"JWT trust"| node_collabsvc
node_authsvc -.->|"JWT trust"| node_playbacksvc
node_ci -->|"build/test"| node_compose
node_compose -->|"starts"| node_traefik
node_compose -->|"starts"| node_authsvc
node_compose -->|"starts"| node_coresvc
node_compose -->|"starts"| node_collabsvc
node_compose -->|"starts"| node_playbacksvc
node_seed -->|"bootstrap"| node_postgres

click node_traefik "https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.yml"
click node_ci "https://github.com/salixandom/spotify_isd_backend/blob/main/.github/workflows/ci.yml"
click node_compose "https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.prod.yml"
click node_seed "https://github.com/salixandom/spotify_isd_backend/blob/main/scripts/seed_database.py"
click node_authsvc "https://github.com/salixandom/spotify_isd_backend/tree/main/services/auth"
click node_authapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/auth/authapp"
click node_coresvc "https://github.com/salixandom/spotify_isd_backend/tree/main/services/core"
click node_playlistapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/playlistapp"
click node_trackapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/trackapp"
click node_searchapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/searchapp"
click node_historyapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/historyapp"
click node_collabsvc "https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration"
click node_collabapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration/collabapp"
click node_shareapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration/shareapp"
click node_playbacksvc "https://github.com/salixandom/spotify_isd_backend/tree/main/services/playback"
click node_playbackapp "https://github.com/salixandom/spotify_isd_backend/tree/main/services/playback/playbackapp"

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_client,node_traefik,node_ci,node_compose toneBlue
class node_authsvc,node_authapp,node_coresvc,node_playlistapp,node_trackapp,node_searchapp,node_historyapp,node_collabsvc,node_collabapp,node_shareapp,node_playbacksvc,node_playbackapp toneAmber
class node_postgres,node_seed toneMint
```

## Components

### Delivery

Gateway, CI, and container orchestration

- **Client API**: external client · Public API consumers
- [Traefik](https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.yml): gateway · Unified HTTP entry and path router · `docker-compose.yml`
- [CI](https://github.com/salixandom/spotify_isd_backend/blob/main/.github/workflows/ci.yml): pipeline · GitHub Actions test and build workflow · `.github/workflows/ci.yml`
- [Compose](https://github.com/salixandom/spotify_isd_backend/blob/main/docker-compose.prod.yml): orchestration · Local and production stack assembly · `docker-compose.prod.yml`

### Services

Independent Django runtimes and their major apps

- [Auth svc](https://github.com/salixandom/spotify_isd_backend/tree/main/services/auth): django service · Identity, registration, login, and JWT boundary · `services/auth`
- [Auth app](https://github.com/salixandom/spotify_isd_backend/tree/main/services/auth/authapp): domain app · User, token, and password management · `services/auth/authapp`
- [Core svc](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core): django service · Main music domain runtime · `services/core`
- [Playlists](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/playlistapp): domain app · Playlist lifecycle and social playlist features · `services/core/playlistapp`
- [Tracks](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/trackapp): domain app · Track metadata and track-focused operations · `services/core/trackapp`
- [Search](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/searchapp): domain app · Discovery and lookup across music data · `services/core/searchapp`
- [History](https://github.com/salixandom/spotify_isd_backend/tree/main/services/core/historyapp): behavior app · Request actions, undo/redo state, and activity capture · `services/core/historyapp`
- [Collab svc](https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration): django service · Shared playlist access and link sharing runtime · `services/collaboration`
- [Members](https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration/collabapp): domain app · Collaborator membership and permissions · `services/collaboration/collabapp`
- [Shares](https://github.com/salixandom/spotify_isd_backend/tree/main/services/collaboration/shareapp): domain app · Share links and usage tracking · `services/collaboration/shareapp`
- [Playback svc](https://github.com/salixandom/spotify_isd_backend/tree/main/services/playback): django service · Queue state and playback synchronization runtime · `services/playback`
- [Playback](https://github.com/salixandom/spotify_isd_backend/tree/main/services/playback/playbackapp): state app · Now-playing, queue, and sync state · `services/playback/playbackapp`

### Data

Shared persistence and bootstrapping

- **PostgreSQL**: database · Shared relational persistence layer
- [Seed data](https://github.com/salixandom/spotify_isd_backend/blob/main/scripts/seed_database.py): bootstrap · Repository-level database seeding scripts · `scripts/seed_database.py`

## Connections

- Client API → Traefik: API requests · Unified public API entrypoint
- Traefik → Auth svc: /auth · Routes identity and token traffic
- Traefik → Core svc: /core · Routes music-domain traffic
- Traefik → Collab svc: /collab · Routes collaboration traffic
- Traefik → Playback svc: /playback · Routes playback traffic
- Auth svc → Auth app: hosts · Auth service runtime centers on authapp
- Core svc → Playlists: contains · Core service subdomain
- Core svc → Tracks: contains · Core service subdomain
- Core svc → Search: contains · Core service subdomain
- Core svc → History: contains · Core service behavioral subsystem
- Collab svc → Members: contains · Collaboration membership logic
- Collab svc → Shares: contains · Share-link logic and tracking
- Playback svc → Playback: hosts · Playback state runtime
- Auth svc → PostgreSQL: reads/writes · Owns identity data
- Core svc → PostgreSQL: reads/writes · Owns core domain data
- Collab svc → PostgreSQL: reads/writes · Owns collaboration data
- Playback svc → PostgreSQL: reads/writes · Owns playback state data
- Auth svc → Core svc: JWT trust · Core validates tokens issued by auth
- Auth svc → Collab svc: JWT trust · Collaboration validates tokens issued by auth
- Auth svc → Playback svc: JWT trust · Playback validates tokens issued by auth
- CI → Compose: build/test · CI supports containerized delivery
- Compose → Traefik: starts · Composes gateway and services
- Compose → Auth svc: starts · Runs auth service container
- Compose → Core svc: starts · Runs core service container
- Compose → Collab svc: starts · Runs collaboration service container
- Compose → Playback svc: starts · Runs playback service container
- Seed data → PostgreSQL: bootstrap · Initializes demo/test data