AMOA

mooner:~/resume/projects/amoa $ tree -L 1

mooner:~/resume/projects/amoa $ cat docs/architecture.md

mooner:~/resume/projects/amoa $ git log --grep=fix

1. 01

   배포할 때마다 색인 작업이 조용히 멈췄다

   Problem

   색인 작업을 선점한 뒤 저장하기 전에 프로세스가 재시작되면, 선점 질의도 누락분을 채우는 스윕도 그 클립을 다시 집지 않았습니다. 오류 없이 색인만 빠진 채 남았고, 로컬 데이터에서는 53건 중 10건이 그랬습니다. 개발 서버는 배포할 때마다 재시작하니 매번 생길 수 있는 문제였습니다.

   Approach

   next_attempt_at을 "이 시각 전에는 보이지 않는다"는 한 가지 뜻으로 통일했습니다. 대기 중인 작업에는 재시도 시각, 선점한 작업에는 10분짜리 리스 만료 시각입니다. 조건 하나로 두 상태를 모두 선점하게 되고, 리스로 되살아난 작업도 시도 횟수를 씁니다. 이미 갇힌 행은 마이그레이션에서 되살렸습니다.

   Result

   리스 관련 통합 테스트 7건을 더하고, 선점 조건을 되돌리면 새 테스트가 실패하는 것까지 확인했습니다. 로컬 데이터 53건이 모두 색인됐습니다.

2. 02

   추천 API가 limit 12부터 500을 냈다

   Problem

   2단 벡터 검색을 넣으면서 HNSW 탐색 폭(ef_search)을 후보 수에서 계산했는데, pgvector의 상한 1000을 확인하지 않았습니다. 기본 요청(limit=20)이 ef_search = 1800이 되어 500이 났고, limit이 12 이상이면 모두 실패했습니다.

   Approach

   상한을 한곳에 두고, ef_search가 아니라 후보 수 자체를 잘랐습니다. ef_search만 낮추면 반복 스캔이 늘어 오히려 느려진다는 측정(40일 때 p50 3.92ms, 200일 때 1.52ms)을 따른 결정입니다. 요청 크기 1–600과 오버페치 배수의 모든 조합에서 상한을 넘지 않는 것을 확인했습니다.

   Result

   실제 PostgreSQL에서만 재현되는 문제라 통합 테스트로 고정했고, 수정 전 코드에서는 그 테스트가 실패하는 것을 확인했습니다.

3. 03

   벡터 인덱스를 1/3로 줄이고, 그 대가를 재다

   Problem

   768차원 벡터의 HNSW 인덱스가 행당 4,096B라, 버퍼 128MB 기준 약 3만 3천 행이면 인덱스가 메모리를 넘칠 상황이었습니다. 자막 단위 색인이 들어오면 넘을 규모였습니다.

   Approach

   임베딩을 halfvec으로 바꾸고(코사인 거리 최대 오차 7e-5), 앞 512차원으로만 인덱스를 만든 뒤 후보를 768차원으로 다시 정렬하는 2단 검색을 넣었습니다. 합성 데이터 2만 행에서 256차원은 recall@10 0.862로 기준(0.95)에 못 미쳤고, 512차원은 0.984였습니다.

   Result

   인덱스가 행당 1,366B로 줄어, 메모리를 넘는 시점이 약 9만 8천 행으로 늦춰졌습니다. 대신 2만 행에서는 2단 검색이 더 느렸습니다(p50 7.17ms 대 1.52ms). 이 측정에 따라 데이터가 적은 레시피 검색은 단일 768차원 인덱스로 두었습니다.

4. 04

   검색 입구가 다섯 개라 클립이 빠졌다

   Problem

   검색처럼 보이는 API가 다섯 개였고, 프론트엔드 검색 화면이 강의 목록 API를 쓰고 있어 클립이 결과에서 빠졌습니다. 통합 검색을 하나 더 만드는 것만으로는 잘못 고를 여지가 사라지지 않았습니다.

   Approach

   통합 검색, 레시피 하이브리드 검색과 통합 자동완성, 클립 벡터 검색을 차례로 붙인 뒤, 검색 경로를 /search와 /search/suggestions 둘로 정리하고 응답을 type으로 구분하는 형태로 바꿨습니다. 호환이 깨지는 변경 4건은 이때 한 번에 정리했습니다.

   Result

   검색 제공자 매핑을 빠짐없는 when으로 두어, 새 종류를 빠뜨리면 컴파일이 막히고 등록을 빠뜨리면 스모크 테스트가 잡습니다.

5. 05

   Spring Boot에서 Ktor로, 바깥 동작은 그대로

   Problem

   Spring Boot와 Modulith로 시작한 백엔드를 Ktor와 Exposed로 다시 쓰면서, API 응답과 DB 스키마, 세션처럼 바깥에서 보이는 동작은 바꾸지 않는 것을 목표로 했습니다.

   Approach

   기존 앱의 실제 응답 56건과 골든 JSON 24건으로 특성화 테스트를 만들었습니다. DB 마이그레이션은 바이트 단위로 같게 두고 스키마 덤프로 차이를 감시했으며, Redis 키와 TTL, 이벤트 아웃박스 형식, 환경 변수 이름까지 맞춰 전환과 롤백 어느 쪽에서도 로그인 세션이 유지되게 했습니다.

   Result

   테스트 167개를 통과한 채 전환했습니다. 전환 직후 fat jar에서 Flyway 서비스 파일이 덮어써져 마이그레이션 두 개가 조용히 빠진 문제도 찾아 빌드 설정으로 고쳤습니다.