# 프로젝트 기술 스택 (Project Stack)

이 프로젝트의 기본 기술 스택과 구조입니다.

## Frontend (news-engine-admin)

### 기술 스택
- **Framework**: Next.js 16.x (App Router)
- **Language**: TypeScript 5.x
- **React**: 19.x
- **Styling**: Tailwind CSS 4.x
- **UI Components**: Radix UI + shadcn/ui
- **Form**: react-hook-form + zod
- **Icons**: lucide-react
- **Theme**: next-themes (다크모드 지원)

### 디렉토리 구조
```
src/
├── app/                    # Next.js App Router 페이지
│   ├── layout.tsx          # 루트 레이아웃
│   ├── page.tsx            # 메인 페이지
│   └── dashboard/          # 대시보드 페이지들
├── components/             # React 컴포넌트
│   ├── ui/                 # shadcn/ui 기본 컴포넌트
│   ├── dashboard/          # 대시보드 전용 컴포넌트
│   └── providers/          # Context Provider
├── hooks/                  # 커스텀 훅
├── lib/                    # 유틸리티 함수
│   └── utils.ts            # cn() 등 공통 유틸
└── types/                  # TypeScript 타입 정의
```

### 설치 명령어
```bash
# 프로젝트 생성
npx create-next-app@latest --typescript --tailwind --app

# shadcn/ui 초기화
npx shadcn@latest init

# 컴포넌트 추가
npx shadcn@latest add button card dialog tabs
```

## Backend (FastAPI 마이크로서비스)

### 기술 스택
- **Framework**: FastAPI
- **Language**: Python 3.11
- **Database**: MongoDB (motor - async driver)
- **Queue**: Redis (aioredis)
- **Validation**: Pydantic v2
- **HTTP Client**: aiohttp

### 마이크로서비스 구조
```
service/
├── Dockerfile
├── requirements.txt
├── worker.py              # 메인 워커 (큐 처리)
├── *_service.py           # 비즈니스 로직
└── *_client.py            # 외부 서비스 클라이언트
```

### API 서비스 구조
```
service/
├── Dockerfile
├── requirements.txt
└── app/
    ├── __init__.py
    ├── main.py            # FastAPI 앱 엔트리포인트
    ├── database.py        # DB 연결 관리
    ├── models/            # Pydantic 모델
    └── routers/           # API 라우터
```

## 공통 라이브러리 (news-commons)

### 제공 기능
- `QueueManager`: Redis 큐 관리 (enqueue, dequeue, heartbeat)
- `PipelineJob`: 파이프라인 작업 데이터 모델
- `PersonEntity`, `OrganizationEntity`: 엔티티 모델
- 로깅, 설정 유틸리티

### 사용 예시
```python
from news_commons import PipelineJob, QueueManager

queue_manager = QueueManager(redis_url="redis://redis:6379")
await queue_manager.connect()

job = await queue_manager.dequeue('wikipedia_enrichment', timeout=5)
```

## 인프라

### 컨테이너
- **MongoDB**: 7.0
- **Redis**: 7-alpine
- **Docker Compose**: 서비스 오케스트레이션

### 외부 서비스
- **Gitea**: 코드 저장소 (http://gitea.yakenator.io/)
- **OpenAI API**: GPT 모델 사용
- **Claude API**: Claude 모델 사용

## 참고 리포지토리

| 서비스 | 설명 | URL |
|--------|------|-----|
| news-commons | 공통 라이브러리 | gitea.yakenator.io/sapiens/news-commons |
| news-article-generator | 기사 생성 | gitea.yakenator.io/sapiens/news-article-generator |
| news-wikipedia-enrichment | 위키피디아 보강 | gitea.yakenator.io/sapiens/news-wikipedia-enrichment |
| news-image-generator | 이미지 생성 | gitea.yakenator.io/sapiens/news-image-generator |
| mcp_biocode | 바이오코드 API | gitea.yakenator.io/sapiens/mcp_biocode |