아키텍처 문서: 왜 필요한가?

README는 "이 프로젝트가 뭔지" 알려준다. 아키텍처 문서는 "이 시스템이 어떻게 돌아가는지" 알려준다.

아키텍처 문서가 필요한 순간
━━━━━━━━━━━━━━━━━━━━━━━━
"이 에러가 어디서 발생한 거야?"     → 컴포넌트 의존 관계
"이 데이터가 어디서 오는 거야?"     → 데이터 흐름도
"이 서비스 죽으면 뭐가 영향받아?"   → 장애 영향 범위
"이 부분 성능이 느린데 뭘 봐야 해?" → 병목 지점 파악

---

아키텍처 문서 구조 (C4 Model 기반)

레벨	이름	독자	내용
L1	System Context	비개발자	시스템과 외부 연동
L2	Container	아키텍트	서비스/DB/큐 구성
L3	Component	개발자	모듈/클래스 수준
L4	Code	유지보수자	핵심 클래스 UML

제조 AI 프로젝트에서는 L2 (Container) + 데이터 흐름도가 핵심

---

제조 AI 시스템의 데이터 흐름도

데이터 흐름 (사용자 질문 → 최종 응답)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

사용자: "CNC E-001 에러가 자꾸 나요. 어떻게 해야 하나요?"

                  ┌─────────┐
                  │ Streamlit│
                  │   UI    │
                  └────┬────┘
                       │ POST /api/diagnose
                       ▼
                  ┌─────────┐
                  │ FastAPI  │
                  │ Gateway  │
                  └────┬────┘
                       │ Agent Router (LangGraph)
                       ▼
              ┌────────┴────────┐
              │                 │
        ┌─────▼─────┐   ┌──────▼──────┐
        │  KG Tool   │   │  RAG Tool   │
        │ (Neo4j)    │   │ (ChromaDB)  │
        └─────┬─────┘   └──────┬──────┘
              │ Cypher 쿼리    │ 유사도 검색
              │                │
        ┌─────▼─────┐   ┌──────▼──────┐
        │ 관련 설비   │   │ 매뉴얼 문서  │
        │ 부품, 이력  │   │ 안전 기준서  │
        └─────┬─────┘   └──────┬──────┘
              │                │
              └────────┬───────┘
                       │ 컨텍스트 통합
                       ▼
                  ┌─────────┐
                  │  LLM    │
                  │ (GPT-4o)│
                  └────┬────┘
                       │ 진단 결과 + 조치 방법
                       ▼
                  ┌─────────┐
                  │  응답    │
                  └─────────┘

---

Mermaid로 다이어그램 그리기

GitHub README에서 바로 렌더링되는 Mermaid:

```mermaid
graph TD
    A[사용자] --> B[Streamlit UI]
    B --> C[FastAPI Gateway]
    C --> D{Agent Router}
    D --> E[RAG Tool]
    D --> F[KG Tool]
    D --> G[Diagnosis Tool]
    E --> H[ChromaDB]
    F --> I[Neo4j]
    G --> J[에러 이력 DB]
    E --> K[LLM]
    F --> K
    G --> K
    K --> L[진단 응답]

---

## 운영 매뉴얼 필수 항목

| 섹션 | 내용 | 왜 필요한가 |
|------|------|------------|
| **배포 절차** | docker compose 명령, 환경변수 | 새로운 서버에 배포할 때 |
| **모니터링** | 로그 위치, 알림 설정 | 장애 감지 |
| **백업/복구** | DB 백업 주기, 복구 절차 | 데이터 손실 방지 |
| **장애 대응** | 자주 발생하는 에러와 해결법 | 새벽에 장애 나면? |
| **스케일링** | CPU/메모리 기준, 스케일 방법 | 트래픽 증가 시 |

### 장애 대응 런북 예시

장애 대응 런북 (Runbook) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━

증상: Neo4j 연결 실패 원인: 1) Neo4j 컨테이너 다운 2) 메모리 부족 3) 볼륨 마운트 이상

대응:

1. docker ps | grep neo4j 로 상태 확인
2. docker logs neo4j --tail 50 로 로그 확인
3. 컨테이너 재시작: docker compose restart neo4j
4. 메모리 부족 시: NEO4J_HEAP_SIZE 조정 후 재시작

에스컬레이션:

• 30분 내 해결 안 되면 → 인프라팀 연락

---

## 핵심 정리

1. 아키텍처 문서는 **데이터 흐름도**가 핵심
2. Mermaid로 GitHub에서 바로 렌더링 가능
3. 운영 매뉴얼 없이 프로덕션 배포는 **시한폭탄**
4. 장애 대응 런북은 **새벽 3시에 빛난다**