# [Specification] GUARDiA 시스템 아키텍처 명세

## 1. 프로젝트 개요

### 1.1. 구축 배경
- 1,000개 이상의 관공서 SM 사이트, 10,000+ 운영 환경 관리
- 레거시 서버: 에이전트 설치 불가, 수동 FTP/SSH 반복 작업 만연
- 목표: 메신저 자연어 명령 → AI → 에이전트리스 자동 배포·운영

### 1.2. 핵심 가치
- **ChatOps**: 메신저가 유일한 터미널
- **Agentless**: SSH/FTP 표준 프로토콜만 사용
- **Human-in-the-loop**: PM 최종 승인 후 실행

---

## 2. 전체 아키텍처 (3-Layer)

```
┌─────────────────────────────────────────────────────────┐
│  INTAKE LAYER  (현장 접수)                              │
│  메신저 앱/웹 → Webhook → 입력 검증 모듈               │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  CONTROL LAYER  (지능형 제어)                           │
│  ① SR/Ops 작업 관리 엔진  (상태: RECEIVED→COMPLETED)   │
│  ② RBAC 보안 승인 엔진    (담당자→대리→상위 에스컬레이션)│
│  ③ sLLM Parser            (자연어→JSON 정형화)          │
│  ④ Claude Code 에이전트   (코드수정·스크립트 생성)      │
│  ⑤ HITL 모듈             (PM 최종 검증 대기)            │
└───────────────────────┬─────────────────────────────────┘
                        │
┌───────────────────────▼─────────────────────────────────┐
│  EXECUTION LAYER  (에이전트리스 실행)                   │
│  SSH Executor / SFTP Client → 대상 서버(1,000+)         │
│  Command Sanitizer → Audit Logger (Hash Chain)          │
└─────────────────────────────────────────────────────────┘
```

---

## 3. 기술 스택

| 구분 | 기술 | 버전/비고 |
|------|------|-----------|
| Backend | Python / FastAPI | 3.11+ |
| LLM | Llama-3-8B 또는 Solar-10.7B | 온프레미스, 4-bit 양자화 |
| Infra 제어 | paramiko (SSH/SFTP) | 에이전트리스 |
| DB | PostgreSQL | CMDB + SR + Audit |
| 메신저 연동 | Webhook (REST) | 슬랙/잔디/자체앱 |
| 보안 | AES-256 (자격증명), SHA-256 (감사로그 해시체인) | |

---

## 4. 사용자 역할별 지원 기능

### 4.1. Developer (배포)
- 로컬 빌드 파일(class, html, js, img) 메신저 첨부 → 자동 배포
- 정적 파일: 카피 즉시 반영 (WAS 재기동 불필요)
- 동적 파일(class): 무중단 롤링 재기동 (WAS #1 → 헬스체크 → WAS #2)

### 4.2. SM 운영자
- 원격 로그 분석: 에러 키워드 grep, 타임라인 추출
- 인프라 점검: 디스크/CPU/메모리/포트 임계치 감시
- 자원 정비: 로그 로테이션, 오래된 아카이브 삭제
- SSL 인증서 만료일 사전 감지

### 4.3. PM 관리자
- SR 진척도 및 배포 이력 타임라인 조회
- 민감 시스템 배포 시 2차 승인 워크플로우 제어
- 배포 결과 HITL 최종 확인 후 고객 완료 통보

---

## 5. 핵심 보안 정책

| 정책 | 내용 |
|------|------|
| 자격증명 저장 | AES-256 암호화 DB 저장, 실행 시 메모리 로드 |
| SSH 접근 | 관제 전용 계정(opsagent) + sudoers 화이트리스트 |
| 명령어 필터 | Blacklist: `rm -rf /`, `mkfs`, `drop`, `truncate` |
| 감사 로그 | SHA-256 해시 체이닝 — 위변조 즉시 탐지 |
| Kill-Switch | 메신저 '정지' 명령 → 즉시 중단 + 롤백 |
| 폐쇄망 | 외부 API 호출 금지, sLLM 온프레미스만 허용 |

---

## 6. 개발 로드맵

| Phase | 내용 | 목표 |
|-------|------|------|
| P1 | 메신저 웹훅 + DB 티켓팅 시스템 | SR 접수 → DB 저장 |
| P2 | sLLM 파서 + 승인 워크플로우 | 자연어 → JSON → HITL |
| P3 | SSH/SFTP 배포 엔진 + 롤링 재기동 | 에이전트리스 실행 |
| P4 | End-to-End 자동화 루프 완성 | SR→배포→알림 전 과정 |