# ccbikai/hacker-news architecture

> Architecture diagram of the GitHub repository ccbikai/hacker-news, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ccbikai/hacker-news
- Repository: https://github.com/ccbikai/hacker-news

## Overview

##### Project Type and Purpose
- This is a full-stack, serverless web application combined with a Cloudflare Worker–driven data‐processing workflow.
- Purpose: every day fetch Hacker News top posts, summarize with OpenAI, synthesize audio via Edge TTS, store results in Cloudflare R2/KV, and expose via a Next.js-based website and RSS feed.

##### Key Architectural Components
a. Scheduled Trigger
- A time-based Cron trigger configured in Cloudflare Workers (via `wrangler.jsonc`) to kick off the workflow once per day.
b. Data-Processing Worker & Workflow
- `worker/index.ts` + `workflow/*.ts` files implement:
– Fetch top Hacker News articles (external HN API).
– Call OpenAI API to generate Chinese summaries.
– Call Edge TTS (Minimax Audio) to produce audio clips.
– Merge or process audio in a headless browser environment.
– Store JSON metadata and text in KV; store audio files in R2.
c. Storage Layer
- Cloudflare KV: stores metadata, text transcripts, pointers to audio URLs.
- Cloudflare R2: stores TTS-generated audio files.
d. Web Frontend
- Next.js 13 “app” directory:
– `app/page.tsx`: homepage listing episodes.
– `app/post/[date]/page.tsx`: individual episode pages.
– `app/rss.xml/route.ts`: RSS feed endpoint.
– `app/static/[...path]/route.ts`: serves static assets from R2.
- shadcn-ui + Tailwind for styling; OpenNext adapter for Cloudflare deployment.
e. External Services
- Hacker News API (data source).
- OpenAI API (text summarization).
- Edge TTS (audio generation via Minimax Audio).
f. Clients
- Web browsers (Next.js UI).
- Podcast apps via RSS feed.
- Any HTTP-capable RSS reader.

##### Relationships & Data Flows
- Cron → Worker (HTTP trigger or scheduled) → workflow code
- workflow → Hacker News API → receives articles
- workflow → OpenAI API → returns summaries
- workflow → Edge TTS → returns audio blobs
- workflow → Cloudflare R2 (audio) + KV (JSON/text)
- Next.js UI & RSS → read from KV & R2 → render pages & feeds
- Client (browser or podcast app) ← HTTP ← Next.js app or RSS endpoint

