diff --git a/docs/architecture/frontend-architecture-strategy.md b/docs/architecture/frontend-architecture-strategy.md new file mode 100644 index 0000000..dbd753c --- /dev/null +++ b/docs/architecture/frontend-architecture-strategy.md @@ -0,0 +1,279 @@ +# 프론트엔드 아키텍처 전략 + +**날짜**: 2025-07-29 +**작성자**: admin@51123 & Claude +**문서 유형**: 아키텍처 설계 결정 + +## 개요 + +로빙 프로젝트의 프론트엔드 서비스 배치 전략과 데이터 흐름을 정의합니다. 게임형 사용자 인터페이스(frontend-customer)의 최적 서버 배치, 인증 체계, 데이터 관리, 그리고 서버 간 통신 아키텍처를 다룹니다. + +## 1. 전체 시스템 아키텍처 + +### 1.1 서버별 역할 정의 + +#### 51123 서버 (Frontend Hub + Data Center) +- **역할**: 사용자 접점, 인증, 데이터 중앙 관리 +- **주요 서비스**: + - nginx 리버스 프록시 (80/443) + - auth-server (9000) - 멀티테넌트 인증 + - frontend-base (8000) - 관리자 대시보드 + - frontend-customer (정적 서빙) - 게임형 UI + - PostgreSQL (5432) - 중앙 데이터베이스 + - Gitea (3000) + Actions Runner - CI/CD + +#### 51124 서버 (Backend Services) +- **역할**: AI 처리 로직, 실시간 서비스 +- **주요 서비스**: + - 로빙 서비스들 (rb8001, rb10508, rb10408) + - 스킬 서비스들 (skill_email, skill_news) + - State Service (8010, 신규 제안) + - ChromaDB - 벡터 데이터베이스 + +### 1.2 데이터 흐름 아키텍처 + +``` +[사용자 브라우저] + ↓ +[nginx@51123] ─── 정적 파일 서빙 (React 게임 UI) + ├─ /auth/* → auth-server (인증) + ├─ /admin/* → frontend-base (관리) + ├─ /game/* → 정적 파일 (게임 UI) + └─ /api/robbing/* → State Service@51124 (프록시) + └─ PostgreSQL@51123 (데이터 저장) +``` + +## 2. 프론트엔드 서비스 상세 설계 + +### 2.1 frontend-customer (게임형 UI) + +#### 배치 방식: nginx 정적 서빙 +- **위치**: `/var/www/game/` +- **이유**: + - 최고 성능의 정적 파일 서빙 + - 게임 리소스(이미지, 애니메이션) 캐싱 최적화 + - CDN-like 설정 가능 + - 51123 인프라 패턴과 일치 + +#### 기술 스택 +- React 18 + TypeScript + Vite +- Framer Motion (애니메이션) +- Lottie (캐릭터 애니메이션) +- WebSocket (실시간 통신) + +#### 주요 기능 +- 로빙 캐릭터 상호작용 UI +- 실시간 레벨/스탯 시각화 +- 스킬 해금 애니메이션 +- 3분할 레이아웃 (GUI|채팅|상태) + +### 2.2 frontend-base (관리자 대시보드) + +#### 배치 방식: Docker 컨테이너 +- **포트**: 8000 +- **현재 상태**: 이미 운영 중 +- **역할**: B2B 관리 기능 + +### 2.3 역할 분리 전략 + +| 서비스 | 대상 | 주요 기능 | 배치 방식 | +|--------|------|-----------|-----------| +| frontend-customer | B2C 최종 사용자 | 게임형 로빙 인터랙션 | nginx 정적 서빙 | +| frontend-base | B2B 관리자 | 시스템 관리, 모니터링 | Docker 컨테이너 | + +## 3. 데이터베이스 아키텍처 + +### 3.1 중앙집중식 데이터 관리 + +```sql +-- PostgreSQL@51123:5432 +├── auth_db (기존) +│ ├── companies +│ └── slack_workspaces +│ +└── robbing_db (신규 제안) + ├── users -- 사용자 기본정보 + ├── user_stats -- 레벨, 스탯 (연산, 기억, 공감, 통솔, 반응) + ├── user_skills -- 스킬 레벨 및 사용량 + └── skill_growth_logs -- 스킬 성장 이력 +``` + +### 3.2 State Service 설계 + +**위치**: 51124 서버 (포트 8010) +**역할**: 로빙 상태 관리 API + +```python +# 주요 엔드포인트 +GET /api/robbing/stats/{user_id} # 사용자 스탯 조회 +POST /api/robbing/levelup # 레벨업 처리 +GET /api/robbing/skills/{user_id} # 스킬 상태 조회 +WS /ws/robbing/realtime # 실시간 상태 업데이트 +``` + +## 4. 인증 및 로그인 체계 + +### 4.1 로그인 페이지 배치 + +**위치**: auth-server 내장 또는 별도 React 앱 +**데이터 저장**: +- 회사 정보: PostgreSQL `auth_db.companies` +- 세션 관리: JWT 토큰 +- OAuth 토큰: 파일시스템 `/tokens/` + +### 4.2 인증 흐름 + +``` +1. 사용자 → auth.ro-being.com (회사별 서브도메인) +2. Google/Slack OAuth 인증 +3. JWT 토큰 발급 +4. 게임 UI 접근 허용 +``` + +## 5. 로그 및 모니터링 아키텍처 + +### 5.1 로그 수집 전략 + +#### 51123 서버 +- **저장 위치**: `/mnt/hdd/logs/` +- **API**: frontend-base `/admin/logs/{service}` + +#### 51124 서버 로그 동기화 +```bash +# cron으로 주기적 동기화 +*/5 * * * * rsync -av admin@192.168.219.52:/var/log/robbing/ /mnt/hdd/logs/51124/ +``` + +### 5.2 Admin 페이지 모니터링 + +**frontend-base API 확장**: +- `/admin/servers/status` - 양 서버 상태 +- `/admin/logs/unified` - 통합 로그 뷰 +- `/admin/stats/dashboard` - 실시간 대시보드 + +## 6. nginx 설정 전략 + +### 6.1 통합 라우팅 설정 + +```nginx +# 정적 파일 서빙 (게임 UI) +location /game/ { + root /var/www; + try_files $uri $uri/ /game/index.html; + + # 캐싱 최적화 + location ~* \.(jpg|jpeg|png|gif|ico|css|js)$ { + expires 1y; + add_header Cache-Control "public, immutable"; + } +} + +# API 프록시 +location /api/robbing/ { + proxy_pass http://192.168.219.52:8010; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; +} + +# WebSocket 프록시 +location /ws/robbing/ { + proxy_pass http://192.168.219.52:8010; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; +} + +# 인증 서버 +location /auth/ { + proxy_pass http://localhost:9000; +} + +# 관리자 대시보드 +location /admin/ { + proxy_pass http://localhost:8000; +} +``` + +## 7. 동적 기능 보장 + +### 7.1 정적 서빙 시에도 모든 동적 기능 작동 + +React 앱이 브라우저에서 실행되면: + +| 기능 | 구현 방식 | 통신 방법 | +|------|-----------|-----------| +| 실시간 대화 | WebSocket | `/ws/robbing/chat` | +| GUI 작업 표시 | API 폴링 | `/api/robbing/screenshot` | +| 스탯 업데이트 | WebSocket + API | `/ws/robbing/stats` | +| 컨테이너 재시작 대응 | 자동 재연결 | Exponential backoff | +| 레벨업 애니메이션 | WebSocket 이벤트 | Custom events | + +### 7.2 React 앱 예시 코드 + +```javascript +// 동적 통신 구현 +const RobingGame = () => { + useEffect(() => { + // WebSocket 연결 + const ws = new WebSocket('wss://ro-being.com/ws/robbing/realtime'); + + // 실시간 상태 업데이트 + ws.onmessage = (event) => { + const data = JSON.parse(event.data); + if (data.type === 'STAT_UPDATE') { + updateStats(data.stats); + } else if (data.type === 'LEVEL_UP') { + showLevelUpAnimation(); + } + }; + + // API 통신 + const fetchStats = async () => { + const response = await fetch('/api/robbing/stats/user123'); + const stats = await response.json(); + setUserStats(stats); + }; + + // 초기 로드 및 주기적 갱신 + fetchStats(); + const interval = setInterval(fetchStats, 5000); + + return () => { + ws.close(); + clearInterval(interval); + }; + }, []); +}; +``` + +## 8. 구현 로드맵 + +### Phase 1: 기반 구축 (1주차) +1. PostgreSQL에 `robbing_db` 스키마 생성 +2. State Service 개발 및 51124 배포 +3. nginx 라우팅 설정 업데이트 + +### Phase 2: 프론트엔드 전환 (2-3주차) +1. frontend-customer 게임형 UI 개발 +2. WebSocket 실시간 통신 구현 +3. nginx 정적 서빙 설정 + +### Phase 3: 통합 및 최적화 (4주차) +1. 로그 동기화 스크립트 구축 +2. Admin 페이지 통합 모니터링 +3. 성능 최적화 및 캐싱 설정 + +## 9. 결론 + +이 아키텍처는 다음을 달성합니다: + +- **명확한 역할 분리**: 51123(프론트엔드+데이터), 51124(백엔드 로직) +- **최적 성능**: nginx 정적 서빙으로 게임 리소스 최적화 +- **확장성**: 각 컴포넌트가 독립적으로 스케일 가능 +- **유지보수성**: 일관된 패턴과 명확한 책임 분리 + +정적 서빙 방식은 성능상 이점만 있고, 모든 동적 기능은 API/WebSocket을 통해 완벽하게 작동합니다. + +--- +**최종 검토**: 2025-07-29 \ No newline at end of file