Skip to content

System Diagrams

KTH1007 edited this page Nov 6, 2026 · 5 revisions

시스템 그림

그림은 저장소의 docs/diagrams/에 PNG로 있다. 원본(.drawio)은 저장소 밖에서 관리한다. 아래 그림은 모두 코드와 설정을 읽어 대조해 그린 것이고, 앱을 띄워 호출을 관찰한 것은 아니다. 값(TTL, 한도)은 application.yml과 nginx.conf 기준이다.

README에는 전체 구성, 정상 흐름, ERD가 있다. 이 페이지는 그 밖의 그림과 읽는 법을 다룬다.

그림 보는 목적
전체 구성과 호출 관계 요청이 어떤 구성 요소를 거치는가
정상 흐름 사용자 한 명이 예매를 끝내기까지
호출 순서: 대기열 줄서기, 순번 조회, 승격이 Redis를 어떻게 쓰는가
호출 순서: 홀드와 결제 트랜잭션 경계와 PG 호출 위치
거절 분기 어떤 요청이 어떤 응답 코드로 끝나는가
상태 전이 예약, 좌석, 결제, 알림의 상태가 어떻게 바뀌는가
ERD 테이블과 제약

전체 구성과 호출 관계

전체 구성과 호출 관계

클라이언트는 nginx를 거쳐 앱 서버(2대)로 간다. 앱은 PostgreSQL, Redis, PG(가짜 또는 Toss)를 호출하고, Prometheus가 앱을 수집하고 Grafana가 Prometheus의 지표를 조회한다. Flyway는 전용 컨테이너가 마이그레이션을 실행한다(앱은 flyway.enabled: false).

  • Redis는 127.0.0.1에만 열려 있어 클라이언트가 직접 붙지 못한다.
  • Prometheus는 Docker 내부에서 앱을 직접 수집하고, 외부 클라이언트에는 /actuator/가 공개되지 않는다(nginx가 404).

정상 흐름

정상 흐름

대기열 등록 -> 순번 조회 -> 승격 -> 좌석 선택과 홀드 -> 결제 -> 예매번호 발급이다. 예매 후에는 예매번호와 전화번호로 조회하고 취소할 수 있다.

호출 순서: 대기열

호출 순서: 대기열

  • 줄서기(POST /api/events/{id}/queues)는 nginx의 줄서기 동시 연결 상한(500)을 거친 뒤 앱이 Redis Lua를 한 번 실행한다.
  • 순번 조회(GET .../queues/me)는 nginx의 순번 조회 상한(250)을 거쳐 앱이 Redis를 읽는다. 클라이언트가 Redis에 직접 붙지 않는다.
  • 승격은 앱의 스케줄러가 1초마다 Redis에서 최대 100명에게 활성 토큰을 준다. 클라이언트의 요청이 아니다.
  • 토큰 TTL은 15분(조회마다 연장), 활성 토큰 TTL은 2분이다.

호출 순서: 홀드와 결제

호출 순서: 홀드와 결제

  • 홀드: 컨트롤러가 활성 토큰에 전화번호를 묶고(Redis), 좌석마다 Redis로 먼저 선점한 뒤, 통과한 요청만 DB 트랜잭션에서 조건부 UPDATE로 확정한다.
  • 결제: PG를 부르기 전에 결제를 PENDING으로 선점하고, PG 호출은 트랜잭션 밖에서 한다. 승인되면 한 트랜잭션에서 예약 PAID, 예매번호, 좌석 SOLD, 결제 SUCCESS, Outbox 기록을 함께 처리한다.
  • 취소: 취소 트랜잭션이 끝난 뒤 트랜잭션 밖에서 환불한다.
  • 트랜잭션 밖에서 PG와 Redis를 부르는 이유는 DB 연결을 점유한 채 외부 호출을 기다리지 않기 위해서다(사례 1).

거절 분기

거절 분기

흐름마다 어떤 조건에서 401, 403, 409, 429, 503으로 끝나는지 정리했다. 의도된 거절(예: 대기열이 가득 찬 503 QUEUE_FULL, 승격 전 홀드의 403)과 장애성 503(TEMPORARILY_UNAVAILABLE, SERVER_BUSY)을 구분해서 보는 것이 목적이다. 의도된 거절은 SLO의 실패로 세지 않는다.

상태 전이

상태 전이

  • 예약: HOLDING -> PAID 또는 EXPIRED, PAID -> CANCELED
  • 결제: PENDING -> SUCCESS 또는 FAILED, FAILED -> PENDING(같은 예약으로 다시 시도), SUCCESS -> CANCELED -> REFUNDED
  • 좌석: AVAILABLE, HELD, SOLD
  • 알림(Outbox): PENDING -> PROCESSING -> DONE 또는 FAILED(재시도하면 PENDING으로 돌아감)

ERD

ERD

마이그레이션 V1 ~ V17을 일회용 Postgres에 적용한 결과에서 컬럼, 키, 외래키, 제약을 뽑았다. 엔티티는 객체 참조 없이 id로만 서로를 가리키고 외래키는 DB에만 있다. 하단 표는 유니크 제약과 인덱스의 상태(사용, 무결성, 미사용)를 코드의 쿼리와 EXPLAIN으로 확인해 정리한 것이다(설계 결정 10).

Clone this wiki locally