Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
184 lines (144 loc) · 5.16 KB

ARCHITECTURE.md

File metadata and controls

184 lines (144 loc) · 5.16 KB

🏗️ DTUI2 아키텍처: 브라우저 & 데스크톱 통합

핵심 질문에 대한 답변

"브라우저에서 테스트 통과하게 만드는거랑 데스크톱 앱으로 동작하게 구현하는거랑 구현체가 달라지니?"

답변: 아니요! 구현체는 동일합니다.

우리의 아키텍처는 런타임 환경 감지 + 어댑터 패턴을 사용하여 하나의 코드베이스로 두 환경을 모두 지원합니다.

🔄 통합 아키텍처 구조

1. 환경 감지 로직 (Runtime Detection)

// src/services/AIProvider.ts
if (window.electronAPI) {
  // 🖥️ Electron 환경: 실제 시스템 API 사용
  const result = await window.electronAPI.executeShellCommand(command);
} else {
  // 🌐 브라우저 환경: Mock API 사용
  const result = await this.aiAgent.executeCommand(command);
}

2. 어댑터 패턴 (Adapter Pattern)

UI Components (공통)
        ↓
  AIProvider (공통)
        ↓
    환경 감지 분기
    ↙         ↘
Electron API  Mock API
(데스크톱)    (브라우저)

📋 환경별 동작 매트릭스

기능 브라우저 환경 Electron 환경
UI 컴포넌트 ✅ 동일한 코드 ✅ 동일한 코드
셸 명령 (!ls) 🔄 Mock 시뮬레이션 🔄 실제 터미널 실행
파일 읽기 🔄 Mock 파일시스템 🔄 실제 파일시스템
AI 응답 🔄 Mock AI Agent 🔄 실제 API 또는 Mock
TTY 포맷팅 ✅ 동일한 렌더링 ✅ 동일한 렌더링
UI 인디케이터 ✅ 동일한 표시 ✅ 동일한 표시

🔧 구현 세부사항

공통 레이어 (Shared Layer)

변경되지 않는 코드 - 100% 재사용

// 모든 UI 컴포넌트
- InputArea.tsx     // 명령 입력 및 모드 감지
- TerminalOutput.tsx // ANSI 색상 렌더링  
- ChatArea.tsx      // 메시지 표시
- Header.tsx        // 헤더 UI

// 공통 비즈니스 로직
- AIProvider.ts     // 명령 처리 및 환경 분기
- types.ts          // TypeScript 타입 정의

환경별 어댑터 (Environment Adapters)

환경에 따라 자동 선택되는 구현체

// Electron 환경 (실제 시스템)
electron/main.js    // 실제 파일/터미널 작업
electron/preload.js // IPC 브릿지

// 브라우저 환경 (시뮬레이션)  
MockElectronAPI.ts  // 파일/터미널 시뮬레이션
MockAIAgent.ts      // AI 기능 시뮬레이션

🎯 핵심 이점

1. 단일 코드베이스

  • 하나의 React 앱으로 두 환경 모두 지원
  • UI 로직 중복 없음
  • 유지보수 비용 최소화

2. 점진적 개발

  • 브라우저에서 빠른 개발/테스트
  • Electron으로 실제 시스템 통합
  • 기능별 단계적 이행 가능

3. 개발자 경험

# 빠른 개발 (브라우저)
npm run dev         # 즉시 테스트 가능

# 실제 환경 (데스크톱)
npm run electron:dev # 시스템 통합 테스트

🔄 환경 전환 예시

셸 명령 실행

// 브라우저: Mock 터미널 출력
!ls → 🎨 색상화된 가짜 파일 목록

// Electron: 실제 터미널 출력  
!ls → 🎨 색상화된 실제 파일 목록

파일 읽기

// 브라우저: Mock 파일 내용
read file package.json → Mock JSON 데이터

// Electron: 실제 파일 내용
read file package.json → 실제 package.json 내용

🚀 배포 전략

개발 단계

  1. 브라우저 개발: npm run dev

    • 빠른 UI/UX 반복
    • Mock 데이터로 기능 검증
    • 크로스 브라우저 테스트

  2. Electron 통합: npm run electron:dev

    • 실제 시스템 API 연동
    • 파일/터미널 실제 동작 확인
    • 데스크톱 UI 최적화

배포

# 웹 버전 배포
npm run build → 정적 웹사이트

# 데스크톱 앱 배포  
npm run dist → .exe, .dmg, .AppImage

🛡️ 안전성 보장

환경 감지 안전성

// 안전한 환경 감지
if (typeof window !== 'undefined' && window.electronAPI) {
  // Electron 환경에서만 실행
} else {
  // 브라우저 환경 폴백
}

에러 핸들링

try {
  // 환경에 맞는 API 호출
  const result = await environmentAPI.execute();
} catch (error) {
  // 공통 에러 처리
  return fallbackResponse(error);
}

📊 성능 비교

측면 브라우저 Electron
시작 속도 ⚡ 즉시 🐌 앱 로딩
메모리 사용 💚 낮음 🟡 높음
시스템 접근 ❌ 제한적 ✅ 완전
배포 크기 💚 작음 🟡 큼
업데이트 ⚡ 즉시 🔄 재설치 필요

🎉 결론

하나의 구현체로 두 환경을 모두 지원합니다!

  • ✅ 공통 UI: 모든 컴포넌트 재사용
  • ✅ 공통 로직: 비즈니스 로직 재사용
  • ✅ 환경 어댑터: 런타임 자동 선택
  • ✅ 점진적 개발: 브라우저 → 데스크톱 단계별 개발
  • ✅ 유지보수: 단일 코드베이스 관리

이 아키텍처로 개발 속도는 최대화하고 코드 중복은 최소화할 수 있습니다! 🚀