아키텍처 결정 기록 (ADR)
📋 개요
이 문서는 CheonYakPlanet 개발 과정에서 이루어진 주요 아키텍처 결정 사항들을 기록하여, 향후 참조를 위해 맥락, 근거 및 결과를 제공합니다.
📚 목차
- ADR-001: 클린 아키텍처 채택
- ADR-002: 데이터베이스 저장 방식의 JWT 인증
- ADR-003: 소프트 삭제 패턴 구현
- ADR-004: 한국 비즈니스 도메인 모델링
- ADR-005: 실시간 채팅을 위한 WebSocket
- ADR-006: 외부 API 통합 전략
- ADR-007: 데이터베이스 카탈로그 분리
- ADR-008: 데이터 동기화를 위한 비동기 처리
- ADR-010: 뉴스 콘텐츠 필터링 파이프라인
ADR-001: 클린 아키텍처 채택
배경
다수의 외부 통합 및 복잡한 비즈니스 규칙을 가진 복잡한 한국 부동산 플랫폼을 위한 확장 가능하고 유지보수 가능한 아키텍처를 구축해야 했습니다.
결정
다음과 같은 명확한 계층을 가진 클린 아키텍처(육각형 아키텍처)를 채택합니다:
- 도메인 계층: 비즈니스 엔터티 및 규칙
- 애플리케이션 계층: 유스케이스 및 비즈니스 로직 오케스트레이션
- 인프라 계층: 외부 관심사 (데이터베이스, API, 프레임워크)
- 프레젠테이션 계층: 컨트롤러 및 사용자 인터페이스 어댑터
근거
- 관심사 분리: 비즈니스 로직과 기술 구현 간의 명확한 경계
- 테스트 용이성: 인프라 종속성 없이 비즈니스 로직을 쉽게 단위 테스트 가능
- 유연성: 핵심 비즈니스 로직에 영향을 주지 않고 구현을 교체 가능
- 한국 도메인 복잡성: 복잡한 청약 규칙의 명확한 모델링 필요
- 외부 종속성: 여러 정부 API의 격리 필요
결과
긍정적:
- 격리된 비즈니스 로직으로 높은 테스트 용이성
- 이해하기 쉽고 유지보수 가능한 코드 구조
- 외부 시스템과의 유연한 통합
- 한국 비즈니스 규칙과 기술 구현 간의 명확한 분리
부정적:
- 간단한 작업에 대한 추가적인 복잡성
- 기존 계층형 아키텍처에 비해 더 많은 상용구 코드
- 클린 아키텍처에 익숙하지 않은 팀원의 학습 곡선
중립적:
ADR-002: 데이터베이스 저장 방식의 JWT 인증
배경
토큰을 폐지하고 사용자 세션을 추적할 수 있는 기능을 지원하며, 웹 및 모바일 클라이언트를 모두 지원하는 보안 인증 시스템이 필요했습니다.
결정
데이터베이스 저장 방식의 JWT(JSON 웹 토큰)를 구현합니다:
- 액세스 토큰: 60분 수명, HS256 알고리즘
- 리프레시 토큰: 24시간 수명
- 데이터베이스 저장:
user_token 테이블에 토큰 저장
- 블랙리스트: 블랙리스트 플래그를 통한 토큰 폐지 지원
근거
- 무상태 인증: JWT 토큰에 사용자 정보 포함
- 보안: 데이터베이스 저장을 통해 토큰 폐지 및 블랙리스트 가능
- 확장성: 여러 서버 인스턴스에 분산 가능
- 모바일 지원: 토큰이 모바일 애플리케이션에서 잘 작동
- 한국 정부 API: 많은 경우 보안 인증 패턴 요구
결과
긍정적:
- 보안 토큰 기반 인증
- 보안을 위한 토큰 폐지 기능
- 무상태 검증으로 좋은 성능
- 다양한 클라이언트 유형 지원
부정적:
- 토큰 유효성 검사를 위한 데이터베이스 종속성
- 순수한 무상태 JWT보다 약간 더 복잡함
- 토큰 저장에 만료된 항목 정리 필요
중립적:
ADR-003: 소프트 삭제 패턴 구현
배경
감사 목적을 위해 이력 데이터를 유지하도록 요구합니다. 사용자 데이터 및 구독 정보는 사용자가 "삭제"하더라도 보존되어야 합니다.
결정
포괄적인 소프트 삭제 패턴을 구현합니다:
- 모든 엔터티에
deleted_at 및 deleted_by 필드 추가
- 자동 처리를 위해
SoftDeleteListener 사용
- 모든 쿼리에
WHERE deleted_at IS NULL 포함
- 소프트 삭제를 통해 참조 무결성 유지
근거
- 규제 준수: 한국 데이터 보존 요구 사항
- 감사 추적: 모든 작업의 완전한 기록
- 데이터 복구: 실수로 삭제된 데이터 복원 기능
- 비즈니스 인텔리전스: 이력 분석 기능
- 사용자 신뢰: 필요한 경우 사용자가 데이터를 복구할 수 있음
결과
긍정적:
- 규정 준수를 위한 전체 감사 추적
- 데이터 복구 기능
- 참조 무결성 유지
- 이력 분석 가능
부정적:
- 데이터베이스 저장 공간 요구 사항 증가
- 더 복잡한 쿼리 (항상 deleted_at 확인 포함)
- 올바르게 처리하지 않을 경우 데이터 혼란 가능성
중립적:
ADR-004: 한국 비즈니스 도메인 모델링
배경
한국 부동산 청약 시스템은 시스템에 정확하게 모델링되어야 하는 복잡한 규칙과 용어를 가지고 있습니다.
결정
도메인별 엔터티 및 값 객체를 생성합니다:
- 데이터베이스에 한국어 필드명 사용 (예:
house_nm, rcept_bgnde)
- 복잡한 순위 시스템 모델링 (1순위/2순위)
- 특별 공급 카테고리 (다자녀, 신혼부부, 생애최초)
- 행정 계층 (시/도, 시/군/구, 읍/면/동)
- 사용자 프로필에 통합된 재정 자격 규칙
근거
- 도메인 정확성: 실제 한국 비즈니스 프로세스 반영
- 사용자 이해: 한국 사용자가 익숙한 용어 이해
- 정부 API 정렬: 정부 데이터 구조와 일치
- 비즈니스 규칙: 복잡한 자격 계산에 정확한 모델링 필요
- 규제 준수: 공식적인 한국 주택 규칙과 일치해야 함
결과
긍정적:
- 한국 부동산 도메인의 정확한 표현
- 정부 API와의 쉬운 통합
- 명확한 비즈니스 규칙 구현
- 사용자 친화적인 한국어 용어
부정적:
- 비한국어 개발자의 학습 곡선
- 문서에서 한국 비즈니스 개념을 설명해야 함
- 복잡한 비즈니스 규칙은 신중한 테스트 필요
중립적:
ADR-005: 실시간 채팅을 위한 WebSocket
배경
한국 부동산 질문에 대한 사용자에게 실시간 AI 채팅 지원이 필요했습니다. 보안을 유지하면서 낮은 지연 시간 통신을 지원해야 했습니다.
결정
WebSocket 기반 채팅 시스템을 구현합니다:
- 핸드셰이크 인터셉터를 통한 JWT 인증
- 일일 사용량 제한 (사용자당 15개 메시지)
- 자동 정리를 통한 세션 관리
- 한국 부동산 전문 지식을 위한 Gemini 2.0 AI 통합
근거
- 실시간 통신: 사용자 질문에 대한 즉각적인 응답
- 보안: 보안 연결을 위한 JWT 기반 인증
- 성능: WebSocket 오버헤드가 폴링보다 낮음
- 사용자 경험: 실제 채팅 대화처럼 느껴짐
- 자원 관리: 사용량 제한으로 남용 방지
결과
긍정적:
- 실시간 응답으로 뛰어난 사용자 경험
- 보안 인증 통합
- 효율적인 자원 사용
- 많은 동시 사용자로 확장 가능
부정적:
- 기존 REST API보다 복잡함
- WebSocket 인프라 지원 필요
- 연결 상태 관리 복잡성
중립적:
ADR-006: 외부 API 통합 전략
배경
청약 데이터, 뉴스, 지도, 금융 정보를 위해 여러 한국 정부 및 상업 API와 통합해야 했습니다.
결정
탄력적인 API 통합 전략을 구현합니다:
- 재시도 메커니즘: 지수 백오프를 통한 구성 가능한 재시도
- 회로 차단기 패턴: 외부 서비스가 다운될 때 빠르게 실패
- 속도 제한: 외부 API 속도 제한 준수
- 비동기 처리: 병렬 API 호출을 위해 CompletableFuture 사용
- 점진적 업데이트: 중복을 피하기 위해 처리된 데이터 추적
근거
- 신뢰성: 외부 API는 신뢰할 수 없거나 속도 제한이 있을 수 있음
- 성능: 병렬 처리가 데이터 동기화 속도 향상
- 비용 관리: 불필요한 API 호출 방지
- 데이터 무결성: 점진적 업데이트로 중복 처리 방지
- 한국 정부 API: 엄격한 속도 제한 및 가용 시간대가 있는 경우가 많음
결과
긍정적:
- 외부 API 실패에 대한 강력한 처리
- 효율적인 데이터 동기화
- 비용 효율적인 API 사용
- 추가 외부 서비스로 확장 가능
부정적:
- 통합 코드의 복잡성 증가
- 통합 문제 디버깅이 더 어려움
- 외부 종속성에 대한 모니터링 및 알림 필요
중립적:
ADR-007: 데이터베이스 카탈로그 분리
배경
데이터베이스 객체의 명확한 구성과 다양한 한국 지역 또는 사업부를 위한 잠재적인 미래 다중 테넌시 지원이 필요했습니다.
결정
catalog = "planet"을 사용하여 MySQL 카탈로그 분리를 사용합니다:
- 전용 카탈로그의 모든 애플리케이션 테이블
- 시스템 테이블과의 명확한 네임스페이스 분리
- 다중 테넌트 아키텍처를 위한 미래 대비
- 간소화된 백업 및 마이그레이션 절차
근거
- 구성: 애플리케이션 데이터의 명확한 분리
- 보안: 애플리케이션이 시스템 테이블에 접근할 수 없음
- 백업 전략: 카탈로그 수준 백업 기능
- 다중 테넌시: 향후 지역 분리를 위한 기반
- 한국 배포: 지역별 데이터 격리 필요 가능성
결과
긍정적:
- 깔끔한 데이터베이스 구성
- 분리를 통한 향상된 보안
- 유연한 배포 옵션
- 다중 테넌시를 위한 미래 대비
부정적:
- 추가적인 구성 복잡성
- 모든 쿼리가 카탈로그를 지정해야 함
- 엔터티 어노테이션이 약간 더 장황함
중립적:
ADR-008: 데이터 동기화를 위한 비동기 처리
배경
정부 API 데이터 동기화 프로세스는 대량의 데이터를 처리하며 사용자 대면 작업을 차단해서는 안 됩니다. 한국 정부 API는 가용 시간대가 제한적입니다.
결정
포괄적인 비동기 처리를 구현합니다:
- 예약된 작업: 일간/주간/월간 데이터 동기화
- 스레드 풀 관리: 사용 가능한 CPU 코어에 최적화
- CompletableFuture: API 호출의 병렬 처리
- 트랜잭션 격리: 별도의 트랜잭션의 각 API 호출
- 진행 상황 추적: 동기화 진행 상황 모니터링
근거
- 성능: 데이터 동기화 중 사용자 작업 차단 방지
- 신뢰성: 격리된 트랜잭션으로 부분 실패 방지
- 자원 활용: 사용 가능한 처리 능력의 효율적인 사용
- 한국 정부 API: API 시간대 및 속도 제한 준수 필요
- 사용자 경험: 백그라운드 처리 중에도 시스템 응답성 유지
결과
긍정적:
- 뛰어난 시스템 응답성
- 효율적인 자원 활용
- 강력한 오류 처리 및 복구
- 추가 데이터 소스로 확장 가능
부정적:
- 작업 관리의 복잡성 증가
- 비동기 작업 디버깅이 더 어려움
- 백그라운드 프로세스 모니터링 필요
중립적:
ADR-010: 뉴스 콘텐츠 필터링 파이프라인
배경
한국 부동산 뉴스 집계는 스팸 및 홍보 자료를 피하면서 고품질의 관련 콘텐츠를 제공하기 위해 정교한 필터링이 필요합니다.
결정
다단계 콘텐츠 필터링 파이프라인을 구현합니다:
- 소스 유효성 검사: 30개 이상의 신뢰할 수 있는 한국 뉴스 도메인
- 키워드 관련성: 점수 매기기가 포함된 20개 이상의 부동산 키워드
- 스팸 방지 필터링: 강력/약한 광고 키워드 감지
- 콘텐츠 품질: 최소 길이 및 형식 요구 사항
- 자동 분류: 정책, 청약, 시장 뉴스
- 일일 요약: 구조화된 마크다운 보고서
근거
- 콘텐츠 품질: 사용자에게 고가치 정보 제공
- 사용자 신뢰: 스팸 및 홍보 콘텐츠 방지
- 한국 시장: 특정 한국 부동산 용어 이해
- 자동화: 수동 검토 없이 콘텐츠 처리 확장
- 비즈니스 가치: 분류된 뉴스는 더 나은 사용자 경험 제공
결과
긍정적:
- 고품질의 관련 뉴스 콘텐츠
- 자동화된 콘텐츠 큐레이션으로 수동 작업 절약
- 분류된 콘텐츠로 사용자 참여도 향상
- 스팸 및 광고 효과적으로 필터링
부정적:
- 복잡한 필터링 로직에 유지보수 필요
- 때때로 합법적인 콘텐츠를 필터링할 수 있음
- 키워드 목록은 주기적인 업데이트 필요
중립적:
🔄 결정 검토 프로세스
검토 일정
- 월간: 최근 결정의 효율성 검토
- 분기별: 주요 아키텍처 선택 사항 평가
- 연간: 포괄적인 아키텍처 검토
평가 기준
- 성능 영향: 결정이 시스템 성능에 미치는 영향
- 유지보수 부담: 지속적인 개발 및 운영 비용
- 비즈니스 가치: 비즈니스 목표와의 정렬
- 기술 부채: 기술적 복잡성의 축적
- 한국 시장 적합성: 한국 부동산 도메인에서의 효율성
결정 수정 프로세스
1. 문제 식별: 현재 접근 방식의 문제점 문서화
2. 대안 분석: 대안 솔루션 평가
3. 영향 평가: 변경의 결과 이해
4. 팀 합의: 관련 이해관계자의 동의 얻기
5. 구현 계획: 필요한 경우 마이그레이션 전략 생성
6. 문서 업데이트: 새로운 결정을 포함하여 ADR 수정
📚 관련 문서
아키텍처 결정 버전: 1.0
최종 업데이트: 2025-06-26
다음 검토: 2025-07-19