sxngt

예이린 통합 플랫폼: 폴리글랏 MSA를 FastAPI 모듈러 모놀리스로 재편

2026.03 ~ 현재 · CTO · 아키텍처 리드, 기술 표준과 협업 체계 총괄

Python 3.12, FastAPI, Pydantic v2, SQLAlchemy 2.0, PostgreSQL 16, Alembic, uv, Redis, gunicorn, GitHub Actions, LangGraph, ChromaDB

문제

  • 아동 돌봄 플랫폼의 백엔드가 저장소 6개(NestJS 1, FastAPI 3, 프론트 2)에 걸친 MSA로 성장
  • 배포 유닛 9개, 데이터베이스 4개, 패키지 매니저 3종
  • JWT 구현 4벌, 서비스 간 배관 코드 약 3,185줄
  • 운영 개발 인원 1명
  • 성능 지표: 문제 아님(공식 테스트 12/12 통과, 30일 가동률 99.87%)
  • 해결할 문제 두 가지
    • 경계 수에 비례해 커지는 변경 비용
    • 시스템 지식이 한 사람의 기억에만 남아 있는 구조(bus factor 1)

목표

  • 목표 두 가지 설정
    • 조직이 통제하고 장기적으로 발전시킬 수 있는 기술 자산
    • 새 구성원이 규칙을 외우지 않고도 안전하게 기여할 수 있는 협업 구조
  • 아키텍처 결정의 평가 기준: 개인의 생산성보다 조직의 확장 가능성
레거시 MSA 전체 지도

아키텍처 재편: 패키지 선언 기반 모듈 경계

  • 모듈러 모놀리스(Modular Monolith) 채택, 모듈 경계는 문서 대신 의존성 선언과 도구로 유지
  • uv workspace 위에 도메인 패키지 19개와 앱 패키지 6개, 공유 커널 core로 재편
재편 후 모노레포 전체 지도
  • 도메인 패키지의 pyproject.toml에서 FastAPI 제외, 선언하지 않은 패키지는 import할 수 없어 도메인 레이어의 프레임워크 의존을 선언 단계에서 차단
  • 공유 커널의 비대화를 모듈러 모놀리스가 무너지는 첫 번째 원인으로 판단
  • core에는 Base 클래스·세션·설정·인증·예외 핸들러만 두어 전체 코드의 1.1%(1,179줄)로 제한
패키지 의존 그래프: 패키지 선언으로 정한 모듈 경계
  • 도메인 내부는 domain / application / infrastructure 3계층
  • 인터페이스는 ABC 대신 typing.Protocol(구조적 타이핑)로 선언해 도메인 코드가 구현체를 참조하지 않도록 구성
  • 애플리케이션 계층은 CQRS 경량 적용, Command/Query Handler 497개로 구성
  • 앱 패키지는 라우터·인증·응답 스키마·Depends 조립만 담당
  • 도메인이 호출자를 참조하지 않는 소유권 원칙을 워크플로우 가이드 8종과 훅으로 상시 검증
도메인 패키지 해부

의존성 주입과 트랜잭션 관리

  • DI 컨테이너 라이브러리를 쓰지 않고 순수 Depends 함수 체인으로 구성
  • provider 함수 452개를 직접 작성하는 비용을 감수하고, 모든 의존성 배선을 grep으로 추적할 수 있게 유지
  • FastAPI의 요청 단위 의존성 캐시로 request-scoped 수명주기 대체
  • 트랜잭션 경계를 요청 하나당 작업 단위(Unit of Work) 하나로 통일
  • 세션 제너레이터 40줄이 commit/rollback을 맡고, 리포지토리는 flush만 수행
  • 도메인 경계를 넘는 작업의 원자성 보장, 해당 규칙은 core 코드 구조로 강제
요청 한 개의 DI 여행

OpenAPI 스펙 기반 API 계약 관리

  • OpenAPI 스펙(518 paths)을 추출해 git에 커밋
  • CI가 빌드마다 스펙을 다시 추출해 diff가 생기면 빌드를 실패시키는 드리프트 게이트 구축, 스키마 불일치를 런타임 전 PR 단계에서 발견
  • 프론트엔드 5개가 이 스펙에서 TypeScript 타입·Zod 스키마·TanStack Query 훅을 코드 생성
  • MSA 시절 주석으로만 존재하던 서비스 간 계약을 스펙 기반 자동 검증으로 대체
  • 전 응답 camelCase(CamelDto), 반환 타입 어노테이션 필수 등의 규칙은 마이그레이션 중 겪은 사고를 근거로 명문화
OpenAPI 계약 파이프라인

코딩 컨벤션과 자동 검증

  • 규칙마다 강제 수단을 함께 설계
    • 네이밍·레이어 순수성·도구 단일화: 훅으로 차단
    • API 계약: CI 게이트
    • 트랜잭션·PK(UUID v7)·soft delete: core 믹스인으로 강제
  • AI 페어 프로그래밍 대응: 아키텍처 규칙을 패키지별 컨텍스트 문서 27개와 워크플로우 가이드 8종으로 코드베이스 안에 배치
  • 개발자와 AI 에이전트가 같은 문서에서 규칙을 읽도록 구성
  • 스키마 이력은 Alembic 단일 체인(72 리비전, head 1개)으로 관리, 배포마다 ORM 메타데이터와 실제 DB를 대조하는 스키마 드리프트 검사 수행
  • DB 스키마 문서는 tbls로 컬럼 comment에서 자동 생성
