add logical architecture

2025-10-21 17:38:07 +09:00
parent bd07ef0cce
commit 597e3716e7
7 changed files with 1505 additions and 0 deletions
@@ -0,0 +1,197 @@
+# 공통설계원칙
+
+모든 설계 단계에서 공통으로 적용되는 핵심 원칙과 전략
+
+## 🎯 핵심 원칙
+
+### 1. 🚀 실행 우선 원칙
+- **프롬프트 우선**: 바로 실행할 수 있는 프롬프트로 작업 시작
+- **가이드 학습**: 원리와 방법론은 가이드로 깊이 있게 학습
+- **점진적 이해**: 실행 → 결과 확인 → 원리 학습 순서
+
+### 2. 🔄 병렬 처리 전략
+- **서브 에이전트 활용**: Task 도구로 서비스별 동시 작업
+- **의존성 기반 그룹화**: 의존 관계에 따른 순차/병렬 처리 결정
+- **통합 검증**: 병렬 작업 완료 후 전체적 일관성 검증
+
+### 3. 🏗️ 마이크로서비스 설계 원칙
+- **서비스 독립성**: 캐시를 통한 직접 의존성 최소화
+- **선택적 비동기**: 장시간 작업(AI 일정 생성)만 비동기 처리
+- **캐시 우선**: Redis를 통한 성능 최적화
+- **독립 배포**: 서비스별 독립적 배포 가능한 구조
+
+### 4. 📝 표준화 원칙
+- **PlantUML**: 모든 다이어그램 표준 (`!theme mono`)
+- **OpenAPI 3.0**: API 명세 표준
+- **자동 검증**: PlantUML, OpenAPI 문법 검사 필수
+- **일관된 네이밍**: kebab-case 파일명, 표준화된 스키마명
+
+### 5. ✅ 검증 우선 원칙
+- **각 단계마다 자동 검증**: 품질 보장
+- **실시간 피드백**: 오류 조기 발견 및 수정
+- **CI/CD 통합**: 자동화된 검증 프로세스
+- **PlantUML 스크립트 파일 생성 즉시 검사 실행**: 'PlantUML 문법 검사  가이드' 준용 
+
+### 6. 🚀 점진적 구현 원칙
+- **MVP → 확장 → 고도화**: 단계별 접근
+- **YAGNI 적용**: 꼭 필요한 기능만 구현(YAGNI원칙:You aren't gonna need it)
+- **지속적 개선**: 피드백 기반 점진적 발전
+
+## 🔧 의존성 분석 및 병렬 처리
+
+### 의존성 분석 방법
+
+1. **서비스 간 의존성 파악**
+   ```
+   일정 서비스 → 프로파일 서비스 (멤버/여행 정보 조회)
+   일정 서비스 → 장소 서비스 (장소 정보 조회)  
+   장소 서비스: 독립적 (외부 API만 사용)
+   ```
+
+2. **의존성 기반 그룹화**
+   ```
+   Group A (순차 처리): 프로파일 → 일정 서비스
+   Group B (독립 처리): 장소 서비스
+   ```
+
+3. **에이전트 할당 및 병렬 처리**
+   ```
+   Agent 1: Group A 담당
+     - 프로파일 서비스 설계
+     - 일정 서비스 설계 (프로파일 참조)
+   
+   Agent 2: Group B 담당  
+     - 장소 서비스 설계 (독립적)
+   ```
+
+### 병렬 처리 적용 가이드
+
+#### API 설계 단계
+- **독립 서비스**: 각각 별도 에이전트
+- **의존 서비스**: 동일 에이전트 내 순차 처리
+- **공통 검증**: 모든 에이전트 완료 후 swagger-cli 검증
+
+#### 시퀀스 설계 단계
+- **외부 시퀀스**: 플로우별 병렬 처리 (각 플로우는 독립적)
+- **내부 시퀀스**: 서비스별 병렬 처리 (서비스 내부는 독립적)
+
+#### 클래스/데이터 설계 단계
+- **의존성 그룹별**: 참조 관계가 있는 서비스들은 순차 처리
+- **독립 서비스**: 병렬 처리
+- **공통 클래스**: 모든 서비스 설계 완료 후 마지막 처리
+  
+## 🎨 PlantUML 작성 표준
+
+### 기본 템플릿
+```plantuml
+@startuml
+!theme mono
+
+title [다이어그램 제목]
+
+' 다이어그램 내용
+@enduml
+```
+
+### 필수 검증
+- **각 파일 생성 직후 PlantUML 문법 검사 수행**
+- **파이프 방식 권장**: `cat "파일" | docker exec -i plantuml ...`
+- **화살표 문법 주의**: sequence diagram에서 `..>` 사용 금지
+
+### 스타일 가이드
+- **폰트 크기**: 적절한 가독성 확보
+- **색상 구분**: 서비스별, 레이어별 색상 구분
+- **설명 추가**: note를 활용한 상세 설명
+
+## 🔌 API 설계 표준
+
+### 파일 구조
+```
+design/backend/api/{service-name}-api.yaml
+```
+
+### 필수 필드
+```yaml
+paths:
+  /endpoint:
+    get:
+      summary: API 목적 설명
+      operationId: 고유 식별자
+      x-user-story: 유저스토리 ID
+      x-controller: 담당 컨트롤러
+      tags: [API 그룹]
+```
+
+### 스키마 원칙
+- **서비스별 독립**: 각 서비스 파일에 모든 스키마 포함
+- **중복 허용**: 초기에는 중복을 허용하고 점진적으로 공통화
+- **명확한 네이밍**: Request/Response DTO 네이밍 표준
+
+## 🔄 시퀀스 설계 표준
+
+### 외부 시퀀스 (서비스 간)
+- **참여 서비스만**: 해당 플로우에 참여하는 서비스만 표시
+- **API 호출 중심**: 서비스 간 API 호출 순서 표현
+- **한글 설명**: 각 호출의 목적을 한글로 명시
+
+### 내부 시퀀스 (서비스 내부)
+- **모든 API 표시**: 해당 서비스의 모든 API 포함
+- **내부 처리 흐름**: 컨트롤러 → 서비스 → 레포지토리 플로우
+- **기술적 세부사항**: 캐시, DB 접근 등 포함
+
+### 동기/비동기 구분
+- **실선 (→)**: 동기 호출
+- **점선 (->>)**: 비동기 호출  
+- **양방향**: 필요시에만 사용
+
+## 📊 클래스 설계 표준
+
+### 아키텍처 적용
+- **Clean Architecture**: Port/Adapter 용어 대신 표준 Clean 용어 사용
+- **멀티프로젝트**: 서비스별 독립 모듈
+- **패키지 구조 표준**: 일관된 패키지 구조 적용
+
+### 관계 표현
+- **Generalization**: 상속 관계
+- **Realization**: 인터페이스 구현
+- **Dependency**: 의존 관계  
+- **Association**: 연관 관계
+- **Aggregation/Composition**: 집약/합성 관계
+
+### 상세 정보
+- **프로퍼티와 메소드**: 모두 명시
+- **접근 제한자**: 적절한 가시성 설정
+- **타입 정보**: 정확한 데이터 타입 명시
+
+## 🗄️ 데이터 설계 표준  
+
+### 서비스별 DB 분리
+- **각 서비스마다 독립적인 데이터베이스**
+- **서비스 간 데이터 공유 최소화**
+- **캐시를 통한 성능 최적화**
+
+### 클래스 설계와 일치
+- **Entity 클래스와 테이블 매핑**
+- **일관된 네이밍 컨벤션**
+- **적절한 정규화 수준**
+
+## 🚨 주의사항
+
+### PlantUML 문법
+- **sequence diagram에서 `..>` 사용 금지**
+- **비동기는 `->>` 또는 `-->>` 사용**
+- **테마는 반드시 `mono` 사용**
+  
+### 병렬 처리
+- **의존성 분석 선행**: 병렬 처리 전 반드시 의존성 파악
+- **순차 처리 필요시**: 무리한 병렬화보다는 안전한 순차 처리
+- **검증 단계 필수**: 병렬 처리 후 통합 검증
+
+### API 설계
+- **유저스토리 ID 필수**: x-user-story 필드 누락 금지
+- **Controller 명시**: x-controller 필드로 담당 컨트롤러 명시
+- **스키마 완전성**: 모든 Request/Response 스키마 정의
+
+---
+
+💡 **이 원칙들은 모든 설계 단계에서 일관되게 적용되어야 하며, 각 단계별 세부 가이드에서 구체적으로 구현됩니다.**
@@ -0,0 +1,64 @@
+# 논리아키텍처설계가이드
+
+[요청사항]
+- <작성원칙>을 준용하여 설계
+- <작성순서>에 따라 설계
+- [결과파일] 안내에 따라 파일 작성 
+- 완료 후 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
@@ -0,0 +1,300 @@
+# Mermaid문법검사가이드
+
+## 개요
+
+Mermaid 다이어그램의 문법 오류를 사전에 검출하여 렌더링 실패를 방지하기 위한 가이드입니다. Docker 기반 Mermaid CLI를 활용하여 로컬에서 빠르게 문법을 검증할 수 있습니다.
+
+## Mermaid CLI 서버 설치 및 검사
+
+### Docker로 Mermaid CLI 컨테이너 실행
+
+```bash
+# Mermaid CLI 컨테이너가 실행 중인지 확인
+docker ps | grep mermaid-cli
+
+# ⚠️ 중요: 첫 실행 시 이미지 다운로드를 먼저 진행 (큰 이미지로 인한 타임아웃 방지)
+docker pull minlag/mermaid-cli:latest
+
+# Mermaid CLI 컨테이너가 없으면 설치 및 실행 (root 권한으로 실행, 포트 48080 사용)
+docker run -d --rm --name mermaid-cli -u root -p 48080:8080 --entrypoint sh minlag/mermaid-cli:latest -c "while true;do sleep 3600; done"
+
+# 컨테이너 상태 확인
+docker logs mermaid-cli
+```
+
+#### 💡 Docker 이미지 다운로드 관련 주의사항
+
+**첫 실행 시 발생할 수 있는 문제:**
+- `minlag/mermaid-cli:latest` 이미지가 큰 용량(약 700MB+)이므로 다운로드에 시간이 오래 걸림
+- `docker run` 명령 실행 시 이미지가 없으면 자동 다운로드하지만 타임아웃 발생 가능
+- **해결방법**: `docker pull` 명령으로 이미지를 먼저 다운로드한 후 컨테이너 실행
+
+**권장 실행 순서:**
+1. `docker pull minlag/mermaid-cli:latest` (이미지 다운로드)
+2. `docker run` 명령으로 컨테이너 실행
+3. 필수 설정 진행
+
+#### ⚠️ 중요: 최초 컨테이너 생성 후 필수 설정
+
+Mermaid CLI는 Puppeteer를 사용하여 다이어그램을 렌더링하므로 Chromium 브라우저가 필요합니다. 
+컨테이너를 처음 생성한 후 다음 명령을 실행하여 필요한 패키지를 설치해야 합니다:
+
+```bash
+# Chromium 및 필요한 종속성 설치
+docker exec mermaid-cli sh -c "apk add --no-cache chromium chromium-chromedriver nss freetype harfbuzz ca-certificates ttf-freefont"
+
+# Puppeteer가 사용할 설정 파일 생성
+docker exec mermaid-cli sh -c "echo '{\"executablePath\": \"/usr/bin/chromium-browser\", \"args\": [\"--no-sandbox\", \"--disable-setuid-sandbox\", \"--disable-dev-shm-usage\"]}' > /tmp/puppeteer-config.json"
+```
+
+이 설정은 컨테이너가 실행되는 동안 유지되므로 한 번만 실행하면 됩니다.
+
+문법검사 후 Container를 중지하지 않고 계속 사용함 
+
+## 문법 검사 방법
+현재 OS에 맞게 수행.
+
+### Linux/macOS 버전
+**스크립트 파일(tools/check-mermaid.sh)을 이용하여 수행**
+
+1. tools/check-mermaid.sh 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "Mermaid문법검사기(Linux/Mac)"를 tools/check-mermaid.sh 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+
+```bash
+# 1. 스크립트 실행 권한 부여 (최초 1회)
+chmod +x tools/check-mermaid.sh
+
+# 2. 문법 검사 실행
+./tools/check-mermaid.sh {검사할 파일}
+
+# 예시
+./tools/check-mermaid.sh design/backend/physical/physical-architecture.mmd
+```
+
+### Windows PowerShell 버전
+**스크립트 파일(tools/check-mermaid.ps1)을 이용하여 수행**
+
+1. tools/check-mermaid.ps1 파일 존재 여부 확인 
+2. 스크립트 파일이 없으면 "Mermaid문법검사기(Window)"를 tools/check-mermaid.ps1 파일로 다운로드하여 스크립트 파일을 만듦
+3. 스크립트 파일이 있으면 그 스크립트 파일을 이용하여 검사
+
+```powershell
+# 문법 검사 실행
+.\tools\check-mermaid.ps1 {검사할 파일}
+
+# 예시
+.\tools\check-mermaid.ps1 design\backend\physical\physical-architecture.mmd
+```
+
+### 수동 검사 방법 (스크립트 없이)
+
+```bash
+# 1. 고유 파일명 생성 (충돌 방지)
+TEMP_FILE="/tmp/mermaid_$(date +%s)_$$.mmd"
+
+# 2. 파일 복사
+docker cp {검사할 파일} mermaid-cli:${TEMP_FILE}
+
+# 3. 문법 검사 (Puppeteer 설정 파일 사용)
+docker exec mermaid-cli sh -c "cd /home/mermaidcli && node_modules/.bin/mmdc -i ${TEMP_FILE} -o /tmp/output.svg -p /tmp/puppeteer-config.json -q"
+
+# 4. 임시 파일 삭제
+docker exec mermaid-cli rm -f ${TEMP_FILE} /tmp/output.svg
+```
+
+**주의**: Puppeteer 설정 파일(`/tmp/puppeteer-config.json`)이 있어야 합니다. 없다면 위의 "최초 컨테이너 생성 후 필수 설정"을 먼저 실행하세요.
+
+### 검사 결과 해석
+
+| 출력 | 의미 | 대응 방법 |
+|------|------|-----------|
+| "Success: Mermaid syntax is valid!" | 문법 오류 없음 ✅ | 정상, 렌더링 가능 |
+| "Parse error on line X" | X번째 줄 구문 오류 ❌ | 해당 라인 문법 확인 |
+| "Expecting 'XXX'" | 예상 토큰 오류 ❌ | 누락된 문법 요소 추가 |
+| "Syntax error" | 일반 문법 오류 ❌ | 전체 구조 재검토 |
+
+## Mermaid 다이어그램 타입별 주의사항
+
+### 1. Graph/Flowchart
+```mermaid
+graph TB
+    %% 올바른 사용법 ✅
+    A[Node A] --> B[Node B]
+    C[Node C] -.-> D[Node D]
+    E[Node E] ==> F[Node F]
+    
+    %% 주의사항
+    %% - 노드 ID에 공백 불가 (대신 [Label] 사용)
+    %% - subgraph와 end 개수 일치 필요
+    %% - 따옴표 안에서 특수문자 주의
+```
+
+### 2. Sequence Diagram
+```mermaid
+sequenceDiagram
+    %% 올바른 사용법 ✅
+    participant A as Service A
+    participant B as Service B
+    
+    A->>B: Request
+    B-->>A: Response
+    A->>+B: Call with activation
+    B-->>-A: Return with deactivation
+    
+    %% 주의사항
+    %% - participant 선언 권장
+    %% - 활성화(+)/비활성화(-) 쌍 맞추기
+    %% - Note 블록 종료 확인
+```
+
+### 3. Class Diagram
+```mermaid
+classDiagram
+    %% 올바른 사용법 ✅
+    class Animal {
+        +String name
+        +int age
+        +makeSound() void
+    }
+    
+    class Dog {
+        +String breed
+        +bark() void
+    }
+    
+    Animal <|-- Dog : inherits
+    
+    %% 주의사항
+    %% - 메서드 괄호 필수
+    %% - 관계 표현 정확히
+    %% - 접근 제한자 기호 확인
+```
+
+### 4. State Diagram
+```mermaid
+stateDiagram-v2
+    %% 올바른 사용법 ✅
+    [*] --> Idle
+    Idle --> Processing : start
+    Processing --> Completed : finish
+    Processing --> Error : error
+    Error --> Idle : reset
+    Completed --> [*]
+    
+    %% 주의사항
+    %% - [*]는 시작/종료 상태
+    %% - 상태 이름에 공백 불가
+    %% - 전이 레이블 콜론(:) 사용
+```
+
+## 일반적인 오류와 해결 방법
+
+### 1. 괄호 불균형
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A[Node (with parenthesis)]  %% 괄호 안에 괄호
+    
+%% 올바른 예 ✅
+graph TB
+    A[Node with parenthesis]
+```
+
+### 2. 특수 문자 이스케이프
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A[Security & Management]  %% & 문자 직접 사용
+    
+%% 올바른 예 ✅
+graph TB
+    A[Security &amp; Management]  %% HTML 엔티티 사용
+```
+
+### 3. subgraph/end 불일치
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    subgraph One
+        A --> B
+        subgraph Two
+            C --> D
+    end  %% Two만 닫힘, One은 안 닫힘
+    
+%% 올바른 예 ✅
+graph TB
+    subgraph One
+        A --> B
+        subgraph Two
+            C --> D
+        end
+    end  %% 모든 subgraph 닫기
+```
+
+### 4. 노드 참조 오류
+```mermaid
+%% 잘못된 예 ❌
+graph TB
+    A --> UnknownNode  %% 정의되지 않은 노드
+    
+%% 올바른 예 ✅
+graph TB
+    A[Node A] --> B[Node B]  %% 모든 노드 정의
+```
+
+## 컨테이너 관리
+
+### 컨테이너 중지 및 삭제
+```bash
+# 컨테이너 중지
+docker stop mermaid-cli
+
+# 컨테이너 삭제
+docker rm mermaid-cli
+
+# 한 번에 중지 및 삭제
+docker stop mermaid-cli && docker rm mermaid-cli
+```
+
+### 컨테이너 재시작
+```bash
+# 컨테이너 재시작
+docker restart mermaid-cli
+```
+
+## 성능 최적화 팁
+
+1. **컨테이너 유지**: 검사 후 컨테이너를 중지하지 않고 유지하여 다음 검사 시 빠르게 실행
+2. **배치 검사**: 여러 파일을 연속으로 검사할 때 컨테이너 재시작 없이 진행
+3. **로컬 파일 사용**: 네트워크 경로보다 로컬 파일 경로 사용 권장
+
+## 문제 해결
+
+### Docker 관련 오류
+```bash
+# Docker 데몬 실행 확인
+docker ps
+
+# Docker Desktop 시작 (Windows/Mac)
+# Docker 서비스 시작 (Linux)
+sudo systemctl start docker
+```
+
+### 권한 오류
+```bash
+# Linux/Mac에서 스크립트 실행 권한
+chmod +x tools/check-mermaid.sh
+
+# Docker 권한 (Linux)
+sudo usermod -aG docker $USER
+```
+
+### 컨테이너 이미지 오류
+```bash
+# 이미지 재다운로드
+docker pull minlag/mermaid-cli:latest
+
+# 기존 컨테이너 삭제 후 재생성
+docker stop mermaid-cli && docker rm mermaid-cli
+```
@@ -0,0 +1,83 @@
+graph TB
+    %% TripGen 논리 아키텍처 - Context Map
+    
+    %% Client Layer
+    subgraph "Client Layer"
+        Mobile["모바일 클라이언트"]
+    end
+    
+    %% Gateway Layer
+    subgraph "Gateway Layer"
+        Gateway["API Gateway<br/>• 인증/인가<br/>• 라우팅<br/>• 로드밸런싱"]
+    end
+    
+    %% Service Layer
+    subgraph "Service Layer"
+        UserSvc["User Service<br/>• 사용자 인증<br/>• 프로필 관리<br/>• 세션 관리"]
+        TripSvc["Trip Service<br/>• 여행 관리<br/>• 멤버 설정<br/>• 일정 조회"]
+        AISvc["AI Service<br/>• 일정 생성<br/>• 맞춤 추천<br/>• 날씨 반영"]
+        LocationSvc["Location Service<br/>• 장소 검색<br/>• 상세 정보<br/>• 리뷰 통합"]
+    end
+    
+    %% Data Layer
+    subgraph "Data Layer"
+        Cache["Redis Cache<br/>• 세션 정보<br/>• 장소 데이터<br/>• AI 결과"]
+        Queue["Message Queue<br/>• AI 작업 큐<br/>• Priority Queue<br/>• Location 비동기"]
+    end
+    
+    %% External APIs
+    subgraph "External APIs"
+        Claude["Claude API"]
+        Kakao["카카오맵 API"]
+        Google["구글맵 API"]
+        Weather["날씨 API"]
+    end
+    
+    %% Client to Gateway (단일 연결)
+    Mobile -->|HTTPS| Gateway
+    
+    %% Gateway to Services (동기)
+    Gateway -->|인증/프로필| UserSvc
+    Gateway -->|여행 관리| TripSvc
+    Gateway -->|장소 검색| LocationSvc
+    
+    %% Service Dependencies
+    TripSvc -.->|"AI 일정 생성 요청<br/>(비동기)"| Queue
+    Queue -.->|작업 처리| AISvc
+    
+    %% AI Service Dependencies
+    AISvc -.->|"장소 정보 조회<br/>(Cache-Aside)"| Cache
+    AISvc -.->|"Location 요청<br/>(Async Fallback)"| Queue
+    Queue -.->|백그라운드 처리| LocationSvc
+    
+    %% Cache Dependencies
+    UserSvc -.->|세션 관리| Cache
+    TripSvc -.->|여행 정보| Cache
+    LocationSvc -.->|장소 캐싱| Cache
+    
+    %% External API Dependencies
+    AISvc -->|일정 생성| Claude
+    LocationSvc -->|장소 검색| Kakao
+    LocationSvc -->|상세/리뷰| Google
+    LocationSvc -->|날씨 조회| Weather
+    
+    %% Styling
+    classDef client fill:#BFDBFE,stroke:#3B82F6,stroke-width:2px
+    classDef gateway fill:#2E86AB,stroke:#1E3A8A,stroke-width:2px,color:#fff
+    classDef user fill:#4ECDC4,stroke:#14B8A6,stroke-width:2px
+    classDef trip fill:#F18F01,stroke:#F97316,stroke-width:2px
+    classDef ai fill:#10B981,stroke:#059669,stroke-width:2px
+    classDef location fill:#8B5CF6,stroke:#7C3AED,stroke-width:2px,color:#fff
+    classDef cache fill:#F59E0B,stroke:#F97316,stroke-width:2px
+    classDef queue fill:#EC4899,stroke:#DB2777,stroke-width:2px
+    classDef external fill:#E5E7EB,stroke:#9CA3AF,stroke-width:2px
+    
+    class Mobile client
+    class Gateway gateway
+    class UserSvc user
+    class TripSvc trip
+    class AISvc ai
+    class LocationSvc location
+    class Cache cache
+    class Queue queue
+    class Claude,Kakao,Google,Weather external