# Telegram Web Client Design

## Overview

웹소켓을 이용해 Telegram 봇(telegram-bot-workers)과 대화하는 웹 앱

## Stack

- **Infrastructure**: Incus 컨테이너 (Debian 13) on jp1/kr1
- **Backend**: Python + Telethon v2 + FastAPI WebSocket
- **Frontend**: React + TypeScript + Vite
- **State Management**: Zustand

## Architecture

```
┌─────────────────┐     WebSocket      ┌─────────────────────────────┐
│  React Frontend │◄──────────────────►│  FastAPI Backend (Debian)   │
│  (브라우저)      │                    │                             │
└─────────────────┘                    │  ┌─────────────────────┐    │
                                       │  │ Telethon v2 Client  │    │
                                       │  │ (MTProto)           │    │
                                       │  └──────────┬──────────┘    │
                                       └─────────────┼───────────────┘
                                                     │
                                                     ▼
                                       ┌─────────────────────────────┐
                                       │  Telegram API (MTProto)     │
                                       │  ↔ telegram-bot-workers 봇  │
                                       └─────────────────────────────┘
```

## Backend Structure

```
backend/
├── main.py              # FastAPI 앱 진입점
├── config.py            # 설정 (API_ID, API_HASH, BOT_USERNAME)
├── auth/
│   ├── telegram_auth.py # Telethon 인증 로직
│   └── session_manager.py # 세션 저장/복원
├── websocket/
│   ├── handler.py       # WebSocket 연결 관리
│   └── events.py        # 메시지 송수신 이벤트
├── telegram/
│   ├── client.py        # Telethon 클라이언트 래퍼
│   └── bot_chat.py      # 봇과의 대화 전용 로직
└── models/
    └── schemas.py       # Pydantic 모델
```

## Frontend Structure

```
frontend/
├── src/
│   ├── App.tsx
│   ├── main.tsx
│   ├── components/
│   │   ├── Auth/
│   │   │   ├── PhoneInput.tsx    # 전화번호 입력
│   │   │   └── CodeInput.tsx     # 인증 코드 입력
│   │   └── Chat/
│   │       ├── ChatContainer.tsx # 채팅 메인
│   │       ├── MessageList.tsx   # 메시지 목록
│   │       └── MessageInput.tsx  # 메시지 입력
│   ├── hooks/
│   │   └── useWebSocket.ts       # WebSocket 연결 훅
│   ├── stores/
│   │   └── chatStore.ts          # Zustand 상태 관리
│   └── types/
│       └── index.ts
├── package.json
└── vite.config.ts
```

## Features

- **Authentication**: Telegram 로그인 (전화번호 + 인증 코드)
- **Session Management**: 로그인 후 세션 파일 저장, 재접속 시 자동 복원
- **Real-time Chat**: WebSocket으로 실시간 메시지 송수신
- **Bot Filter**: 특정 봇(telegram-bot-workers)과의 대화만 처리

## User Flow

1. 사용자가 웹에서 전화번호 입력
2. 백엔드가 Telethon으로 Telegram에 인증 코드 요청
3. 사용자가 코드 입력 → 세션 생성
4. WebSocket 연결 유지, 봇과 실시간 대화

## Configuration

환경 변수:
- `TELEGRAM_API_ID`: Telegram API ID
- `TELEGRAM_API_HASH`: Telegram API Hash
- `BOT_USERNAME`: 대화할 봇 username (예: @telegram_summary_bot)

## Deployment

- Incus 컨테이너: Debian 13
- systemd 서비스로 백엔드 실행
- Caddy/Nginx로 리버스 프록시 + SSL