레거시 개발자의 첫번쩨 바이브코딩 체험기(디지털노마드 2탄)

제품 구조에 대한 아키텍쳐 및 구성요소에 대해서 상세히 설명해줘.

itda-claude-web 아키텍처 개요
📐 전체 구조도

┌─────────────────────────────────────────────────────────────────┐
│                         itda-claude-web                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────────┐        ┌─────────────────┐                 │
│  │   Next.js App   │ ←────→ │  Socket.IO      │                 │
│  │   (Port 9998)   │        │  Server         │                 │
│  │                 │        │                 │                 │
│  │  • Terminal UI  │        │  • Session Mgr  │                 │
│  │  • xterm.js     │        │  • PTY Process  │                 │
│  │  • React 19     │        │  • Auth/JWT     │                 │
│  └─────────────────┘        └─────────────────┘                 │
│         │                           │                            │
│         │        WebSocket          │                            │
│         └───────────────────────────┘                            │
│                          │                                       │
│                          ▼                                       │
│                  ┌─────────────────┐                             │
│                  │  node-pty       │                             │
│                  │  (Shell Proc)   │                             │
│                  └─────────────────┘                             │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘
🏗️ 핵심 아키텍처 패턴
1. 단일 포트 통합 아키텍처
Socket.IO 서버와 Next.js가 하나의 포트(9998)에서 함께 운영
Cloudflare 터널링을 위한 유연한 호스트 구성
2. 클라이언트-서버 분리
서버: 세션 상태 관리 (SSOT - Single Source of Truth)
클라이언트: 상태 표시 및 사용자 입력만 담당
3. 세션 지속화 패턴

서버 재시작
    ↓
.sessions-state.json 복구 → 메타데이터만 복원
    ↓
PTY 자동 재생성 → join_session 시
    ↓
버퍼 내용 유지 → 사용자 경험 연속성

🔌 통신 플로우
WebSocket 이벤트 흐름
방향	이벤트	설명
C→S	connect	JWT 인증
C→S	create_session	새 터미널 생성
C→S	join_session	기존 세션 참가
C→S	input	키보드 입력 전송
C→S	resize	터미널 크기 조정
C→S	heartbeat	연결 유지 (30초)
S→C	session_list	활성 세션 목록
S→C	output	터미널 출력
S→C	status_change	세션 상태 변경
🗂️ 주요 파일별 역할
서버 사이드
파일	역할	핵심 기능
server/index.js	진입점	Socket.IO + Next.js 통합
server/session-manager.js	세션 관리	PTY 생성, 버퍼링, 상태 저장
server/socket-handler.js	이벤트 핸들러	WebSocket 이벤트 처리, 인증
server/lib/auth.js	인증	JWT 생성/검증
server/lib/security.js	보안	입력 검증, 속도 제한
클라이언트 사이드
파일	역할	핵심 기능
src/app/terminal/page.tsx	메인 페이지	Ocean Depth UI, 세션 탭
src/components/terminal/Terminal.tsx	터미널	xterm.js 래퍼
src/hooks/useSession.ts	세션 훅	WebSocket 연결 관리
src/hooks/useAuth.ts	인증 훅	로그인/로그아웃 상태
src/lib/terminal-formatter/	포매터	ANSI 코드 처리
🔐 보안 아키텍처

┌──────────────────────────────────────────────────────────┐
│                    Security Layers                       │
├──────────────────────────────────────────────────────────┤
│  1. JWT 인증         → 토큰 기반 세션 접근 제어          │
│  2. 속도 제한         → DDoS/스팸 방지                    │
│  3. 입력 검증         → SQL 인젝션/명령어 인젝션 방지      │
│  4. 작업 디렉토리 검사 → 경로 순회 공격 방지               │
│  5. 세션 수 제한      → 리소스 과다 사용 방지 (최대 5개)   │
│  6. 유휴 세션 정리    → 30분 무활동 시 자동 삭제          │
└──────────────────────────────────────────────────────────┘
🎨 UI 아키텍처

Ocean Depth Theme
    │
    ├── Glassmorphism 패턴
    │   └── 반투명 배경, blur 효과
    │
    ├── xterm.js 터미널
    │   └── WebGL 렌더링 (성능 최적화)
    │
    ├── 분할 터미널
    │   ├── SplitPane (개별 창)
    │   └── SplitControls (제어)
    │
    └── 세션 탭 관리
        └── 다중 세션 전환
📦 기술 스택
계층	기술
프론트엔드	Next.js 15, React 19, Tailwind CSS, xterm.js
백엔드	Node.js, Socket.IO, node-pty
인증	JWT, bcrypt
언어	TypeScript
테스트	Playwright (E2E)
🔄 세션 라이프사이클

생성 → 활성 → 유휴(30분) → 만료(24시간) → 삭제
  │                              │
  │    ←─── 자동 재생성 ────     │
  │      (PTY 재시작 시)          │
  ↓                              ↓
버퍼 유지                      .sessions-state.json
🚀 주요 설계 원칙
SSOT (Single Source of Truth): 서버가 모든 세션 상태 보유
멱등성: 세션 복구 시 일관된 상태 보장
비동기优先: 이벤트 기반 비동기 통신
보안 기본: 모든 입력 검증, 인증 필수
UX 연속성: 서버 재시작에도 버퍼 유지