docs: 프론트엔드 아키텍처 전략 문서 추가
- 게임형 UI의 nginx 정적 서빙 전략 - 51123/51124 서버 역할 분리 명확화 - State Service 및 데이터베이스 아키텍처 설계 - 인증, 로그, 모니터링 통합 전략 - 동적 기능 구현 방법 및 예시 코드
This commit is contained in:
parent
acee934ab5
commit
ce2c2c9ee9
279
docs/architecture/frontend-architecture-strategy.md
Normal file
279
docs/architecture/frontend-architecture-strategy.md
Normal file
@ -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
|
||||
Loading…
x
Reference in New Issue
Block a user