Architecture

Architecture

전체 데이터 파이프라인

HackDigest의 핵심은 5단계 파이프라인입니다:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   1. FETCH  │────►│   2. RANK   │────►│ 3. SUMMARIZE│────►│  4. CACHE   │────►│  5. DELIVER │
│  (fetchers) │     │  (scoring)  │     │ (Groq LLM)  │     │ (JSON file) │     │ (Gmail SMTP)│
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

상세 흐름

cronjob.io (매일 KST 10:15)
  │
  ▼ workflow_dispatch
GitHub Actions Workflow (daily-digest.yml)
  │
  ├── 1. 보안 스캔 (security-scan job)
  │     └── 하드코딩된 시크릿 검사
  │
  ├── 2. 캐시 복원 (GitHub Actions Cache)
  │     └── data/cache/ 디렉토리
  │
  └── 3. 파이프라인 실행 (python -m src.main)
        │
        ├── 구독자 로드 (subscribers.json)
        │
        ├── (topic, language) 조합 계산
        │     예: (tech, ko), (stocks, en), (realestate, ko)
        │
        ├── Fetch: 토픽별 기사 수집
        │   ├── tech:       Hacker News API → 상위 50개 필터링 → Top 5
        │   ├── stocks(en): Yahoo Finance RSS
        │   ├── stocks(ko): Google News Korea RSS
        │   ├── realestate(en): Zillow + HousingWire + CNBC RSS
        │   └── realestate(ko): Google News Korea RSS
        │
        ├── Summarize: 캐시 미스 기사만 Groq API 호출
        │   ├── trafilatura로 기사 본문 추출
        │   ├── 3000자 제한 → Groq qwen/qwen3.8-27b
        │   ├── 언어별 프롬프트 (한국어: 캐주얼 블로거, 영어: casual)
        │   ├── Rate limit 시 지수 백오프 재시도 (최대 3회)
        │   └── 실패 시 Google Translate 폴백
        │
        ├── Cache: 기사 + 요약 JSON 저장
        │
        └── Deliver: 구독자별 이메일 발송
            ├── 단일 SMTP 연결로 모든 이메일 처리
            ├── HTML 템플릿: 모바일 친화적
            ├── 구독 해지 링크 포함
            └── 실패 시 다음 구독자로 계속

구독 흐름

┌──────────────────────┐
│  구독 페이지          │
│  (GitHub Pages)      │
│  docs/index.html     │
└──────────┬───────────┘
           │ POST (이메일, 언어, 토픽)
           ▼
┌──────────────────────┐
│  Cloudflare Worker   │
│  worker/src/index.js │
│                      │
│  ─ CORS 검증         │
│  ─ Rate limiting     │
│  ─ 입력 검증         │
│  ─ 이메일 길이 제한   │
└──────────┬───────────┘
           │ repository_dispatch
           ▼
┌──────────────────────┐
│  GitHub Actions      │
│  subscribers.yml     │
│                      │
│  ─ subscribers.json  │
│    에 추가/삭제       │
│  ─ 환영 이메일 발송   │
│  ─ 변경사항 커밋+푸시 │
└──────────────────────┘

토픽별 데이터 소스

Tech (언어 독립적)

• 소스: Hacker News API (hacker-news.firebaseio.com)
• 방식: Top Stories → 상위 50개 fetch → 비기술 필터링 → 점수순 Top 5
• 필터링: 정치, 스포츠, 다이어트, 유명인 등 비기술 키워드 제외

Stocks (언어 의존적)

• 영어: Yahoo Finance RSS
• 한국어: Google News Korea (주식+코스피+코스닥, 증시+주가+상장)
• 필터링: 주식/시장 관련 키워드 매칭 (영어/한국어 별도 패턴)

Real Estate (언어 의존적)

• 영어: Zillow Research + HousingWire + CNBC Real Estate RSS
• 한국어: Google News Korea (부동산+아파트+매매, 부동산+전세+분양)
• 필터링: 부동산 관련 키워드 매칭

캐싱 전략

data/cache/
├── articles_{topic}.json        # 기사 캐시 (토픽별)
└── summaries_{language}.json    # 요약 캐시 (언어별)

• GitHub Actions Cache를 사용하여 일간 캐시
• 같은 기사가 여러 구독자에게 발송될 때 중복 API 호출 방지
• 요약은 언어별로 캐시 (한국어 요약과 영어 요약은 별도)
• 캐시 키: hackdigest-v2-{run_id} (실행마다 새 캐시 생성, 이전 캐시에서 복원)

보안 설계

레이어	보호
Cloudflare Worker	CORS origin 제한, Rate limiting (분당 5건, 시간당 20건), 필드 화이트리스트, Body 크기 제한 (1KB)
GitHub Actions	하드코딩 시크릿 스캔, Bandit 정적 분석
이메일	URL sanitization (http/https만), HTML escape
구독자 관리	최대 500명 제한, 이메일 형식 검증