# cyanburu.com 홈랩 아키텍처

## 전체 구조

```mermaid
flowchart TD
  User["외부 사용자\nhttps://cyanburu.com"]
  Router["MSI 라우터\n포트포워딩 80/443"]
  Ingress["Nginx Ingress Controller\nTLS 종료 · Let's Encrypt 인증서"]
  CoreDNS["CoreDNS\n내부 도메인 헤어핀 NAT 우회"]

  User --> Router --> Ingress --> CoreDNS

  subgraph K8s["Docker Desktop Kubernetes"]
    subgraph WebPortal["web-portal namespace"]
      FE["Frontend\nNginx · index.html"]
      BE["Backend\nFastAPI · main.py"]
      DB["PostgreSQL\nportaldb"]
      Notifier["notifier.py\nDiscord · Gmail 다중 채널"]
      Monitor["monitor.py\nPod 1분 · 인증서 24시간"]
      NotifyCh["notify_channels\nDB 테이블"]

      FE --> BE --> DB
      BE --> Notifier
      BE --> Monitor
      Notifier --> NotifyCh
    end

    subgraph GitOps["GitOps 파이프라인"]
      Gitea["Gitea\n코드 · Container Registry"]
      ArgoCD["ArgoCD\nGitOps 자동 배포"]
      Deploy["K8s Deployment\nbackend · frontend"]

      Gitea -->|git push| ArgoCD -->|sync| Deploy
      Gitea -->|image pull| Deploy
    end

    CoreDNS --> WebPortal
  end

  Notifier -->|Webhook| Discord["Discord"]
  Notifier -->|SMTP SSL| Gmail["Gmail"]
```

---

## 네임스페이스 구성

| 네임스페이스 | 구성 요소 | 역할 |
|-------------|----------|------|
| `web-portal` | Frontend, Backend, PostgreSQL | 웹 포털 서비스 |
| `gitea` | Gitea, PostgreSQL-HA, Valkey | 코드 저장소 + Container Registry |
| `argocd` | ArgoCD Server | GitOps 자동 배포 |
| `ingress-nginx` | Nginx Ingress Controller | 외부 트래픽 라우팅 + TLS |
| `cert-manager` | cert-manager | Let's Encrypt 인증서 자동 발급 |

---

## 도메인 구성

| 도메인 | 서비스 | 인증서 |
|--------|-------|--------|
| `cyanburu.com` | Web Portal | Let's Encrypt |
| `gitea.cyanburu.com` | Gitea | Let's Encrypt |
| `argo.cyanburu.com` | ArgoCD | Let's Encrypt |

---

## 배포 흐름 (GitOps)

```mermaid
sequenceDiagram
  participant Dev as 개발자
  participant Gitea as Gitea
  participant Registry as Container Registry
  participant ArgoCD as ArgoCD
  participant K8s as Kubernetes

  Dev->>Gitea: git push (코드 변경)
  Dev->>Registry: docker build & push
  Gitea-->>ArgoCD: Webhook 감지
  ArgoCD->>K8s: Sync (yaml 적용)
  K8s->>Registry: image pull
  K8s-->>Dev: Pod Running
```

---

## 알림 채널 발송 규칙

| 채널 유형 | Pod 이상/복구 | 계정 잠금/임시PW | 인증서 만료 |
|---------|-------------|----------------|------------|
| Discord+Gmail | Discord + Gmail | Discord만 | Gmail만 |
| Discord 전용 | Discord만 | Discord만 | 발송 안 함 |
| Gmail 전용 | Gmail만 | 발송 안 함 | Gmail만 |

---

## 이미지 레지스트리 주의사항

Docker Desktop 환경에서는 kubelet이 Docker 데몬을 통해 이미지를 Pull하므로
K8s 내부 DNS(`gitea-http.gitea.svc.cluster.local`)를 사용할 수 없음.

**반드시 외부 IP 사용:**
```
192.168.10.101:30000/qorgh529/portal-backend:latest
192.168.10.101:30000/qorgh529/portal-frontend:latest
```