예이린 통합 플랫폼: 폴리글랏 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)
목표
- 목표 두 가지 설정
- 조직이 통제하고 장기적으로 발전시킬 수 있는 기술 자산
- 새 구성원이 규칙을 외우지 않고도 안전하게 기여할 수 있는 협업 구조
- 아키텍처 결정의 평가 기준: 개인의 생산성보다 조직의 확장 가능성

아키텍처 재편: 패키지 선언 기반 모듈 경계
- 모듈러 모놀리스(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 코드 구조로 강제

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

코딩 컨벤션과 자동 검증
- 규칙마다 강제 수단을 함께 설계
- 네이밍·레이어 순수성·도구 단일화: 훅으로 차단
- 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 기반 관측성 스택을 도입해 레거시에 없던 로그 파이프라인 구축

협업 체계와 기술 리더십
- 백엔드와 프론트엔드의 인터페이스 협의 기준을 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, 컨텍스트 문서로 온보딩과 코드 리뷰 기준 정비
- 조직의 확장 가능성을 기준으로 아키텍처 결정