스튜디오 지브리 영화의 명장면 감상평 서비스

GraphQL 학습을 목적으로 제작된 웹 서비스로,
REST API의 오버페칭/언더페칭 문제를 해결하기 위해 GraphQL을 도입하고 Apollo + Express 기반으로 구현하였다.
서비스 아키텍처에는 Traefik, OAuth2-Proxy, Keycloak을 추가하여 인증/인가를 프록시 레이어에서 처리하고,
애플리케이션 서버는 토큰 검증에 집중할 수 있도록 설계하였다.

또한 Elastic Stack(Elasticsearch, Logstash, Kibana)을 도입하여 MySQL 데이터를 실시간으로 동기화하고,
Elasticsearch 기반의 고성능 검색 기능과 Kibana를 통한 데이터 시각화 및 분석 환경을 제공함으로써
학습 목적뿐만 아니라 실제 운영 환경에서도 데이터 분석과 모니터링이 가능하도록 구성하였다.

초기 베이스: GraphQL과 타입스크립트로 개발하는 웹 서비스 (저자: 강화수)에서 제공하는 🔗예제 프로젝트

기술스택

스크린샷

아키텍처

• 인프라
  • Traefik: 인그레스/리버스 프록시, 라우팅 관리, 컨테이너 이벤트 감지 기반 동적 라우팅
  • OAuth2-Proxy: 프록시 레벨에서 인증/인가 처리, Keycloak과 연동, 애플리케이션 서버는 토큰 검증 불필요
  • Keycloak: 중앙 인증 서버(IdP), 사용자 관리, OIDC 기반 토큰 발급
• 백엔드
  • Apollo Server: Express 플러그인으로 GraphQL query, mutation, resolver 처리
  • Express: 웹 서버 및 미들웨어 관리
  • 비즈니스 로직: 클라이언트 요청을 받아 MySQL과 Redis에 데이터 저장 및 캐싱
  • MySQL: 영속적 데이터 저장 (영화, 명장면, 감상평)
  • Redis: 캐싱 및 성능 최적화
  • Elasticsearch: 검색 엔진, 영화 데이터에 대한 텍스트 검색 지원
  • Logstash: 데이터 파이프라인, MySQL에서 Elasticsearch로 동기화
  • Kibana: Elasticsearch 데이터를 시각화, 검색/로그 분석 및 모니터링 대시보드 제공
• 프론트엔드
  • Apollo Client: GraphQL 쿼리/뮤테이션 전송, 클라이언트 캐싱, 데이터 페칭
  • Nest.js: SSR, SSG UI 렌더링 및 상태 관리
  • CDN (Nginx 기반): 정적 자산 배포 및 캐싱, 접근 속도 최적화
  • Chakra UI: 웹 UI 구성 및 스타일링
• 데이터 흐름
  1. 클라이언트에서 Apollo Client로 GraphQL 요청 전송
  2. 요청은 Traefik → OAuth2-Proxy → Apollo Server로 전달
     • OAuth2-Proxy가 Keycloak과 연동해 사용자 인증/인가 확인
     • 인증된 요청만 백엔드로 전달
  3. Apollo Server + Express에서 요청 처리 후 비즈니스 로직 실행
  4. MySQL/Elasticsearch/Redis에서 필요한 데이터 조회 또는 저장
     1. MySQL에 저장된 데이터는 Logstash 파이프라인을 통해 수집·정제되어 Elasticsearch로 동기화
  5. 서버에서 처리된 데이터를 GraphQL Response로 클라이언트에 반환
  6. 클라이언트에서 Apollo Client가 데이터 수신 후 렌더링
  7. 정적 자산(CSS, JS, 이미지 등)은 CDN에서 빠르게 제공

서브 프로젝트

프로젝트	저장소	설명	버전
Backend	/Ghibli-Films/tree/server	Apollo + Express 기반 서버	v1.5.0
Frontend	/Ghibli-Films/tree/web	Next.js 클라이언트	v2.7.0
Keycloak-theme	/Ghibli-Films/tree/keycloak-theme	Keycloak 테마	v1.0.0
Infra	/Ghibli-Films/tree/main/infra	인프라 관리	-

폴더 구조

열기

Ghibli-Films
├─ README.md
├─ .env # 환경변수
├─ package.json # 패키지 의존성 관리
│  └─ package-lock.json
├─ codegen.yml # GraphQL 스키마 추출기
├─ docker-compose.yml # 종합 도커 컴포즈
├─ docs
│  └─ index.html # gh-pages용 웹페이지
├─ infra # 인프라 관리
│  ├─ docker-compose.yml # 인프라 도커 컴포즈
│  ├─ gateway # 게이트웨이 설정
│  │  └─ traefik.yml
│  ├─ oauth2-proxy # 인증 게이트웨이 설정
│  │  ├─ entrypoint.sh
│  │  └─ config.sh
│  ├─ keycloak # 인증 프로바이더 설정
│  │  ├─ keycloak.conf
│  │  └─ realm-dev.json
│  ├─ cdn
│  │  └─ nginx.conf
│  ├─ rdb/sql # DDL/DML
│  │  ├─ 01.ddl.sql
│  │  ├─ 02.directors.sql
│  │  ├─ 03.films.sql
│  │  └─ 04.cuts.sql
│  ├─ elasticsearch # 인덱스 템플릿 초기화
│  │  ├─ create_index_templates.sh
│  │  └─ templates
│  │     └─ film-template.json
│  └─ logstash # ETL 파이프라인
│     ├─ mysql-connector-j-9.4.0.jar
│     └─ sync_rdb_to_es.conf
└─ project # 프로젝트
   ├─ server
   ├─ web
   └─ keycloak-theme

실행 방법

$ git clone https://github.com/NarciSource/Ghibli-Films

$ cd Ghibli-Films

$ docker-compose up -d

접속 안내

환경	URL
web	http://host.docker.internal:8080/
traefik dashboard	http://host.docker.internal:8080/dashboard
keycloak admin	http://host.docker.internal:8080/auth
server healthcheck	http://localhost:4000
graphql schema	http://localhost:4000/voyager⁠
graphql playground	http://localhost:4000/graphql⁠
elasticsearch ui	http://localhost:5601⁠
cdn	http://localhost:8081⁠