기술스택 | Notion

# CTRL_F Frontend 기술 스택

## 최종 산출물 - 기술 스택 명세서

> 본 문서는 package.json, tsconfig.json, vite.config.ts, Dockerfile 등 실제 설정 파일을 기반으로 작성되었습니다.

---

## 1. Core Framework

| 기술 | 버전 | 용도 |
|------|------|------|
| **React** | 19.2.0 | UI 라이브러리 |
| **React DOM** | 19.2.0 | React DOM 렌더링 |
| **TypeScript** | 5.9.3 | 정적 타입 언어 |

---

## 2. 빌드 및 번들링

| 기술 | 버전 | 용도 |
|------|------|------|
| **Vite** | 7.2.2 | 빌드 도구 및 개발 서버 |
| **@vitejs/plugin-react** | 5.1.0 | Vite React 플러그인 |

### Vite 설정
- 개발 서버 포트: `5173`
- HMR (Hot Module Replacement) 지원
- 프록시 설정을 통한 백엔드 서비스 연동

---

## 3. 라우팅

| 기술 | 버전 | 용도 |
|------|------|------|
| **React Router DOM** | 7.9.6 | SPA 클라이언트 사이드 라우팅 |

---

## 4. 인증 및 보안

| 기술 | 버전 | 용도 |
|------|------|------|
| **Keycloak JS** | 26.2.1 | OAuth2/OpenID Connect 인증 |

### Keycloak 설정
- Realm: `ctrlf`
- Client ID: `web-app`
- 프로토콜: OAuth2 / OIDC

---

## 5. UI 컴포넌트

| 기술 | 버전 | 용도 |
|------|------|------|
| **Lucide React** | 0.553.0 | 아이콘 라이브러리 |
| **CSS (자체 구현)** | - | 컴포넌트 스타일링 |

---

## 6. 코드 품질 도구

| 기술 | 버전 | 용도 |
|------|------|------|
| **ESLint** | 9.39.1 | JavaScript/TypeScript 린팅 |
| **@eslint/js** | 9.39.1 | ESLint 기본 설정 |
| **typescript-eslint** | 8.46.3 | TypeScript ESLint 파서 및 플러그인 |
| **eslint-plugin-react-hooks** | 7.0.1 | React Hooks 린팅 규칙 |
| **eslint-plugin-react-refresh** | 0.4.24 | React Refresh 린팅 규칙 |

---

## 7. 타입 정의

| 기술 | 버전 | 용도 |
|------|------|------|
| **@types/react** | 19.2.2 | React 타입 정의 |
| **@types/react-dom** | 19.2.2 | React DOM 타입 정의 |
| **@types/node** | 24.10.0 | Node.js 타입 정의 |

---

## 8. TypeScript 컴파일러 설정

| 설정 | 값 | 설명 |
|------|-----|------|
| **target** | ES2022 | 컴파일 대상 ECMAScript 버전 |
| **module** | ESNext | 모듈 시스템 |
| **jsx** | react-jsx | JSX 변환 방식 (React 17+ 자동 런타임) |
| **moduleResolution** | bundler | 모듈 해석 방식 |
| **strict** | true | 엄격한 타입 검사 활성화 |
| **lib** | ES2022, DOM, DOM.Iterable | 포함할 라이브러리 정의 |

---

## 9. 런타임 환경

| 항목 | 버전 | 비고 |
|------|------|------|
| **Node.js** | 22.19.0 | 개발 및 빌드 환경 |
| **npm** | 10.0.0 이상 | 패키지 관리자 |

---

## 10. 배포 인프라

### 컨테이너화
| 기술 | 버전/이미지 | 용도 |
|------|------------|------|
| **Docker** | - | 컨테이너 런타임 |
| **Nginx** | stable-alpine | 웹 서버 및 리버스 프록시 |

### 컨테이너 오케스트레이션
| 기술 | 설정 | 용도 |
|------|------|------|
| **Kubernetes** | Deployment | 컨테이너 오케스트레이션 |
| **ArgoCD** | namespace: argocd | GitOps 기반 CD |
| **AWS ECR** | ap-northeast-2 | 컨테이너 이미지 레지스트리 |

### Nginx 설정
- 포트: 80
- SPA 라우팅 지원: `try_files $uri $uri/ /index.html`
- API 프록시: `/api/` → 백엔드 서비스

---

## 11. 백엔드 서비스 연동 (개발 환경 프록시)

| 프록시 경로 | 대상 서비스 | 포트 |
|------------|------------|------|
| `/api-edu/*` | Education Service | 9002 |
| `/api-infra/*` | Infrastructure Service | 9003 |
| `/api/chat/*`, `/chat/*` | Chat Service | 9005 |
| `/api/faq/*`, `/faq/*` | FAQ Service (Chat Service) | 9005 |

---

## 12. 프로젝트 스크립트

| 명령어 | 실행 내용 |
|--------|----------|
| `npm run dev` | Vite 개발 서버 실행 |
| `npm run build` | TypeScript 컴파일 + Vite 프로덕션 빌드 |
| `npm run lint` | ESLint 코드 검사 |
| `npm run preview` | 프로덕션 빌드 미리보기 |

---

## 13. 기술 스택 요약 다이어그램

┌─────────────────────────────────────────────────────────────┐ │ CTRL_F Frontend │ ├─────────────────────────────────────────────────────────────┤ │ UI Layer │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ React 19.2 │ │ TypeScript │ │ Lucide React│ │ │ │ │ │ 5.9.3 │ │ 0.553.0 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Routing & Auth │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ React Router 7.9.6 │ │ Keycloak JS 26.2.1 │ │ │ │ (Client-side) │ │ (OAuth2/OIDC) │ │ │ └─────────────────────┘ └─────────────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Build & Dev Tools │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Vite 7.2.2 │ │ ESLint 9.39 │ │ Node 22.19 │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────────┤ │ Deployment │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Docker │ │ Kubernetes │ │ AWS ECR │ │ │ │ Nginx Alpine│ │ ArgoCD │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Backend Services │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Education │ │ Infrastructure│ │ Chat │ │ │ │ Service │ │ Service │ │ Service │ │ │ │ (9002) │ │ (9003) │ │ (9005) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────┘


---

## 14. 의존성 전체 목록

### Production Dependencies
```json
{
  "react": "^19.2.0",
  "react-dom": "^19.2.0",
  "react-router-dom": "^7.9.6",
  "keycloak-js": "^26.2.1",
  "lucide-react": "^0.553.0"
}

Development Dependencies

{
  "@eslint/js": "^9.39.1",
  "@types/node": "^24.10.0",
  "@types/react": "^19.2.2",
  "@types/react-dom": "^19.2.2",
  "@vitejs/plugin-react": "^5.1.0",
  "eslint": "^9.39.1",
  "eslint-plugin-react-hooks": "^7.0.1",
  "eslint-plugin-react-refresh": "^0.4.24",
  "globals": "^16.5.0",
  "typescript": "~5.9.3",
  "typescript-eslint": "^8.46.3",
  "vite": "^7.2.2"
}

15. 특이사항

외부 라이브러리 최소화

상태 관리: 외부 라이브러리 없이 React 내장 기능(useState, useReducer, useSyncExternalStore 패턴) 사용
HTTP 통신: 외부 라이브러리 없이 Fetch API 직접 사용
스타일링: CSS 프레임워크 없이 순수 CSS 사용
마크다운 렌더링: 외부 라이브러리 없이 자체 구현

Development Dependencies

15. 특이사항

외부 라이브러리 최소화

최신 기술 스택 적용