← 전체 프로젝트

PROJECT 04

SayBridge

화상채팅 기반 외국어 교육 플랫폼

프로젝트 개요

SayBridge는 외국어 강사와 학생을 실시간으로 연결하는 화상 수업 기반 언어 학습 플랫폼입니다. 학생은 언어와 난이도로 강의를 찾아 수강을 신청하고, 강사가 승인하면 1:1 화상 수업과 실시간 채팅으로 수업을 듣습니다. 수업 뒤에는 과제를 제출하고, 강사가 제출 현황을 확인하는 흐름까지 한 서비스에서 이어집니다.

주요 구현

WebRTC 연결 순서를 정리했고, 프로젝트 이후 과제 제출 상태를 게시글마다 조회하던 쿼리를 한 번의 조회로 바꿨습니다(사후 개선).

진행 기간
2025.01 ~ 2025.05
팀 구성
1인 개발
담당 역할
프론트엔드 및 백엔드 개발

기술 스택

Backend
Spring BootSpring SecurityJWTOAuth2Spring Data JPAQueryDSL
Frontend
React
Realtime
WebSocketSTOMPWebRTC
Data
MySQLRedisAWS S3
시연 화면실제 프론트엔드에 시연용 목 데이터를 넣어 재현했습니다
01 · 강의 탐색언어와 레벨을 골라 조건에 맞는 강의만 검색
02 · 1:1 화상 수업 · 채팅WebRTC 영상 연결 위에서 STOMP 채팅을 실시간으로 주고받음
03 · 과제 제출과제 공지에 녹음 파일을 올리면 바로 제출 상태로 바뀜
04 · 과제 제출 현황 · 강사강사는 과제별로 학생 제출 파일과 시각을 한 번에 확인

01

서비스 소개

서비스 배경
녹화 강의 위주의 학습 서비스는 강사와 학생이 실시간으로 주고받기 어렵고, 강의 탐색·수업·과제가 서로 다른 도구로 나뉘기 쉽습니다. 말하기 중심의 외국어 학습에는 실시간 소통과 수업 관리가 한곳에 모인 환경이 필요하다고 보았습니다.
서비스 목표
강의 검색부터 수강 신청·승인, 화상 수업과 채팅, 과제 제출·확인까지 하나의 서비스에서 연결하고, 영상 연결이 매번 같은 순서로 맺어지도록 시그널링을 통제합니다.
대상 사용자
온라인으로 외국어 수업을 듣는 학생과 수업을 운영하는 강사

주요 기능

  • 강의 탐색

    언어·난이도 같은 조건을 조합해 강의를 검색합니다. (QueryDSL 동적 검색)

  • 수강 관리

    학생이 수강을 신청하면 강사가 승인하거나 거절하고, 수강생 목록을 관리합니다.

  • 1:1 화상 수업

    WebRTC P2P로 영상을 연결하고, STOMP로 연결 순서를 주고받습니다.

  • 실시간 채팅

    수업 중 질문과 피드백을 채팅으로 바로 주고받습니다.

  • 과제 제출

    학생이 과제 파일을 올리고, 강사는 과제별 제출 파일과 시각을 확인합니다.

  • 소셜 로그인

    네이버·카카오·구글 OAuth2 로그인과 JWT 인증을 지원합니다.

02

시스템 아키텍처

SayBridge React 프론트엔드, Spring Boot 백엔드, MySQL, Redis, S3와 WebRTC 화상 수업 구조를 보여주는 시스템 아키텍처
SayBridge 시스템 아키텍처이미지를 누르면 크게 볼 수 있습니다

영상 스트림은 P2P로 흘려 서버 부하를 줄이고, 서버는 시그널링과 영속 데이터만 책임지도록 역할을 나눴습니다.

구성 요소별 역할

  • React

    수업 탐색, 신청, 화상 수업, 채팅, 과제 제출 화면 및 클라이언트 로직 담당

  • Spring Boot

    인증(JWT), 강의/과제 CRUD, 파일 업로드 REST API 및 비즈니스 로직 처리

  • WebSocket / STOMP

    실시간 채팅 메시지 중계 및 WebRTC 연결을 위한 시그널링 데이터 교환

  • WebRTC

    서버 부하를 최소화하기 위한 브라우저 간(P2P) 영상·음성 미디어 스트림 연결

  • MySQL · S3 · Redis

    영속 데이터(MySQL), 강의·과제 파일(S3), 저장된 채팅 메시지 ID 목록(Redis)을 분리해 관리

03

구현 기능

