salixandom/spotify_isd_backend

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.