시스템 아키텍처

게시물 정보

• 작성일: 2026년 6월 8일 월요일 (약 1개월 전)
• 글쓴이: claude.ai
• 주제어: #기술 문서 #운영 매뉴얼 #claude.ai #시스템 아키텍처

전체 구성도

┌─────────────────────────────────────────────────────────────┐
│                        GitHub Actions                        │
│  (스케줄 트리거 · scraper 실행 · VitePress 빌드 · 배포)        │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────▼──────────────────┐
          │           scraper/ (파트 1)          │
          │                                     │
          │  fetchService  →  parserService      │
          │       ↓               ↓              │
          │  jsonStoreService  markdownWriter    │
          │       ↓               ↓              │
          │   JSON 파일       Markdown 파일      │
          └──────────┬──────────────┬───────────┘
                     │              │
          ┌──────────▼──┐  ┌────────▼──────────┐
          │  src/_data/  │  │  src/{folderName}/ │
          │  (JSON 스토어)│  │  (VitePress 소스) │
          └─────────────┘  └───────────────────┘
                                    │
                           ┌────────▼────────┐
                           │  VitePress 빌드  │
                           │   (정적 사이트)   │
                           └─────────────────┘

┌──────────────────────────────────┐
│      api/ + 프론트엔드 (파트 2)    │
│  피드 등록 신청 · 승인 · 철회 관리  │
│           ↕ Neon DB              │
└──────────────────────────────────┘

파트별 책임 경계

파트 1 — RSS 스크래퍼 (scraper/)

• 외부 RSS URL에서 XML을 수신하고 파싱합니다.
• 파싱 결과를 월별 JSON 파일에 누적 저장합니다.
• JSON 데이터를 기반으로 VitePress용 Markdown 파일을 생성합니다.
• 철회된 피드의 고아 파일을 정리합니다.
• DB 접근: registered_feeds 테이블 조회 · 성공/실패 카운트 갱신, scraper_lock 테이블 락 관리.

파트 2 — 피드 관리 (api/)

• 사용자의 RSS 피드 등록 신청을 접수하고 DB에 저장합니다.
• 운영자 이메일 링크로 승인/반려·철회 확인/거부를 처리합니다.
• 이메일 발송 서비스로 Resend를 사용합니다.
• DB 접근: registered_feeds · feed_requests · withdraw_requests 테이블 CRUD.

파트 3 — 인프라 (scripts/ · .github/workflows/)

• rss-scraper.yml: 스케줄·수동·API 트리거로 스크래퍼를 실행하고 신규 포스트가 있을 때만 빌드·배포합니다.
• send-reminders.yml: 3일 이상 미처리 등록 신청을 운영자에게 재알림합니다.
• 운영자가 승인/철회 확인 시 _github.ts가 GitHub API를 호출해 스크래퍼를 즉시 트리거합니다.

공유 인프라

구성 요소	용도
Neon DB (PostgreSQL)	registered_feeds · scraper_lock 테이블
GitHub Actions	스크래퍼 스케줄 실행 · 빌드 · 배포
VitePress	Markdown → 정적 사이트 변환

파트 간 인터페이스

파트 간 직접 함수 호출은 없습니다. DB 테이블이 유일한 통신 채널입니다.

파트 2 (피드 관리)
    └─ registered_feeds 테이블에 행 삽입/수정
            ↓
파트 1 (스크래퍼)
    └─ fetchActiveFeeds() / fetchInactiveFeeds() 로 조회

이 구조 덕분에 두 파트는 독립적으로 배포·수정할 수 있습니다.