DOCS/docs/architecture/frontend-architecture-strategy.md

# 프론트엔드 아키텍처 전략

**날짜**: 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