Project Report: klming-fastapi

Analysis Context

• Agent: Claude Code (claude-sonnet-4-6)
• Project: klming 클라이밍 기록 앱 백엔드 서버
• Privacy level: Anonymized (비공개 private repo)
• Commits reviewed: GitHub 데이터 및 세션 로그 기반
• Sessions analyzed: 간접 관찰
• Period: 약 3년간 운영
• Confidence: Medium

Project Overview

클라이밍(암벽등반) 기록 앱 "klming"의 백엔드 API 서버입니다. 운동 기록, 등반 루트 평가, 암장 정보, 커뮤니티 기능, 멤버십 관리, 통계, 푸시 알림 등 모바일 앱의 핵심 비즈니스 로직을 담당합니다. 비동기 Python 웹 프레임워크 기반으로 구축되었으며, 현재는 BaaS 전환 이후 스키마 관리 도구 전용으로 레포지토리를 유지 중입니다.

Tech Stack: Python 비동기 웹 프레임워크, PostgreSQL, 비동기 DB 드라이버, ORM (async), 스키마 마이그레이션 도구, 태스크 큐, 컨테이너 배포

User's Role & Contributions

Youngsup은 이 프로젝트의 유일한 개발자입니다. 아키텍처 설계부터 구현, 인프라 구성, CI/CD 파이프라인, 코드 품질 도구 도입까지 전 과정을 혼자 담당했습니다. 다수의 도메인으로 분리된 DDD 아키텍처를 설계하고, 백엔드를 3년 이상 운영하며 BaaS 전환이라는 큰 마이그레이션까지 완수했습니다.

Technical Decisions

Notable Problem-Solving

Auth 도메인 단계적 리팩토링. 인증 컨텍스트 기반 리팩토링을 수개월에 걸쳐 단계적으로 진행했습니다. 한 번에 전체를 바꾸지 않고 컨텍스트 도입 → 도메인 분리 → 프로필 분리 순으로 단계를 나눠 운영 중인 서비스를 깨뜨리지 않으면서 설계를 개선했습니다.

레거시 데이터 소스 완전 제거. 한때 시스템에 포함되어 있던 레거시 데이터 소스를 코드베이스 전반에서 완전히 제거했습니다. 단순히 연결을 끊는 수준이 아니라 흔적을 지우는 수준의 정리를 진행하며, 미사용 도구도 같은 릴리즈에서 함께 제거했습니다. 기술 부채를 의도적으로 인식하고 명확한 버전 이정표에서 처리하는 패턴입니다.

BaaS 전환을 위한 스키마 안정화. 전환을 앞두고 외래 키 정책 정비, 미사용 모델 제거, 테이블 명명 규칙 통일 등 스키마를 체계적으로 정비했습니다. 마이그레이션이라는 목표를 위해 역방향으로 코드베이스를 준비하는 엔지니어링 감각이 드러납니다.

전환 후에도 스키마 정합성 유지. 전환이 완료된 상황에서도 Enum 타입 개선과 테이블명 통일 작업을 계속하며, 스키마 정합성을 유지하려는 의지를 보여줍니다.

Characteristics Revealed

이 프로젝트에서 특히 드러나는 특성은 장기 운영에 대한 설계 감각입니다. 1인 프로젝트임에도 다수의 도메인으로 분리한 DDD 아키텍처를 선택한 것은 단기 편의보다 장기 유지보수를 우선한 판단입니다. 실제로 이 구조 덕분에 3년에 걸친 점진적 개선이 가능했습니다.

기술 부채를 버전 이정표로 관리하는 습관도 눈에 띕니다. 레거시 제거가 단일 릴리즈에 묶인 것은 우연이 아닙니다. 시맨틱 릴리즈를 통한 자동 버전 관리와 결합해, 언제 무엇이 제거되었는지 명확한 이력이 남습니다.

실용적 마이그레이션 판단도 인상적입니다. 전환 후에도 레포를 폐기하지 않고 스키마 관리 도구로 활용하기로 결정한 것은, 도구의 가치를 플랫폼에 종속시키지 않고 독립적으로 평가한 결과입니다.

1인 프로젝트에서 린터, 타입 체커, 커버리지 도구, pre-commit 같은 코드 품질 도구를 일관되게 적용한 점도 주목할 만합니다. 팀 협업 없이도 팀 수준의 프로세스를 스스로에게 적용하는 자기 규율입니다.

Git & GitHub Analysis

• Commit style: 기능/리팩토링/버그 수정을 명확히 구분하는 메시지, 버전 태그와 연동
• Release cadence: 자동화된 시맨틱 릴리즈로 프로젝트 진화를 기록
• Code quality signals: 린터, 타입 체커, pre-commit, CI/CD, 커버리지 통합
• Dependency management: 메이저 의존성 업데이트를 정기적으로 수행하며 최신 생태계 추적
• Schema management: 다수의 마이그레이션 파일 — 스키마 변경 이력이 코드로 추적 가능

Summary

이 프로젝트는 Youngsup이 자신의 취미(클라이밍)에서 출발한 문제를 3년 이상 운영 가능한 백엔드로 발전시킨 프로젝트입니다. DDD 아키텍처, 전면 비동기 처리, IaC 기반 인프라 관리, 자동 시맨틱 릴리즈 — 이 모든 선택이 1인 프로젝트치고 과도해 보일 수 있지만, BaaS 마이그레이션이라는 큰 변화를 체계적으로 완수한 결과를 보면 그 판단이 옳았음을 알 수 있습니다. "자신이 겪는 문제를 직접 도구로 만들고, 만든 도구를 제대로 운영하는" 개발자의 면모가 이 프로젝트 전반에 걸쳐 드러납니다.

Review History