TL;DR

이 레포는 NestJS와 TypeScript로 구현된 클라우드 네이티브 마이크로서비스 지갑 플랫폼으로 각 서비스가 Clean Architecture를 따르고 Apache Kafka로 비동기 이벤트를 스트리밍하며 gRPC로 실시간 검증을 수행한다. 복식부기 원장을 사용하여 트랜잭션 무결성을 확보하고 MFA·KYC 통합으로 규제 요건을 충족하도록 구성되어 있다. Terraform과 서비스별 GitHub Actions가 함께 제공되어 인프라 코드 기반의 재현 가능한 배포 파이프라인을 구성할 수 있다. 로컬 Docker Compose로 Kafka·PostgreSQL·Redis를 기동한 뒤 서비스별 .env를 설정하고 npm run start:dev로 각 서비스를 실행하면 엔드투엔드 흐름을 빠르게 검증할 수 있다.

주요 기능

• 지갑 관리를 수행하는 독립 서비스 구성을 제공한다. 각 서비스는 도메인·애플리케이션·인프라 계층으로 분리되어 유지보수와 테스트가 용이하다. 서비스별로 독립 배포가 가능하여 확장성과 장애 격리를 확보한다.
• 이벤트 주도 비동기 처리 파이프라인을 제공한다. Apache Kafka를 토픽 기반 이벤트 스트리밍으로 사용하여 사용자 등록부터 알림 전송까지 비동기 워크플로를 연결한다. 이 방식은 서비스 간 결합도를 낮추고 이벤트 재처리 및 감사 로그 유지를 용이하게 한다.
• 실시간 검증을 위한 동기 RPC를 제공한다. gRPC와 Protobuf를 사용하여 인증·컴플라이언스 체크를 동기 호출로 처리함으로써 트랜잭션 승인 과정에서 빠르고 타입 안전한 검증을 수행한다. 동기 호출은 리스크 평가와 같은 결정적 검증 단계에서 지연을 최소화한다.
• 운영 자동화를 위한 CI/CD와 IaC를 포함한다. 서비스별 GitHub Actions 워크플로가 Docker 이미지 빌드와 AWS ECR 푸시 및 ECS 배포를 자동화한다. Terraform 코드로 VPC, RDS, ECS, ECR 등 AWS 리소스를 선언하여 프로덕션 환경을 코드로 재현할 수 있다.

어떻게 동작하는가

각 마이크로서비스는 Clean Architecture 원칙을 따른 계층 구조로 비즈니스 로직과 인프라 접근을 분리하여 구현되어 있다. 비동기 이벤트 흐름은 Apache Kafka 토픽에 이벤트를 발행하고 관련 서비스가 해당 토픽을 소비하여 상태 변경과 후속 처리를 수행한다. 동기적 요구가 발생하는 경로에서는 gRPC 호출로 실시간 검증을 수행하고 그 결과를 토대로 Kafka 이벤트를 생성하거나 데이터베이스 트랜잭션을 완료한다.

해결 문제

이 레포는 디지털 지갑 운영에 필요한 서비스 분리, 이벤트 기반 데이터 연계, 규정 준수 검증, 그리고 알림 전달 구조를 통합하여 제공한다. 단일 모놀리식에서 발생하는 개발·배포 병목과 감사 추적의 어려움을 해소하기 위해 서비스별 독립 배포와 Kafka 기반 이벤트 스트리밍을 채택하여 시스템 변경과 확장을 용이하게 한다. 또한 복식부기를 통해 금융 트랜잭션의 원장 무결성을 확보하고 MFA·KYC 통합으로 규제 요구를 충족할 수 있는 엔드투엔드 흐름을 갖춘다.

지금 주목받는 이유

클린 아키텍처 기반의 마이크로서비스 구성과 Kafka·gRPC를 결합한 실무형 레퍼런스로서 인프라 코드와 CI/CD를 함께 제공하기 때문에 실무 도입 사례로 주목받고 있다.

차별점

