hgzero/claude/logical-architecture-design.md

# 논리아키텍처설계가이드

[요청사항]
- <작성원칙>을 준용하여 설계
- <작성순서>에 따라 설계
- [결과파일] 안내에 따라 파일 작성 
- 완료 후 mermaid 스크립트 테스트 방법 안내 
  - https://mermaid.live/edit 에 접근 
  - 스크립트 내용을 붙여넣어 확인 

[가이드]  
<작성원칙>
- **유저스토리와 매칭**되어야 함. **불필요한 추가 설계 금지**
- UI/UX설계서의 '사용자 플로우'참조하여 설계 
- '아키텍처패턴'에 선정된 클라우드 디자인 패턴을 적용하여 설계 
- 사용자 관점의 컴포넌트 다이어그램 작성
- Context Map 스타일로 서비스 내부 구조는 생략하고 서비스 간 관계에 집중
- 클라이언트에서 API Gateway로는 단일 연결선으로 표현
<작성순서>
- 준비: 
  - 유저스토리, UI/UX설계서, 아키텍처패턴 분석 및 이해 
  - "@analyze --play" 프로토타입이 있는 경우 웹브라우저에서 실행하여 서비스 이해 
- 실행: 
  - 논리아키텍처 설계서(logical-architecture.md) 작성: 아래 항목은 필수 포함하고 필요 시 항목 추가 
    - 개요: 설계 원칙, 핵심 컴포넌트 정의 
    - 서비스 아키텍처 
      - 서비스별 책임 
      - 서비스 간 통신 전략 
    - 주요 사용자 플로우
    - 데이터 흐름 및 캐싱 전략
    - 확장성 및 성능 고려사항 
    - 보안 고려사항
    - 논리아키텍처 다이어그램  
      - Mermaid 형식으로 작성하며 별도 파일로 작성: logical-architecture.mmd 
      - <통신전략>과 <의존성 표현 방법>을 준수
      - **Mermaid 스크립트 파일 검사 실행**: 'Mermaid문법검사가이드' 준용
- 검토:
  - <작성원칙> 준수 검토
  - 스쿼드 팀원 리뷰: 누락 및 개선 사항 검토
  - 수정 사항 선택 및 반영  
<통신 전략>
- **동기 통신**: 즉시 응답이 필요한 단순 조회
- **캐시 우선**: 자주 사용되는 데이터는 캐시에서 직접 읽기
- **비동기 처리**: 외부 API 다중 호출 등 장시간 작업
<의존성 표현 방법>
- 실선 화살표(→): 동기적 의존성 (필수)
- 비동기 화살표(->>): 비동기 의존성 (fire-and-forget)
- 점선 화살표(-->): 선택적 의존성 또는 느슨한 결합
- 양방향 화살표(↔): 상호 의존성
- 의존성 레이블에 목적 명시 (예: "멤버 정보 조회")
- 플로우 라벨 형식: [요청서비스약어]액션 (예: [Trip]AI 일정 생성 요청)

[참고자료]
- 유저스토리
- UI/UX설계서
- 프로토타입
- 아키텍처패턴  

[예시]
- 논리아키텍처 다이어그램: https://raw.githubusercontent.com/cna-bootcamp/clauding-guide/refs/heads/main/samples/sample-논리아키텍처.mmd

[결과파일]
- design/backend/logical/logical-architecture.md
- design/backend/logical/logical-architecture.mmd