시스템 아키텍처 계획 문서

This content is not available in your language yet.

🏗️ 시스템 아키텍처 계획 문서

이 폴더는 Newsfork 시스템의 아키텍처 설계 및 계획 문서들을 포함합니다.

📋 문서 목록

🔍 엔진 개요 및 비교

Research 엔진 vs Seed 엔진 개요
- 두 엔진의 역할과 책임 분리
- 전체 데이터 파이프라인 흐름
- 핵심 차이점 및 상호작용

🔬 Research 엔진 (URL 발견)

Research 엔진 상세 설명
- URL 발견 및 도메인 정규화
- 생존성 확인 (Liveness Check)
- 배치 처리 및 Queue 시스템
- API 엔드포인트 및 데이터 스키마

🌱 Seed 엔진 (수집 계약 생성)

Seed 엔진 상세 설명
- Raw/Prod 2단계 데이터 모델
- 3단계 워크플로우 (Orchestrator → File Processor → Domain Collector)
- 기술 메타데이터 수집 (robots.txt, sitemap.xml)
- 체크포인트 시스템 및 Idempotency

🎯 핵심 개념

📊 데이터 파이프라인

[Research Engine] → [Seed Engine] → [Scraper Engine]
     "어디서"          "어떻게"         "실제 수집"

🗄️ 스토리지 구조

R2 버킷:
├── research/datasets/    # Research 엔진 출력 (URL 발견)
├── research/liveness/    # 도메인 생존성 확인
├── raw/                  # Seed 엔진 입력 (불변 원본)
├── prod/                 # Seed 엔진 출력 (기술 메타데이터)
└── final/                # Scraper 엔진 출력 (실제 콘텐츠)

🔄 역할 분리 원칙

엔진	입력	처리	출력	책임
Research	검색 쿼리, 힌트	URL 발견, 정규화	`research/datasets/`	”어디서 찾을까?”
Seed	Research 출력	기술 메타데이터 수집	`raw/`, `prod/`	”어떻게 가져올까?”
Scraper	Seed 출력	실제 콘텐츠 수집	`final/content/`	”실제로 수집”

🛠️ 기술 스택

🏗️ 인프라 (Cloudflare 네이티브)

Cloudflare Workers: 서버리스 컴퓨팅
Cloudflare R2: 객체 스토리지 (S3 호환)
Cloudflare D1: SQLite 기반 엣지 데이터베이스
Cloudflare KV: 키-값 캐시 스토리지
Cloudflare Queues: 비동기 작업 큐

🔧 애플리케이션 스택

TypeScript: ES2022+ 기준
Hono: 경량 웹 프레임워크
Zod: 스키마 검증 라이브러리
Drizzle ORM: 타입 세이프 ORM

⚡ Queue 시스템

Research 엔진:
├── RESEARCH_QUEUE → URL 발견 작업
└── LIVENESS_QUEUE → 도메인 생존성 확인

Seed 엔진:
├── SEED_QUEUE → Raw 파일 처리
└── DOMAIN_QUEUE → 도메인별 메타데이터 수집

📋 설계 원칙

🎯 관심사의 분리 (Separation of Concerns)

Research: URL 발견에만 집중, 판단하지 않음
Seed: 기술적 메타데이터 수집, 콘텐츠 수집하지 않음
Scraper: 실제 콘텐츠 수집, 발견하지 않음

🔄 데이터 불변성

research/datasets/: 완전 불변, 시점별 스냅샷
raw/: 불변 원본, 덮어쓰기 금지
prod/: 갱신 가능, 파이프라인 재실행 시 업데이트

🛡️ 안정성 보장

체크포인트 시스템: .success 파일을 통한 idempotency
재시도 전략: 지수 백오프 및 DLQ 처리
에러 분류: 재시도 가능/불가능 에러 구분

📈 확장성

병렬 처리: 파일/도메인별 독립적 처리
적응형 동시성: 에러율 기반 동시성 조정
환경 분리: dev/staging/prod 완전 격리

🔗 관련 문서

📚 구현 가이드

🔧 운영 문서

📋 규칙 및 표준

🚀 향후 계획

🔄 Phase 2: Scraper 엔진

Seed 엔진 출력을 기반으로 한 실제 콘텐츠 수집
콘텐츠 타입별 특화 수집 로직
품질 검증 및 구조화

📊 Phase 3: 분석 엔진

수집된 콘텐츠의 자동 분류
중복 제거 및 품질 평가
실시간 모니터링 및 알람

🤖 Phase 4: AI 통합

콘텐츠 요약 및 키워드 추출
자동 태깅 및 카테고리 분류
이상 탐지 및 품질 개선

이 문서들은 Newsfork 시스템의 전체 아키텍처를 이해하고, 각 엔진의 역할과 상호작용을 파악하는 데 도움이 됩니다. 구체적인 구현 세부사항은 각 엔진별 상세 문서를 참조하세요.