• 클린 아키텍처를 서비스 단위로 일관되게 적용하여 각 서비스의 도메인 경계를 명확히 한다. 이로 인해 기능별 테스트 및 독립 배포가 수월하고 서비스별 기술 부채를 국지화할 수 있다. 결과적으로 팀별 소유와 운영 효율성이 향상된다.
• 이벤트 중심 설계와 gRPC 병용으로 비동기 확장성과 동기적 무결성 검증을 동시에 확보한다. Kafka는 비용이 큰 재시도·재생(consumer replay)을 지원하여 이벤트 기반 회복성을 제공하고 gRPC는 실시간 리스크 체크와 같은 결정적 경로에서 일관된 응답을 보장한다. 두 패턴의 조합으로 지연-정합성 트레이드오프를 상황에 맞게 조율할 수 있다.
• Terraform을 통한 인프라 코드와 서비스별 GitHub Actions 워크플로가 통합되어 배포 파이프라인을 표준화한다. 인프라 변경은 코드 리뷰와 계획 단계로 관리되며 이미지 빌드·ECR 푸시·ECS 배포가 자동화되어 운영 반복 작업을 줄인다. 이로 인해 로컬 개발 환경과 프로덕션 간의 불일치를 줄이고 재현 가능한 배포를 달성한다.

사용 사례

• 스타트업 또는 금융 서비스 팀이 빠르게 회계 무결성과 규제 준수를 갖춘 지갑 기능을 구축할 때 활용할 수 있다. 이 레포는 인증·KYC·MFA와 복식부기, 알림 파이프라인을 포함하여 기본적인 운영 흐름을 바로 적용할 수 있는 구성 요소를 제공한다. 서비스별 독립 배포는 트래픽 증가 시 부분적인 수평 확장이 가능하게 한다.
• 금융 애플리케이션의 프로토타입 또는 PoC를 제작할 때 백엔드 아키텍처 템플릿으로 활용할 수 있다. 개발자가 인증, 트랜잭션 처리, 규정검사 흐름을 빠르게 조립하고 실제 Kafka 기반 이벤트 흐름으로 엔드투엔드 시나리오를 검증하는 데 적합하다. Terraform과 CI 파이프라인이 포함되어 데브옵스 워크플로 검증에도 유리하다.
• 교육·내부 레퍼런스로서 마이크로서비스 설계와 이벤트 구동 아키텍처를 학습하려는 팀에서 실전 예제로 사용할 수 있다. 각 서비스의 README와 Swagger 문서가 포함되어 있어 API 계약과 서비스 경계를 학습용 사례로 삼기 적합하다. 로컬 Docker Compose 환경으로 전체 스택을 손쉽게 기동하여 통합 테스트를 수행할 수 있다.

시작하기

레포를 클론한 뒤 Docker Compose로 로컬 인프라(Kafka KRaft, PostgreSQL, Redis)를 기동하여 기본 의존성을 확보한다. 각 서비스의 .env.example 파일을 복사하여 환경변수를 설정한 다음 각 서비스 디렉터리에서 npm install을 실행하고 개발 모드로 start:dev 명령을 통해 개별 서비스를 실행한다. Swagger UI가 각 서비스의 포트에서 열리므로 API를 확인하고 통합 플로우를 로컬에서 테스트할 수 있다.

요구사항

• Node.js 24 이상과 npm 10 이상이 필요하다. 이 런타임 요구는 프로젝트의 SWC 빌드 및 NestJS 11 기반 실행을 충족시키기 위한 최소 조건이다. 로컬 개발에서는 Alpine 기반 Docker 이미지를 사용하므로 호환되는 Node 버전 사용이 권장된다.
• Docker와 Docker Compose가 필요하며 로컬에서 Kafka(KRaft), PostgreSQL, Redis를 컨테이너로 구동하여 통합 테스트 환경을 구성한다. Compose로 띄운 인프라의 포트와 접속 정보는 각 서비스의 .env 파일에 반영해야 정상적으로 연동된다. 운영 환경에서는 Terraform으로 AWS 리소스를 프로비저닝하여 ECS Fargate 기반 배포를 수행한다.
• 외부 서비스 연동을 위한 API 키와 자격 증명이 필요하다. SendGrid, Twilio, KYC 공급자 등 알림과 인증 관련 외부 API의 키를 .env에 설정해야 알림 전송과 문서 검증 기능이 동작한다. 또한 JWT 시크릿과 DB 접속 정보 등 보안 민감 값은 SSM Parameter Store 또는 유사한 비밀관리 시스템으로 관리하는 것이 권장된다.