# Architecture

> Variet Agent — Gemini CLI 기반 AI Agent Team 시스템

## 프로젝트 개요

사용자가 디스코드에서 자연어 명령 → AI Agent Team이 코드 분석/분해/실행 → Gitea CI로 PR/빌드/배포.
Gemini CLI를 서브프로세스(`asyncio.create_subprocess_exec`)로 래핑하여 역할별 독립 컨텍스트로 호출.

## 디렉토리 구조

```
variet-agent/
├── main.py                  # 진입점 (FastAPI + Discord Bot 동시 실행)
├── config.py                # .env 기반 설정 관리
├── api/
│   ├── server.py            # FastAPI REST 서버
│   ├── discord_bot.py       # Discord Bot (NLU + PCRS 파이프라인 + 애니 핸들러)
│   └── models.py            # 요청/응답 모델
├── core/
│   ├── task_pipeline.py     # PCRS: Plan → Code → Review → Summarize
│   ├── gemini_caller.py     # Gemini CLI 래퍼 (text/agent 모드)
│   ├── context_manager.py   # 관련 파일 선별 + 토큰 예산 제어
│   ├── project_indexer.py   # 프로젝트 구조 스캔/캐시
│   ├── workspace.py         # 워크스페이스 관리 (채널 ↔ 프로젝트 매핑)
│   ├── file_applier.py      # 코드 변경 적용
│   └── docs_manager.py      # 문서/세션 기록
├── tools/                   # 자동화 도구 (애니메이션 파이프라인)
│   ├── anime_pipeline.py    # 통합 파이프라인 (검색/다운/자막/상태)
│   ├── anissia_client.py    # Anissia 편성표 API
│   ├── nyaa_client.py       # Nyaa 토렌트 검색
│   ├── qbit_client.py       # qBittorrent 제어
│   ├── nas_scanner.py       # NAS 파일 스캔
│   ├── title_matcher.py     # 제목 매칭 (로마지/퍼지)
│   └── subtitle_downloader.py  # 자막 다운로더
├── integrations/
│   ├── gitea_client.py      # Gitea API (PR/이슈)
│   ├── vikunja_client.py    # Vikunja 태스크 관리
│   └── ci_monitor.py        # CI 결과 모니터링
└── prompts/                 # AI 역할별 프롬프트
    ├── unified.md           # NLU 분류 (chat/task/anime/clarify)
    ├── planner.md           # 태스크 분해
    ├── coder.md             # 코드 구현
    ├── reviewer.md          # 코드 리뷰
    └── summarizer.md        # 총평 생성
```

## 핵심 모듈

| 모듈 | 역할 | 의존성 |
|------|------|--------|
| `discord_bot.py` | 사용자 인터페이스 + NLU 분류 | `workspace.py`, `gemini_caller.py`, `task_pipeline.py` |
| `task_pipeline.py` | PCRS 오케스트레이션 (Inner/Outer 루프) | `gemini_caller.py`, `context_manager.py`, `project_indexer.py` |
| `gemini_caller.py` | Gemini CLI 서브프로세스 호출 (text/agent) | `prompts/` |
| `context_manager.py` | 태스크 기반 파일 선별 + 토큰 예산 | `project_indexer.py` |
| `workspace.py` | 채널 ↔ 프로젝트 경로 매핑, workspaces.json 관리 | — |
| `anime_pipeline.py` | 애니 자동화 통합 | `anissia_client.py`, `nyaa_client.py`, `qbit_client.py`, `nas_scanner.py` |

## 데이터 흐름

```
Discord 메시지
  → on_message()
    → _unified_call() — NLU 분류 (chat/task/anime/clarify)
      ├─ chat → 즉답
      ├─ clarify → 질문 임베드
      ├─ anime → _handle_anime() → AnimePipeline
      └─ task → _handle_task()
            → TaskPipeline.plan() — Planner (태스크 분해)
            → TaskPipeline.code_parallel() — Coder (에이전트 모드, cwd=프로젝트)
            → TaskPipeline.planner_verify() — 내부 자가검증 (Inner Loop)
            → TaskPipeline.batch_review() — Reviewer (Outer Loop)
            → TaskPipeline.summarize() — 총평
            → Discord Embed 보고
```