엔지니어링 컨벤션 카탈로그

이전 전략과 운영

  • 무중단 조건에서 스트랭글러 패턴(Strangler Fig)을 도메인 단위로 적용
  • 하루 1~2개 도메인씩 도메인 모델 → Command/Query → 인프라 순서로 13일간 이전, 14일째 앱 조립
  • 레거시 API 계약을 새 정규화 모델의 파생 필드로 보존해 프론트엔드 수정 없이 컷오버
  • 배포 구성: 단일 코드베이스를 런타임 5개로 나눠 실행
  • gunicorn 5개 그룹이 앱별 포트에서 독립 기동해 장애 격리와 개별 재시작 유지
  • CI 5벌을 품질 게이트(ruff·pytest 836·OpenAPI 드리프트)를 포함한 단일 파이프라인으로 통합
  • 배포·운영 스크립트를 bash 350줄로 정리
  • Grafana·Loki·Alloy 기반 관측성 스택을 도입해 레거시에 없던 로그 파이프라인 구축
CI·배포 파이프라인

협업 체계와 기술 리더십

  • 백엔드와 프론트엔드의 인터페이스 협의 기준을 OpenAPI 스펙으로 통일
  • 프론트엔드 앱 5개가 스펙에서 타입·SDK·쿼리 훅을 코드 생성, 인터페이스 협의는 구두 조율 대신 스펙 diff 리뷰로 진행
  • 기존 계약 변경을 금지하고 추가만 허용하는 additive-only 원칙을 ADR로 명문화해 백엔드 변경에 프론트엔드 작업이 흔들리지 않는 환경 마련
  • 온보딩 자료를 코드베이스에 포함: 패키지별 컨텍스트 문서 27개, 작업 단위 워크플로우 가이드 8종(엔드포인트 추가, 신규 도메인, 마이그레이션 등)
  • 규칙 위반은 훅과 CI가 즉시 알려, 코드 작성 위치와 규칙을 사람에게 묻지 않아도 되는 저장소 구성
  • 도메인 패키지 단위 소유권을 향후 팀 경계로 설계, 인원이 늘면 그대로 업무 분담 기준으로 사용
  • 주니어 기여자의 PR 리뷰 정례화, 리뷰 근거는 명문화된 컨벤션으로 한정
  • 의사결정 기록: 아키텍처 결정은 ADR, 제품 방향은 PRD·로드맵 문서, DB 스키마는 컬럼 comment에서 자동 생성되는 문서 사이트로 축적
  • 결정 근거를 개인의 기억 대신 저장소에 보존

배운 점

  • 경계의 개수는 팀이 감당할 수 있는 만큼만 유지하고, 나머지는 나중에 나눌 수 있는 형태로 남기는 방식이 작은 조직에 적합
  • 리팩터링의 주된 목적은 시스템 지식을 사람의 기억에서 CI·훅·타입·커밋된 계약으로 옮기는 일, 이관을 마쳐야 시스템이 특정 개인에게 의존하지 않음
  • 규칙을 말로 전달하는 방식은 리더가 없으면 멈추므로, 규칙이 자동으로 실행되는 환경 구축을 기술 리더의 역할로 판단
  • 선언만으로는 경계 유지가 불완전: 크로스 도메인 조인의 편의 때문에 경계가 서서히 무너지는 현상을 실측으로 확인
  • 완화 장치(공개 join helper)와 다음 과제(import-linter)를 명시해 관리 가능한 부채로 유지

성과

  • 저장소 6 → 1, 배포 유닛 9 → 5, DB 4 → 1(단일 스키마 102 테이블), 환경변수 121 → 28
  • 인증 구현 4벌 → 160줄 1벌, 서비스 간 배관 3,185줄 → 0줄, CI 테스트 0 → 836개
  • 이전 후 4개월간 엔드포인트 62 → 666으로 확장(신규 서비스 3개 포함), 같은 1인 리소스로 기능 개발 속도 상승
  • 동일 도메인 기준 프로덕션 코드 63% 감소
  • Spring·NestJS 진영의 엔터프라이즈 패턴(Layered Architecture, DDD 전술 패턴, CQRS, DI, Unit of Work, API Contract, 모듈 경계)을 파이썬 생태계로 옮겨 프로덕션에서 검증
  • 해당 경험을 PyCon 발표와 기술 회고 3부작으로 공유
숫자로 보는 전환
엔터프라이즈 패턴 번역 확인서

발휘 역량

  • 폴리글랏 MSA를 모듈러 모놀리스로 무중단 이전하는 대규모 아키텍처 재편
  • 코딩 규칙·API 계약·스키마 이력을 CI·훅·타입 검사로 자동 강제
  • OpenAPI 계약, ADR, 컨텍스트 문서로 온보딩과 코드 리뷰 기준 정비
  • 조직의 확장 가능성을 기준으로 아키텍처 결정