# ituff/cfrss architecture

> Architecture diagram of the GitHub repository ituff/cfrss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ituff/cfrss
- Repository: https://github.com/ituff/cfrss

## Overview

CFRSS is a self-hosted, single-user RSS reader: the reader manages subscriptions, retrieves and reads articles, and can use AI, speech, bookmarks, and a daily digest. Feed refresh runs both on demand and on a schedule; article metadata is stored in Cloudflare D1, while full text can be archived in the user’s GitHub repository. The graph follows documented capabilities and sampled routing/service calls; several handler-to-service links are omitted where their wiring was not shown.

Main entry points: [`src/index.ts`](https://github.com/ituff/cfrss/blob/main/src/index.ts) (HTTP routing), [`src/handlers/llm.ts`](https://github.com/ituff/cfrss/blob/main/src/handlers/llm.ts) (AI handlers), [`src/services/feed-refresh.ts`](https://github.com/ituff/cfrss/blob/main/src/services/feed-refresh.ts) (Feed refresh), [`src/client/services/api.ts`](https://github.com/ituff/cfrss/blob/main/src/client/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Reader app"]
  node_client_app["App bootstrap<br/>[main.ts]"]
  node_reading_ui["Reading views<br/>[main-view.ts]"]
  node_subscription_ui["Subscription views<br/>[index.ts]"]
  node_llm_ui["AI features<br/>[index.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_service_worker["Offline service worker<br/>[sw.js]"]
end

subgraph group_api["Worker API"]
  node_worker["HTTP routing<br/>[index.ts]"]
  node_article_handlers["Article handlers<br/>[articles.ts]"]
  node_subscription_handlers["Subscription handlers<br/>[subscriptions.ts]"]
  node_opml_handlers["OPML handlers<br/>[opml.ts]"]
  node_bookmark_handlers["Bookmark handlers<br/>[bookmarks.ts]"]
  node_llm_handlers["AI handlers<br/>[llm.ts]"]
  node_auth_middleware["Auth middleware<br/>[auth.ts]"]
  node_scheduled["Scheduled refresh<br/>[scheduled.ts]"]
end

subgraph group_domain["Reader services"]
  node_subscriptions["Subscription management"]
  node_refresh["Feed refresh<br/>[feed-refresh.ts]"]
  node_fetcher["Content fetching<br/>[content-fetcher.ts]"]
  node_content_store["Article content<br/>[content-store.ts]"]
  node_digest["Daily digest<br/>[daily-digest.ts]"]
  node_llm_proxy["LLM proxy<br/>[llm-proxy.ts]"]
end

subgraph group_storage["Data and integrations"]
  node_d1[("Cloudflare D1")]
  node_github[("GitHub repository")]
  node_feed_sources["RSS feeds"]
  node_llm_provider["LLM provider"]
  node_tts_service["Read-aloud service"]
end

node_reader(("Reader"))

node_reader -->|"opens"| node_client_app
node_client_app -->|"starts"| node_reading_ui
node_reading_ui -->|"requests data"| node_api_client
node_subscription_ui -->|"manages feeds"| node_api_client
node_llm_ui -->|"requests AI"| node_api_client
node_api_client -->|"calls API"| node_worker
node_worker -->|"checks access"| node_auth_middleware
node_worker -->|"dispatches"| node_article_handlers
node_worker -->|"dispatches"| node_subscription_handlers
node_worker -->|"dispatches"| node_opml_handlers
node_worker -->|"dispatches"| node_bookmark_handlers
node_worker -->|"dispatches"| node_llm_handlers
node_scheduled -->|"starts refresh"| node_refresh
node_article_handlers -->|"refreshes feeds"| node_refresh
node_refresh -->|"fetches feeds"| node_fetcher
node_fetcher -->|"reads feeds"| node_feed_sources
node_refresh -->|"stores metadata"| node_d1
node_content_store -->|"archives articles"| node_github
node_llm_handlers -->|"loads article text"| node_content_store
node_llm_handlers -->|"streams prompts"| node_llm_proxy
node_llm_proxy -->|"requests completion"| node_llm_provider
node_llm_handlers -->|"generates digest"| node_digest
node_llm_handlers -->|"reads and caches"| node_d1
node_subscription_handlers -->|"manages feeds"| node_subscriptions
node_subscriptions -->|"stores subscriptions"| node_d1
node_bookmark_handlers -->|"stores bookmarks"| node_d1
node_client_app -->|"registers"| node_service_worker
node_reader -.->|"uses read-aloud"| node_tts_service

click node_client_app "https://github.com/ituff/cfrss/blob/main/src/client/main.ts"
click node_reading_ui "https://github.com/ituff/cfrss/blob/main/src/client/components/main-view.ts"
click node_subscription_ui "https://github.com/ituff/cfrss/blob/main/src/client/components/subscription/index.ts"
click node_llm_ui "https://github.com/ituff/cfrss/blob/main/src/client/components/llm/index.ts"
click node_api_client "https://github.com/ituff/cfrss/blob/main/src/client/services/api.ts"
click node_worker "https://github.com/ituff/cfrss/blob/main/src/index.ts"
click node_article_handlers "https://github.com/ituff/cfrss/blob/main/src/handlers/articles.ts"
click node_subscription_handlers "https://github.com/ituff/cfrss/blob/main/src/handlers/subscriptions.ts"
click node_opml_handlers "https://github.com/ituff/cfrss/blob/main/src/handlers/opml.ts"
click node_bookmark_handlers "https://github.com/ituff/cfrss/blob/main/src/handlers/bookmarks.ts"
click node_llm_handlers "https://github.com/ituff/cfrss/blob/main/src/handlers/llm.ts"
click node_auth_middleware "https://github.com/ituff/cfrss/blob/main/src/middleware/auth.ts"
click node_scheduled "https://github.com/ituff/cfrss/blob/main/src/scheduled.ts"
click node_subscriptions "https://github.com/ituff/cfrss/blob/main/src/services/subscription-manager.ts"
click node_refresh "https://github.com/ituff/cfrss/blob/main/src/services/feed-refresh.ts"
click node_fetcher "https://github.com/ituff/cfrss/blob/main/src/services/content-fetcher.ts"
click node_content_store "https://github.com/ituff/cfrss/blob/main/src/services/content-store.ts"
click node_digest "https://github.com/ituff/cfrss/blob/main/src/services/daily-digest.ts"
click node_llm_proxy "https://github.com/ituff/cfrss/blob/main/src/services/llm-proxy.ts"
click node_service_worker "https://github.com/ituff/cfrss/blob/main/public/sw.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_app,node_reading_ui,node_subscription_ui,node_llm_ui,node_api_client,node_service_worker toneBlue
class node_worker,node_article_handlers,node_subscription_handlers,node_opml_handlers,node_bookmark_handlers,node_llm_handlers,node_auth_middleware,node_scheduled toneAmber
class node_subscriptions,node_refresh,node_fetcher,node_content_store,node_digest,node_llm_proxy toneMint
class node_d1,node_github,node_feed_sources,node_llm_provider,node_tts_service toneRose
class node_reader toneIndigo
```

## Components

### Reader app

- [App bootstrap](https://github.com/ituff/cfrss/blob/main/src/client/main.ts): `src/client/main.ts`
- [Reading views](https://github.com/ituff/cfrss/blob/main/src/client/components/main-view.ts): `src/client/components/main-view.ts`
- [Subscription views](https://github.com/ituff/cfrss/blob/main/src/client/components/subscription/index.ts): `src/client/components/subscription/index.ts`
- [AI features](https://github.com/ituff/cfrss/blob/main/src/client/components/llm/index.ts): `src/client/components/llm/index.ts`
- [API client](https://github.com/ituff/cfrss/blob/main/src/client/services/api.ts): `src/client/services/api.ts`
- [Offline service worker](https://github.com/ituff/cfrss/blob/main/public/sw.js): `public/sw.js`

### Worker API

- [HTTP routing](https://github.com/ituff/cfrss/blob/main/src/index.ts): `src/index.ts`
- [Article handlers](https://github.com/ituff/cfrss/blob/main/src/handlers/articles.ts): `src/handlers/articles.ts`
- [Subscription handlers](https://github.com/ituff/cfrss/blob/main/src/handlers/subscriptions.ts): `src/handlers/subscriptions.ts`
- [OPML handlers](https://github.com/ituff/cfrss/blob/main/src/handlers/opml.ts): `src/handlers/opml.ts`
- [Bookmark handlers](https://github.com/ituff/cfrss/blob/main/src/handlers/bookmarks.ts): `src/handlers/bookmarks.ts`
- [AI handlers](https://github.com/ituff/cfrss/blob/main/src/handlers/llm.ts): `src/handlers/llm.ts`
- [Auth middleware](https://github.com/ituff/cfrss/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [Scheduled refresh](https://github.com/ituff/cfrss/blob/main/src/scheduled.ts): `src/scheduled.ts`

### Reader services

- [Subscription management](https://github.com/ituff/cfrss/blob/main/src/services/subscription-manager.ts): `src/services/subscription-manager.ts`
- [Feed refresh](https://github.com/ituff/cfrss/blob/main/src/services/feed-refresh.ts): `src/services/feed-refresh.ts`
- [Content fetching](https://github.com/ituff/cfrss/blob/main/src/services/content-fetcher.ts): `src/services/content-fetcher.ts`
- [Article content](https://github.com/ituff/cfrss/blob/main/src/services/content-store.ts): `src/services/content-store.ts`
- [Daily digest](https://github.com/ituff/cfrss/blob/main/src/services/daily-digest.ts): `src/services/daily-digest.ts`
- [LLM proxy](https://github.com/ituff/cfrss/blob/main/src/services/llm-proxy.ts): `src/services/llm-proxy.ts`

### Data and integrations

- **Cloudflare D1**
- **GitHub repository**
- **RSS feeds**
- **LLM provider**
- **Read-aloud service**

### Other components

- **Reader**

## Connections

- Reader → App bootstrap: opens
- App bootstrap → Reading views: starts
- Reading views → API client: requests data
- Subscription views → API client: manages feeds
- AI features → API client: requests AI
- API client → HTTP routing: calls API
- HTTP routing → Auth middleware: checks access
- HTTP routing → Article handlers: dispatches
- HTTP routing → Subscription handlers: dispatches
- HTTP routing → OPML handlers: dispatches
- HTTP routing → Bookmark handlers: dispatches
- HTTP routing → AI handlers: dispatches
- Scheduled refresh → Feed refresh: starts refresh
- Article handlers → Feed refresh: refreshes feeds
- Feed refresh → Content fetching: fetches feeds
- Content fetching → RSS feeds: reads feeds
- Feed refresh → Cloudflare D1: stores metadata
- Article content → GitHub repository: archives articles
- AI handlers → Article content: loads article text
- AI handlers → LLM proxy: streams prompts
- LLM proxy → LLM provider: requests completion
- AI handlers → Daily digest: generates digest
- AI handlers → Cloudflare D1: reads and caches
- Subscription handlers → Subscription management: manages feeds
- Subscription management → Cloudflare D1: stores subscriptions
- Bookmark handlers → Cloudflare D1: stores bookmarks
- App bootstrap → Offline service worker: registers
- Reader → Read-aloud service: uses read-aloud