엔지니어링 개요 (홈)

이 시스템의 핵심은 공개 API 서버다. 클라이언트(브라우저·앱)로부터 HTTP 요청을 받아 사용자, 노트북, 결제 데이터를 처리한다. 데이터는 모두 Postgres (관리형 데이터스토어)에 저장되며, API 서버와 Postgres 사이에는 반드시 DB 커넥션 풀을 경유해야 한다. 스키마 변경은 Alembic 마이그레이션 도구로 관리되고, 배포와 롤백은 CI/CD 파이프라인이 자동화한다. 인시던트 발생 시 #incidents 채널로 공지가 게시된다. [Engineering — Incidents & Decisions.md]

아키텍처의 가장 중요한 운영 원칙은 모든 DB 접근은 공유 풀을 통해야 한다는 것이다. 이를 어기면 커넥션 고갈로 인한 대규모 장애가 발생할 수 있으며, 실제로 그런 일이 일어났다. 자세한 내용은 아래 포스트모텀 섹션에서 다룬다. [Engineering — Incidents & Decisions.md]

시스템을 구성하는 주요 컴포넌트는 다음과 같다.

공개 API 서버는 사용자·노트북·결제 요청을 처리하는 메인 서비스다. DB 커넥션 풀은 모든 DB 접근이 반드시 경유해야 하는 공유 자원이며, 풀을 우회하는 코드는 가장 위험한 운영 패턴이다. Postgres (관리형 데이터스토어)는 이 팀의 유일한 기본 데이터스토어로, ADR-014 — Postgres를 기본 데이터스토어로 채택을 통해 공식화되었다. Alembic은 스키마 마이그레이션을 수동으로 관리하는 도구로, 배포 롤백 시 스키마 변경 여부를 반드시 확인해야 하는 이유가 바로 여기에 있다. [Engineering — Incidents & Decisions.md]

팀의 기술적 선택은 ADR 형식으로 기록된다. 현재 이 지식 베이스에서 다루는 핵심 ADR은 다음과 같다.

ADR-014 — Postgres를 기본 데이터스토어로 채택는 사용자, 노트북, 결제 데이터를 저장하기 위한 데이터스토어를 선택한 결정이다. 팀은 강한 일관성(strong consistency), 트랜잭션, 조인(JOIN) 지원을 핵심 요건으로 삼았고, 후보 세 가지를 평가했다. MongoDB는 트랜잭션과 조인 지원이 부족하여 기각되었고, DynamoDB는 벤더 종속(lock-in) 우려와 애드혹 쿼리의 취약함으로 기각되었다. 결과적으로 관리형 Postgres가 채택되었으며, 트레이드오프로 Alembic을 통한 수동 스키마 마이그레이션 관리를 감수하기로 했다. 세 후보의 상세 비교는 데이터스토어 비교 — Postgres vs MongoDB vs DynamoDB 페이지에서 확인할 수 있다. [Engineering — Incidents & Decisions.md]

이 결정은 단순한 기술 선택을 넘어 운영 방식 전반에 영향을 미쳤다. Postgres (관리형 데이터스토어)의 커넥션 한도는 유한하기 때문에 DB 커넥션 풀 관리가 필수적인 운영 관심사가 되었으며, 스키마 마이그레이션을 동반하는 배포는 롤백 절차를 더욱 복잡하게 만든다. [Engineering — Incidents & Decisions.md]

포스트모텀 — 2026-05-12 API 장애 (45분)는 이 팀이 경험한 주요 인시던트 기록이다. 2026년 5월 12일 오후, 신규 엔드포인트를 포함한 배포가 나가면서 약 45분간 공개 API 전반에 5xx 오류가 발생하고 결제(checkout) 기능이 차단되었다. [Engineering — Incidents & Decisions.md]

장애의 근본 원인은 신규 엔드포인트가 DB 커넥션 풀을 사용하지 않고 요청마다 개별 DB 커넥션을 직접 생성한 것이었다. 14:02 배포 이후 부하가 쌓이면서 14:10에 Postgres (관리형 데이터스토어)의 커넥션 한도가 소진되었고, API 전체가 타임아웃에 빠졌다. 14:47에 롤백이 실행되어 14:55에 서비스가 완전히 복구되었다.

이 장애에서 도출된 후속 조치 항목은 아직 완료되지 않았다. DB 커넥션 수가 최대치의 80%에 도달할 때 알림을 추가하고, 풀 외부에서 임의로 커넥션을 생성하는 코드를 금지하는 린트 규칙을 도입하며, 신규 엔드포인트 릴리스 전 부하 테스트를 의무화하는 세 가지 항목이 미완료 상태다. DB 커넥션 풀 페이지에서 이 패턴의 개념적 설명과 올바른 사용 원칙을 확인할 수 있다. [Engineering — Incidents & Decisions.md]

런북 — 잘못된 배포 롤백 절차는 잘못된 배포가 감지되었을 때 서비스를 이전의 안정된 상태로 되돌리기 위한 공식 단계별 절차를 담고 있다. 2026-05-12 장애에서 실제로 적용된 절차이기도 하다. [Engineering — Incidents & Decisions.md]

롤백 절차는 크게 다섯 단계로 구성된다. ① 대시보드에서 에러율·레이턴시 지표를 확인하여 회귀 여부를 검증한다. ② CI에서 main 브랜치의 마지막 그린(green) 파이프라인 커밋을 찾는다. ③ 해당 커밋으로 배포 잡을 실행한다. ④ 롤백 후 5분 이내에 에러율이 정상으로 돌아오는지 확인한다. ⑤ #incidents 채널에 롤백 커밋과 한 줄 원인 요약을 게시한다. [Engineering — Incidents & Decisions.md]

이 절차에서 가장 중요한 주의사항은 DB 스키마 변경이 포함된 배포의 경우 앱만 단독으로 롤백해서는 안 된다는 것이다. 반드시 마이그레이션 상태를 먼저 확인해야 한다. 이는 ADR-014 — Postgres를 기본 데이터스토어로 채택에서 결정된 Alembic 기반 수동 마이그레이션 전략과 직결된다. 스키마 롤백을 고려하지 않은 채 앱만 이전 버전으로 되돌리면 데이터 정합성이 깨질 수 있기 때문이다. [Engineering — Incidents & Decisions.md]

이 지식 베이스의 각 문서는 단독으로 존재하지 않는다. 아래 다이어그램은 주요 페이지들이 어떻게 서로를 참조하는지를 보여 준다.

ADR-014 — Postgres를 기본 데이터스토어로 채택이 Postgres (관리형 데이터스토어) 선택의 근거를 제공하고, Postgres 운영은 DB 커넥션 풀 관리를 필수로 요구한다. 풀 관리 실패는 포스트모텀 — 2026-05-12 API 장애 (45분)으로 이어졌고, 그 장애 대응 과정에서 런북 — 잘못된 배포 롤백 절차가 실행되었다. 그리고 롤백 절차는 다시 스키마 마이그레이션 전략(ADR-014)과 연결된다. 모든 내용의 원본은 Engineering — Incidents & Decisions.md에서 확인할 수 있다. [Engineering — Incidents & Decisions.md]