# 전체 아키텍처 개요

## 1. 목적

Helm Chart 신규 버전을 카탈로그에 자동으로 추가하고, 해당 버전으로 배포/업그레이드 시 참고할 주의사항을 문서화한다.

> **카탈로그 역할**: 신규 배포를 위한 Helm 차트 버전 보관소. 운영 클러스터 직접 변경과 무관.

자동화 항목:
- 신규 버전 차트 pull 및 카탈로그 디렉토리 추가
- Structured Diff JSON 기반 변경 분석
- `custom-values.yaml` 수정 필요 여부(Breaking) 판단
- 업그레이드 주의사항 문서 자동 생성 (`CUSTOM-README.md`에 추가)
- Git PR 자동 생성

---

## 2. 설계 원칙

| # | 원칙 |
|---|------|
| 1 | LLM은 Helm CLI를 직접 구성하거나 실행하지 않는다. helm 실행은 결정론적 Skill이 전담하며, Agent/LLM은 Skill을 언제 호출할지만 결정한다 |
| 2 | Diff 생성은 100% deterministic 해야 한다 |
| 3 | LLM 입력은 반드시 Structured JSON 형식이다 |
| 4 | Breaking Change 판단은 코드 기반 Rule Engine이 먼저 수행한다 |
| 5 | LLM은 설명 및 Markdown 생성만 담당한다 |
| 6 | 각 컴포넌트는 Agent Skill로 노출한다 (Agent가 직접 호출) |
| 7 | 카탈로그 업데이트는 Git PR로 관리한다 (운영 환경 직접 변경 아님) |
| 8 | 외부 입력(PR comment, webhook 등)은 신뢰 경계 밖으로 취급하며, 프롬프트 주입 방어를 기본 전제로 한다 |

## 2.1 운영 기준 (Non-Functional)

- **성능**: Diff 생성 + 요약 전체 파이프라인 5분 내 완료를 목표로 한다 (대형 차트는 예외).
- **신뢰성**: 실패 시 재시도 3회, 재시도 후 실패는 알림 전송 + 중단.
- **검토 정책**: `breaking=true` PR에는 `needs-review` 레이블을 부착한다. 담당자가 `custom-values.yaml` 수정 후 merge 여부를 판단한다. (`breaking=false` PR은 자동 merge 가능)

---

## 3. 전체 시스템 아키텍처

### Step 1: Skills (에이전트 내부에서 호출되는 개별 기능)

```
[Chart Version Detector]
      │  chart명, current/new version
      ▼
[chart_updater Skill]
      │  helm pull → manifests/helm/<chart>/<to_version>/ 생성
      │  CUSTOM-README.md carry-over from previous version
      ▼
[helm_diff Skill]
      │  values/template/CRD 비교
      ▼
[Structured Diff JSON]
      │  { values, templates, crd, dependencies }
      ▼
[breaking_change_check Skill]
      │  custom-values.yaml 기준 판단 (LLM 없음)
      │  breaking=true: custom-values.yaml 수정 필요
      │  breaking=false: 수정 불필요 (주의사항만)
      ▼
[generate_upgrade_doc Skill]   ← 항상 실행
      │  breaking=true  → LLM 상세 가이드 (custom-values.yaml 수정 방법 포함)
      │  breaking=false → 템플릿 기반 간단 요약
      ▼
[update_docs_file Skill]
      │  CUSTOM-README.md에 업그레이드 주의사항 섹션 추가
      ▼
[create_pr Skill]
      │  branch 생성 → PR 생성 (항상)
      │  breaking=true  → label: needs-review
      │  breaking=false → label: auto-update
```

> 각 Skill은 독립적으로 호출 가능. 호출 순서는 Agent(Step 2~3)가 담당.

> `deploy_validate` Skill은 Phase 2에서 구현 예정 (현재 스코프 밖).

### Step 2~3: On-Cluster AI Agent

```
[OpenClaw / Nanobot on K8s]
      │
      ├── Skill: chart_version_detector → 신규 버전 감지
      ├── Skill: chart_updater          → 신규 버전 차트 pull
      ├── Skill: helm_diff              → Structured Diff JSON 생성
      ├── Skill: breaking_check         → custom-values.yaml 수정 필요 여부 판단
      ├── Skill: generate_doc           → 업그레이드 주의사항 문서 생성 (항상)
      ├── Skill: update_docs            → CUSTOM-README.md 업데이트
      ├── Skill: create_pr              → GitHub PR 생성
      └── Channel: Discord              → 알림 발송 (추후 Slack으로 변경 가능)

트리거: Cron 스케줄 또는 K8s 이벤트
```

---

## 4. 컴포넌트 책임 분리

| 컴포넌트 | 역할 | 결정성 | LLM 사용 |
|---------|------|--------|---------|
| Chart Version Detector | 신규 버전 감지 | ✅ | ❌ |
| Chart Updater | 신규 버전 차트 pull → 버전 디렉토리 생성 | ✅ | ❌ |
| Helm Diff Engine | Structured Diff JSON 생성 | ✅ | ❌ |
| Breaking Change Rule Engine | custom-values.yaml 수정 필요 여부 판단 | ✅ | ❌ |
| LLM Summarizer | 업그레이드 주의사항 문서 생성 | ❌ | ✅ (breaking=true 시만) |
| Docs Updater | CUSTOM-README.md 업그레이드 주의사항 섹션 추가 | ✅ | ❌ |
| Git PR Bot | branch / commit / PR 생성 | ✅ | ❌ |

---

## 5. 기술 스택

| 영역 | 선택 | 비고 |
|------|------|------|
| Helm CLI | helm 3.x | pull, template, diff |
| 버전 감지 | ArtifactHub API / GitHub Release Webhook | |
| Diff 처리 | Python (deepdiff 또는 직접 구현) | |
| Rule Engine | Python | 코드 기반, custom-values.yaml 기준 |
| LLM | Claude (Anthropic) | via Skill or API, breaking=true 시만 호출 |
| 문서 저장 | `manifests/helm/<chart>/<version>/CUSTOM-README.md` | 업그레이드 주의사항 섹션 추가 |
| PR 생성 | GitHub API (PyGithub / gh CLI) | |
| 스케줄링 | Agent 내장 스케줄러 (Cron) | Step 2~3 |
| On-Cluster Agent | OpenClaw / Nanobot | Step 2~3 |
| Skill Contract | JSON 스키마 (Skill I/O) | Step 1 계약 (Agent-Skill 인터페이스) |

---

## 6. 데이터 흐름 요약

```
입력:  chart명 + current_version + new_version (레포 내 디렉토리 기준)
중간:  Structured Diff JSON (values/templates/crd/breaking) + CUSTOM-README.md (docs_context)
출력:  CUSTOM-README.md 업그레이드 주의사항 섹션 + GitHub PR
```

---

## 7. 관련 설계 문서

- [01-helm-diff-engine.md](01-helm-diff-engine.md) — Diff Engine 상세 설계
- [02-breaking-change-rules.md](02-breaking-change-rules.md) — Rule Engine 판단 로직
- [03-llm-summarizer.md](03-llm-summarizer.md) — LLM Summarizer + Docs Updater
- [04-skill-interface.md](04-skill-interface.md) — Skill 인터페이스 정의
- [05-on-cluster-agent.md](05-on-cluster-agent.md) — On-Cluster Agent 설계 (Step 2~3)