전체 서비스 안에서 직접 구현하거나 공동으로 맡은 기능입니다.

  • 01

    인증 및 권한 관리

    Spring Security·OAuth2 소셜 로그인과 JWT 인증

  • 02

    WebRTC 화상 연결

    브라우저 간 미디어 스트림 P2P 연결을 통한 실시간 화상 수업 구현

  • 03

    실시간 메시징

    WebSocket/STOMP 기반의 시그널링 처리 및 수업 중 실시간 채팅 중계

  • 04

    동적 강의 검색

    QueryDSL을 활용하여 언어·레벨 등 복합 조건의 동적 강의 검색 구현

  • 05

    파일 시스템 분리

    S3를 활용한 강의 자료·과제 파일 저장 (과제 제출 상태 조회는 사후 개선)

04

트러블슈팅

문제와 해결, 확인한 결과를 적고 실제 코드와 테스트를 근거로 붙였습니다.

문제 해결

WebRTC 협상 순서 안정화

문제
미디어 스트림 준비, STOMP 연결, 상대방 입장과 Offer 생성이 서로 다른 비동기 흐름에서 실행되어 초기 연결 시점에 따라 영상 연결 상태가 달라졌습니다.
해결
로컬 트랙을 PeerConnection에 먼저 등록하고 STOMP를 연결했습니다. 상대방 입장과 stable 상태를 확인한 뒤 Offer를 생성하도록 순서를 고정했습니다.
결과
연결 시점에 따라 영상이 표시되지 않던 흐름을 안정화했습니다. 시그널링과 미디어 트랙 상태를 함께 확인했습니다.
webrtc-signaling.jsjavascript
// 1) 먼저 로컬 미디어를 확보하고 PeerConnection에 등록
navigator.mediaDevices
  .getUserMedia({ video: true, audio: true })
  .then((stream) => {
    localRef.current.srcObject = stream;
    stream.getTracks().forEach((track) => {
      if (pc.signalingState !== 'closed') {
        pc.addTrack(track, stream);
      }
    });
  })
  .then(connectStomp);

// 2) 상대방 입장(join) 후 stable 상태에서 Offer 생성
case 'join':
  if (isInitiator && !negotiatingRef.current
      && pc.signalingState === 'stable') {
    negotiatingRef.current = true;
    const offer = await pc.createOffer();
    await pc.setLocalDescription(offer);
    stompRef.current.publish({
      destination: '/app/video.signal',
      body: JSON.stringify({
        type: 'offer',
        sdp: pc.localDescription,
        chatCode,
      }),
    });
  }
  break;
판단 과정 단계별로 보기
  1. 문제 현상

    Offer/Answer 시그널링은 진행됐지만 일부 연결에서 상대방 영상이 표시되지 않아, 시그널링 메시지와 미디어 트랙 준비 시점을 함께 추적했습니다.

  2. 원인 추적

    getUserMedia, addTrack, STOMP connect, 상대방 join, createOffer의 실행 순서를 나눠 확인해 자동 시그널링의 비동기 순서 문제로 범위를 좁혔습니다.

  3. 확인한 구조적 문제

    로컬 스트림 준비와 STOMP 연결이 분리되어 있고, 상대방 준비 여부와 무관하게 협상이 시작될 수 있어 PeerConnection 상태에 따라 연결 결과가 달라질 수 있었습니다.

  4. 해결

    로컬 미디어 트랙을 먼저 PeerConnection에 등록한 뒤 STOMP를 연결하고, 상대방 join과 stable 상태를 확인한 경우에만 Offer를 생성하도록 순서를 재구성했습니다.

  5. 결과

    초기 협상 순서를 하나의 흐름으로 통제해 연결 시점에 따른 불안정성을 줄였습니다. 시그널링 성공 여부뿐 아니라 트랙 등록과 PeerConnection 상태를 함께 확인하도록 개선했습니다.

05

기술 선택 이유

기술 이름보다 해결하려던 작업과 적용 이유를 적었습니다.

WebRTC

브라우저 간 1:1 영상·음성 연결

영상은 P2P로 전달하고 서버는 연결을 위한 시그널링을 담당하도록 역할을 나눴습니다.

WebSocket · STOMP

시그널링과 수업 중 채팅 중계

미디어 준비, 서버 연결, 상대 입장과 Offer 생성의 순서를 함께 관리해 연결 시점에 따른 차이를 줄였습니다.

QueryDSL · Spring Security

조건부 강의 검색과 JWT 인증

언어·레벨 조건이 있을 때만 쿼리에 반영하고, 소셜 로그인 뒤의 요청은 JWT로 인증했습니다.

06

회고

시그널링 메시지가 전달돼도 영상 연결까지 성공했다고 볼 수 없었습니다. 미디어 트랙 준비와 PeerConnection 상태를 함께 추적하면서, 비동기 문제를 이벤트의 실행 순서로 좁히는 방법을 익혔습니다.