GAJA

프로젝트 개요

코드 저장소: BIKE-PROJECT-MINJI/bike-back

GAJA는 자전거 여행 중 경로, 날씨, 주행 상태를 한 화면에서 확인할 수 있도록 설계한 위치 기반 HUD 서비스입니다. 백엔드는 코스 조회, route point 제공, 주행 시작 가능 여부 평가, 날씨 fallback 같은 API 흐름을 담당합니다.

백엔드에서는 JWT 인증, 코스/route 조회, 외부 기상 API 연동, 주행 기록 저장과 후처리 흐름을 담당했습니다.

주요 기능 및 설계

위치 기반 HUD 데이터 파이프라인

주행 기록 저장 시 원본 route point를 먼저 저장하고, 커밋 이후 비동기 finalization 단계에서 후처리된 경로 데이터를 생성하도록 분리했습니다.

• Raw route point 저장과 async finalization 후처리 책임 분리
• 최근접 route 판단에 local window + segment projection + full-scan fallback 적용
• 후처리 단계에서 route point dedupe/canonicalization 수행

인증 및 세션 관리

서버 세션 의존을 줄이기 위해 JWT 기반 인증 흐름을 사용했습니다.

• JWT 기반 상태less 인증을 채택하여 서버 세션 의존성 제거
• Access Token / Refresh Token 분리로 보안과 편의성 균형 확보
• 인증/프로필 API와 주행 API에서 인증 사용자 기준 처리

외부 API 연동 및 장애 대응

기상 정보는 외부 기상청 API를 통해 실시간으로 조회합니다. 외부 서비스 의존성으로 인한 장애 전파를 방지하기 위해 다음과 같은 대응을 구현했습니다.

• API 응답 실패 시 Fallback 캐시 데이터 제공
• 외부 provider 지연이 전체 응답을 끌고 가지 않도록 timeout 기준 적용
• 동시 요청 시 in-flight 요청 재사용으로 중복 provider 호출 완화

기술적 고민

최근접 route 판단의 정확성과 비용 균형

주행 중 현재 위치가 코스 경로에서 얼마나 벗어났는지 판단할 때, 매번 전체 route point를 선형 탐색하면 비용이 커집니다. 최근 매칭 지점 주변 local window를 먼저 확인하고, 신뢰도가 낮을 때 full-scan fallback으로 보정하는 구조를 적용했습니다.

데이터 정합성

주행 기록은 시간 순서가 중요한 데이터입니다. 네트워크 지연이나 비정상 종료로 인해 좌표 순서가 뒤섞이거나 누락될 수 있으므로, 서버 수신 시 타임스탬프 기준 정렬과 중복 제거를 수행하여 데이터 정합성을 보장했습니다.

비운영 환경 부하 테스트

실제 서비스 트래픽이 아닌 비운영 테스트 환경에서 k6로 조회 경로의 응답 특성을 확인할 수 있도록 부하 검증 스크립트와 p95 지표 확인 흐름을 구성했습니다.

회고

GAJA 프로젝트를 통해 위치 기반 route 판단, 원본 데이터 저장과 후처리 분리, 외부 API fallback 같은 백엔드 보호 흐름을 직접 설계할 수 있었습니다. 이후 프로젝트에서도 상태 분리와 장애 시나리오를 먼저 정리하는 습관을 갖게 되었습니다.