How I Built FeedLog: Three Repos, One Product

개요

FeedLog는 GitHub 이슈를 코드 저장소를 벗어나지 않고 발행 가능한 변경 로그 항목으로 전환하는 제품으로, 세 개의 독립적인 저장소(feedlog-api, feedlog-app, feedlog-toolkit)로 구성된 아키텍처를 통해 구현되었습니다.

주요 내용

• 세 개의 저장소 아키텍처:
• feedlog-api (private): Node.js 기반 백엔드로, 웹훅 처리, AI 기반 초안 생성, 공개 API 제공.
• feedlog-app (private): 웹 대시보드로, OAuth, 설정, 변경 로그 관리 기능 제공.
• feedlog-toolkit (public, MIT): 임베드 가능한 SDK로, 고객 사이트에 변경 로그 위젯을 렌더링.
• feedlog-toolkit의 독립성과 재사용성: MIT 라이선스로 공개되어 독립적인 버전 관리 및 릴리즈가 가능하며, Stencil 기반 모노레포에서 웹 컴포넌트 및 React, Vue 래퍼를 생성.
• feedlog-api 스택:
• HTTP 프레임워크: Fastify (plugin 시스템 및 스키마 검증 활용).
• 데이터베이스: Neon Postgres + Drizzle ORM (TypeScript 스키마, SQL 마이그레이션).
• 비동기 작업: BullMQ + Redis (GitHub 웹훅 이벤트 처리, AI 초안 생성).
• 스케줄링 작업: Croner (in-process) (웹훅 복구, Sentry 모니터링).
• 안정성: opossum (Postgres 풀에 대한 서킷 브레이커), Redis (@fastify/rate-limit)를 통한 API 키 기반 속도 제한.
• feedlog-app 스택:
• 프레임워크: TanStack Start (React SSR) + TanStack Router, TanStack Query.
• UI: Tailwind CSS v4 + Radix UI primitives (shadcn 패턴).
• 배포: Cloudflare Workers (Wrangler)를 통한 엣지 SSR.
• 데이터베이스 설계 원칙:
• UUIDv7 기본 키: 시간 순서 및 단조 증가로 B-tree 인덱스 단편화 방지. created_at 컬럼 불필요. (단점: Neon 콘솔/Drizzle Studio에서 직접 timestamp 확인 어려움).
• 접두사가 붙은 공개 ID (Prefixed Public IDs): API를 통해 노출되는 모든 테이블에 public_id 컬럼 추가. prefix_ + 12자 base36 nanoid 패턴으로 엔티티 유형 힌트 제공 (예: usr_, iss_).
• 모든 테이블에 대한 소프트 삭제 (Soft Deletes): deleted_at 타임스탬프 컬럼을 사용하여 모든 삭제를 소프트 삭제로 처리. 데이터 복구, 감사 추적, 언두 흐름 용이. (계획: 주기적인 정리 Cron으로 오래된 데이터는 영구 삭제).
• 향후 개선점 고려: in-process Croner 방식의 장기적인 적합성 검토 (별도 스케줄링 작업 프로세스 필요성).

시사점

FeedLog는 여러 저장소의 분리, 적절한 기술 스택 선택, 그리고 시간을 고려한 데이터베이스 설계 원칙 적용을 통해 견고하고 확장 가능한 제품 아키텍처를 구축했습니다. 이러한 설계 결정은 제품 개발의 효율성과 유지보수성을 높이는 데 기여합니다.