Project Report: klming 백엔드 마이그레이션
Analysis Context
- Agent: Claude Code (claude-sonnet-4-6)
- Project: klming — 자체 호스팅 백엔드 → BaaS 전환
- Privacy level: Anonymized (비공개 프로젝트)
- Commits reviewed: 마이그레이션 파일 + GitHub 데이터 기반
- Sessions analyzed: 간접 분석 (GitHub 데이터 및 세션 로그 기반)
- Period: 약 3개월간 진행
- Confidence: Medium
Project Overview
실내 클라이밍 기록 앱 "klming"의 백엔드 아키텍처 전환 프로젝트입니다. 자체 호스팅 API 서버에서 BaaS(Backend as a Service)로의 마이그레이션을 수행했습니다. 인프라 운영 부담과 비용을 줄이면서 동일한 기능을 유지하는 것이 핵심 목표였습니다.
Tech Stack: 모바일(Flutter) + 자체 호스팅 Python 백엔드 → 모바일(Flutter) + BaaS
User's Role & Contributions
Youngsup은 이 마이그레이션의 유일한 설계자이자 실행자입니다. 아키텍처 결정, DB 스키마 준비, 앱 상태 관리 교체, API 레이어 전환, 스토리지 이전까지 모든 단계를 혼자 담당했습니다. 실사용자가 있는 프로덕션 서비스를 운영 중인 상태에서 무중단으로 마이그레이션을 완료했습니다.
Technical Decisions
| Decision | Chosen Approach | Reasoning | Alternatives Considered |
|---|---|---|---|
| 마이그레이션 순서 | DB 정리 → Auth → State → API → 정리 | 위험 단계적 분산, 각 단계 독립 롤백 가능 | 한 번에 전환 (빅뱅 마이그레이션) |
| 기존 서버 레포 | 전환 후에도 유지 | 스키마 마이그레이션 도구의 버전 이력 활용 | 완전 폐기 |
| 상태 관리 | 마이그레이션과 병행하여 상태 관리 프레임워크 전환 | BaaS SDK와의 통합 용이성, 코드 간소화 | 기존 상태 관리 유지 |
| 서비스 전환 방식 | 구/신 시스템 병행 운영 후 전환 | 다운타임 없이 마이그레이션, 사용자 영향 최소화 | 점검 시간 공지 후 일괄 전환 |
| 통계 API | 서버 엔드포인트 → DB 함수 직접 호출 | DB 계층에서 직접 처리, 네트워크 왕복 제거 | 서버리스 함수 |
Notable Problem-Solving
DB 스키마 준비를 마이그레이션보다 앞에 배치. 마이그레이션을 시작하기 전, 스키마 마이그레이션 도구를 통해 스키마를 체계적으로 정리했습니다. 레거시 데이터 소스 제거, 외래 키 정책 정비, 미사용 모델 제거 등 "깨끗한 스키마"를 가져간 덕분에 이후 단계가 간결해졌습니다.
인증 전환을 가장 먼저, 그리고 신중하게. 인증은 앱 전체에서 가장 깊숙이 연결된 시스템이기 때문에, 실패 시 치명적 결과가 발생합니다. 인증 전환을 다단계로 진행하고, 안정된 후에야 다음 단계로 진행했습니다.
API 전환 스프린트. 약 2주간 6개 API 도메인을 BaaS 직접 호출로 전환했습니다. 기존 미들웨어 레이어를 제거함으로써 네트워크 요청과 서버 비용을 대폭 절감했습니다.
대규모 스토리지 이전. 기존 스토리지에서 BaaS 스토리지로 대량의 미디어 파일을 마이그레이션했습니다. 사용자가 즉시 체감하는 영역이므로 특히 조심스럽게 진행하고, 완료 후 레거시 코드를 완전히 제거했습니다.
기존 서버 레포를 완전히 폐기하지 않는 결정. 전환이 완료된 후에도 기존 서버 레포를 스키마 관리 도구 전용으로 유지하는 실용적 선택을 했습니다.
Characteristics Revealed
이 마이그레이션 프로젝트에서 특히 드러나는 특성은 준비에 투자하는 습관입니다. 첫 번째 단계에서 상당 기간을 DB 정리에만 쏟았습니다. "빨리 넘어가자"가 아니라 "넘어갈 때 이 스키마가 문제없어야 한다"는 순서였습니다. 이 선택이 이후 빠른 전환을 가능하게 한 기반입니다.
운영 중인 서비스에 대한 책임감도 두드러집니다. 다운타임 없이 마이그레이션하는 것은 기술적으로 더 복잡하지만, 실사용자에 대한 영향을 최소화하는 방향을 선택했습니다.
비용 최적화를 실용적으로 접근하는 태도도 보입니다. 자체 호스팅 서버 운영 비용이 1인 개발자에게 비효율적이라는 판단 하에 BaaS로 전환하여 운영 비용을 대폭 절감했습니다. 기술적 우월성보다 운영 효율성을 기준으로 아키텍처를 평가하는 관점입니다.
Git & GitHub Analysis
- 마이그레이션 단계 추적: 스키마 마이그레이션 파일이 준비 과정을 순서대로 기록. 각 파일이 독립적 변경을 담당
- 버전 태깅: 마이그레이션 단계와 버전이 연동되어 진행 상황 추적 가능
- 레거시 정리의 명확성: 전환 완료 후 레거시 코드와 패키지를 남기지 않는 깔끔한 정리 패턴
- 단계별 커밋 분리: 각 마이그레이션 단계가 날짜 범위로 추적 가능 — 일정에 따라 체계적으로 진행
Summary
이 마이그레이션은 1인 개발자가 프로덕션 서비스를 운영하면서 백엔드 아키텍처를 전면 교체하는 작업을 어떻게 실행했는지를 보여줍니다. 무중단 전환, DB 준비 우선, 단계별 위험 분산, 기존 도구의 실용적 유지라는 선택들이 모여 약 3개월 만에 운영 비용 대폭 절감과 아키텍처 현대화를 동시에 달성했습니다. Youngsup이 이 프로젝트에서 드러낸 것은 새 기술을 채택하는 속도가 아니라, 기존 서비스를 안전하게 유지하면서 아키텍처를 바꾸는 판단력과 실행력입니다.
Review History
| Date | Reviewer | Change | Reason |
|---|---|---|---|
| 2026-03-13 | User | Content Sensitivity Guide 적용으로 재작성 | 구체적 비즈니스 수치(가입자 수, MAU, 비용 절감률), 인프라 스택 상세, 정확한 마이그레이션 날짜 제거 |