데이터 흐름 중심으로 설계한 음악 서비스 아키텍처 (도메인·ERD·API)

Miro (전체 흐름)

프로젝트 초기 단계에서 도메인 구조와 데이터 흐름을 시각적으로 정리하기 위해 Miro를 활용했다.

Aggregate, 이벤트 흐름, 사용자 행동 기반 시나리오 등을 함께 정리하여

단순 기능 구현이 아닌 전체 서비스 흐름을 고려한 설계를 진행했다.

 

[Miro 설계 보러가기] https://miro.com/app/board/uXjVGmDSglo=/

Miro | The Visual Workspace for Innovation

---

ERD (데이터 구조)

도메인 간 관계와 데이터 구조를 명확히 하기 위해 ERD를 작성했다.

 

[ERD 설계 보러가기] https://www.erdcloud.com/d/kJp9TjSjxMgaCkTf8

Spring 최종 프로젝트

---

재생 흐름 (Playback Flow)

재생 기능은 단순 요청 처리 방식이 아니라, 사용자의 상태 변화 흐름을 기반으로 동작하도록 설계하였다.
재생 시작, 일시정지, 건너뛰기 등의 사용자 행동은 개별 이벤트로 저장되는 것이 아니라, Playback의 상태 변화로 관리된다.

하나의 Playback은 "한 곡의 한 번 재생 흐름"을 의미하며, 상태 전이에 따라 재생 시간과 종료 상태가 누적된다.
이를 통해 단순 재생 기능을 넘어, 사용자 행동 흐름을 기반으로 한 분석 및 인기 차트 집계로 확장할 수 있도록 구성하였다.

---

API 명세서

플레이리스트 생성, 재생 제어, 재생 이력 조회, 인기 차트 조회 기능을 기준으로 API를 설계했다.

단순 CRUD를 넘어,
플레이리스트 내 곡 순서 변경과 자동 재생 흐름 기록 등
서비스의 실제 사용 흐름을 반영한 기능을 포함했다.

---

1. 플레이리스트 관리

플레이리스트 생성, 조회, 수정, 삭제 기능을 제공한다.

POST   /api/playlists               # 플레이리스트 생성
GET    /api/playlists               # 플레이리스트 목록 조회
GET    /api/playlists/{playlistId}  # 플레이리스트 상세 조회
PATCH  /api/playlists/{playlistId}  # 플레이리스트 수정
DELETE /api/playlists/{playlistId}  # 플레이리스트 삭제

---

2. 플레이리스트 트랙 관리

플레이리스트는 단순한 곡 저장 기능이 아니라,
사용자가 직접 순서를 구성하고 변경할 수 있도록 설계했다.

POST   /api/playlists/{id}/tracks                 # 트랙 추가
GET    /api/playlists/{id}/tracks                 # 트랙 목록 조회
PATCH  /api/playlists/{id}/tracks/index           # 트랙 순서 변경
DELETE /api/playlists/{id}/tracks/{trackId}       # 트랙 삭제

---

3. 재생 제어

사용자의 재생 흐름을 제어하기 위한 기능을 제공한다.

POST /api/playbacks/play    # 재생 시작 / 재개
POST /api/playbacks/pause   # 재생 일시정지
POST /api/playbacks/skip    # 곡 건너뛰기
POST /api/playbacks/stop    # 곡 정지

---

4. 재생 이력 조회

자동 재생 흐름을 기반으로 사용자의 음악 재생 이력을 조회할 수 있도록 구성했다.

GET /api/me/playback-history   # 내 재생 기록 조회

---

5. 인기 차트 조회

재생 데이터를 기반으로 인기 차트를 조회할 수 있도록 설계했다.

GET /api/popular-charts/top100   # 인기 차트 Top100 조회

---

비즈니스 규칙

각 도메인은 단순 CRUD 처리가 아닌,
서비스의 실제 사용 흐름과 데이터 일관성을 유지하기 위해 설계했다.

특히 사용자 권한, 데이터 무결성,
그리고 기능 간 상호작용을 고려하여 도메인별 비즈니스 규칙을 정의했다.

---

1. PlayList

• 로그인한 사용자만 플레이리스트 생성 가능
• 플레이리스트는 생성한 사용자 (User) 가 소유 및 관리
• 사용자는 여러 개의 플레이리스트 생성 가능 (1:N 관계)
• 플레이리스트는 제목, 설명 등의 메타 정보를 가짐
• 플레이리스트는 작성자 본인만 수정 및 삭제 가능
• 삭제는 soft delete 방식으로 처리
• deletedAt이 NULL인 경우 활성 플레이리스트로 간주
• 삭제된 플레이리스트는 일반 조회 대상에서 제외

---

2. PlayListTrack

• 플레이리스트에 트랙 추가 가능
• 하나의 플레이리스트는 여러 트랙 포함 가능
• 플레이리스트 내 트랙은 표시 순서 가짐
• 트랙 순서는 index 값으로 관리 (1부터 시작)
• 플레이리스트 내 트랙 순서는 충돌 없이 유지되어야 함
• 플레이리스트에서 트랙 순서 변경 가능
• 플레이리스트에서 트랙 제거 가능
• 동일 플레이리스트 내 동일 트랙의 중복 추가 허용 여부는 서비스 정책에 따라 결정 가능
• 트랙이 플레이리스트에 추가된 시점은 createdAt으로 기록

---

3. Playback

• 로그인한 사용자만 재생 기능을 사용할 수 있다.
• 사용자는 트랙 재생, 일시정지, 재개, 중단, 건너뛰기, 완료 상태로 변경할 수 있다.
• 재생 상태는 PLAYING, PAUSED, STOPPED, SKIPPED, COMPLETED 값으로 관리한다.
• 재생 상태는 사용자 행동이 아닌 Playback의 현재 또는 최종 상태를 의미한다.
• Playback은 "한 곡의 한 번 재생 흐름"을 기준으로 생성된다.
• 동일 트랙을 반복 재생하는 경우에도 각각 별도의 Playback으로 저장된다.
• 재생 기록은 사용자 단위로 저장된다.
• Playback은 재생이 발생한 playlist_id를 포함하여 재생 맥락을 함께 저장한다.
• skip시 현재 Playback은 SKIPPED로 종료되고, 다음 트랙에 대해 새로운 Playback이 생성되어 자동 재생된다.
• session_id를 통해 동일 사용자 내 재생 흐름을 구분할 수 있다.
• device_id를 통해 재생이 발생한 디바이스를 구분할 수 있다.
• played_duration은 실제 재생된 누적 시간(초)을 의미한다.
• 재생 시간은 pause, stop, skip, complete 시점에만 누적된다.
• resume 시에는 재생 시간을 누적하지 않고 기준 시각만 갱신한다.
• 재생 기록은 통계 및 차트 집계를 위한 원천 데이터로 활용된다.

---

4. PopularChart

• 인기 차트는 재생 기록 기반으로 집계
• 차트는 주간 단위 기준으로 생성
• snapshotDate 기준으로 차트 데이터 관리
• snapshotDate는 해당 주차의 월요일 00:00 기준으로 설정
• 동일 트랙이라도 주차에 따라 다른 순위 가질 수 있음
• 차트 순위는 해당 기간 재생 수(playCount) 기준으로 결정
• 인기 차트는 Top100 기준으로 조회
• 차트 데이터는 별도 저장하여 조회 성능 최적화
• 동일 snapshotDate 내 동일 트랙은 하나의 차트 데이터만 가짐