DOCS/_archive/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 중앙집중식 데이터 관리

-- 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

# 주요 엔드포인트
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 서버 로그 동기화

# 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 통합 라우팅 설정

# 정적 파일 서빙 (게임 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 앱 예시 코드

// 동적 통신 구현
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