##### Architectural Patterns & Principles
- Serverless, event-driven: Cron triggers + Workers + KV/R2 storage.
- Micro-workflow: discrete steps (fetch → summarize → synthesize → store).
- Separation of concerns: data pipeline (Worker+workflow) vs. presentation layer (Next.js).
- Cloud-native: all components deployed on Cloudflare edge for low latency.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Scheduler Layer
    subgraph "Scheduler"
        Cron["Cron Trigger"]:::compute
    end

    %% Data Pipeline Layer
    subgraph "Data Pipeline"
        Worker["Cloudflare Worker\n(fetch & workflow)"]:::compute
        subgraph "Workflow Modules"
            Fetch["Fetch & Orchestration"]:::compute
            Prompt["Prompt Templates"]:::compute
            TTSModule["TTS Integration"]:::compute
            Utils["Shared Utilities"]:::compute
        end
        StaticAssets["Worker Static Assets"]:::compute
    end

    %% External Services Layer
    subgraph "External Services"
        HN["Hacker News API"]:::external
        OpenAI["OpenAI API"]:::external
        EdgeTTS["Edge TTS"]:::external
    end

    %% Storage Layer
    subgraph "Storage"
        KV["Cloudflare KV"]:::storage
        R2["Cloudflare R2"]:::storage
    end

    %% Frontend Layer
    subgraph "Frontend - Next.js Application"
        subgraph "Core Configuration"
            Layout["Global Layout"]:::frontend
            Styles["Global Styles"]:::frontend
            NextConfig["Next.js Config"]:::frontend
            OpenNext["OpenNext Adapter Config"]:::frontend
        end
        subgraph "App Routes"
            Home["Homepage\n(app/page.tsx)"]:::frontend
            Post["Episode Detail\n(app/post/[date]/page.tsx)"]:::frontend
            RSS["RSS Feed Endpoint\n(app/rss.xml/route.ts)"]:::frontend
            StaticRoute["Static Asset Proxy\n(app/static/[...path]/route.ts)"]:::frontend
        end
        subgraph "UI Components"
            ArticleCard["Article Card\n(components/article-card.tsx)"]:::frontend
            UIComp["shadcn-ui/Tailwind\n(components/ui/)"]:::frontend
        end
    end

    %% Clients Layer
    subgraph "Clients"
        Browser["Web Browser"]:::client
        Podcast["Podcast App / RSS Reader"]:::client
    end

    %% Connections
    Cron -->|"daily trigger"| Worker
    Worker -->|invokes| Fetch
    Fetch -->|GET top posts| HN
    Fetch -->|POST summarize request| OpenAI
    Fetch -->|POST TTS request| EdgeTTS
    Fetch -->|uses| Prompt
    Fetch -->|uses| Utils
    Fetch -->|"PUT JSON & text"| KV
    Fetch -->|"PUT audio file"| R2
    StaticAssets -->|serves demo assets| Worker

    Home -->|read data| KV
    Home -->|fetch audio| R2
    Post -->|read data| KV
    Post -->|fetch audio| R2
    RSS -->|read data| KV
    RSS -->|fetch audio| R2
    StaticRoute -->|proxy audio| R2

    Browser --> Home
    Browser --> Post
    Podcast --> RSS

    %% Click Events
    click Cron "https://github.com/ccbikai/hacker-news/blob/main/worker/wrangler.jsonc"
    click Worker "https://github.com/ccbikai/hacker-news/blob/main/worker/index.ts"
    click Fetch "https://github.com/ccbikai/hacker-news/blob/main/workflow/index.ts"
    click Prompt "https://github.com/ccbikai/hacker-news/blob/main/workflow/prompt.ts"
    click TTSModule "https://github.com/ccbikai/hacker-news/blob/main/workflow/tts.ts"
    click Utils "https://github.com/ccbikai/hacker-news/blob/main/workflow/utils.ts"
    click StaticAssets "https://github.com/ccbikai/hacker-news/tree/main/worker/static/"
    click Layout "https://github.com/ccbikai/hacker-news/blob/main/app/layout.tsx"
    click Styles "https://github.com/ccbikai/hacker-news/blob/main/app/globals.css"
    click Home "https://github.com/ccbikai/hacker-news/blob/main/app/page.tsx"
    click Post "https://github.com/ccbikai/hacker-news/blob/main/app/post/[date]/page.tsx"
    click RSS "https://github.com/ccbikai/hacker-news/blob/main/app/rss.xml/route.ts"
    click StaticRoute "https://github.com/ccbikai/hacker-news/blob/main/app/static/[...path]/route.ts"
    click NextConfig "https://github.com/ccbikai/hacker-news/blob/main/next.config.mjs"
    click OpenNext "https://github.com/ccbikai/hacker-news/blob/main/open-next.config.ts"
    click ArticleCard "https://github.com/ccbikai/hacker-news/blob/main/components/article-card.tsx"
    click UIComp "https://github.com/ccbikai/hacker-news/tree/main/components/ui/"

    %% Styles
    classDef compute fill:#b3cde0,stroke:#333,stroke-width:1px
    classDef storage fill:#ccebc5,stroke:#333,stroke-width:1px
    classDef external fill:#fdae61,stroke:#333,stroke-width:1px
    classDef frontend fill:#decbe4,stroke:#333,stroke-width:1px
    classDef client fill:#f0f0f0,stroke:#333,stroke-width:1px
```
