# muzuiyo/cfrss architecture

> Architecture diagram of the GitHub repository muzuiyo/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/muzuiyo/cfrss
- Repository: https://github.com/muzuiyo/cfrss

## Overview

RSS Reader’s main workflow is: a signed-in reader selects or searches a feed view, the Next.js interface requests articles from the Worker API, and the API returns persisted feed/article state. Feed subscriptions can be refreshed manually or on a 12-hour schedule; the fetcher retrieves RSS/Atom documents, parses them with conditional-request support, and stores resulting feed and article data. The product also covers GitHub OAuth, OPML transfer, and user settings. The README establishes these capabilities; route and hook internals not sampled are represented only where their paths and responsibilities are documented.

Main entry points: [`backend/src/index.ts`](https://github.com/muzuiyo/cfrss/blob/main/backend/src/index.ts) (API entry), [`frontend/src/app/page.tsx`](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/app/page.tsx) (Reader app), [`backend/src/db/index.ts`](https://github.com/muzuiyo/cfrss/blob/main/backend/src/db/index.ts) (D1 database), [`backend/src/services/feed-fetcher.ts`](https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/feed-fetcher.ts) (Feed fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Reader interface"]
  node_frontend["Reader app<br/>[page.tsx]"]
  node_auth_ui["Auth provider<br/>[auth-provider.tsx]"]
  node_auth_client["Auth client<br/>[auth.ts]"]
  node_article_ui["Article views<br/>[article-list.tsx]"]
  node_sidebar["Feed sidebar<br/>[sidebar.tsx]"]
  node_settings_ui["Settings view<br/>[settings-view.tsx]"]
  node_hooks["Data hooks<br/>[use-articles.ts]"]
  node_feed_hooks["Feed hooks<br/>[use-feeds.ts]"]
  node_settings_hooks["Settings hooks<br/>[use-settings.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Worker API"]
  node_worker["API entry<br/>[index.ts]"]
  node_auth_routes["OAuth routes<br/>[auth.ts]"]
  node_auth_middleware["Auth middleware<br/>[auth.ts]"]
  node_feed_routes["Feed routes<br/>[feeds.ts]"]
  node_article_routes["Article routes<br/>[articles.ts]"]
  node_opml_routes["OPML routes<br/>[opml.ts]"]
  node_opml_service["OPML service<br/>[opml.ts]"]
  node_settings_routes["Settings routes<br/>[settings.ts]"]
end

subgraph group_ingestion["Feed ingestion"]
  node_fetcher["Feed fetcher<br/>[feed-fetcher.ts]"]
  node_parser["RSS/Atom parser<br/>[rss-parser.ts]"]
end

subgraph group_state["Persistent data"]
  node_database[("D1 database<br/>[index.ts]")]
  node_schema["Data schema<br/>[schema.ts]"]
end

node_reader(("Reader"))
node_scheduled(("Scheduled trigger"))
node_feed_sources(("RSS sources"))
node_github(("GitHub OAuth"))

node_reader -->|"uses"| node_frontend
node_frontend -->|"checks session"| node_auth_ui
node_auth_ui -->|"calls"| node_auth_client
node_auth_client -->|"requests auth"| node_worker
node_frontend -->|"selects articles"| node_hooks
node_frontend -->|"loads feeds"| node_feed_hooks
node_frontend -->|"renders"| node_article_ui
node_frontend -->|"renders"| node_sidebar
node_frontend -->|"renders"| node_settings_ui
node_settings_ui -->|"reads and updates"| node_settings_hooks
node_hooks -->|"requests data"| node_api_client
node_feed_hooks -->|"requests data"| node_api_client
node_settings_hooks -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_worker
node_worker -->|"guards API"| node_auth_middleware
node_worker -->|"dispatches auth"| node_auth_routes
node_worker -->|"dispatches feeds"| node_feed_routes
node_worker -->|"dispatches articles"| node_article_routes
node_worker -->|"dispatches OPML"| node_opml_routes
node_worker -->|"dispatches settings"| node_settings_routes
node_worker -->|"creates database access"| node_database
node_auth_routes -->|"exchanges OAuth"| node_github
node_auth_middleware -->|"provides authorized context"| node_database
node_feed_routes -->|"reads and writes"| node_database
node_feed_routes -->|"refreshes feeds"| node_fetcher
node_article_routes -->|"reads and writes"| node_database
node_opml_routes -->|"handles transfer"| node_opml_service
node_opml_routes -->|"reads and writes"| node_database
node_settings_routes -->|"reads and writes"| node_database
node_scheduled -->|"triggers schedule"| node_worker
node_worker -->|"refreshes all feeds"| node_fetcher
node_fetcher -->|"loads and stores feed data"| node_database
node_fetcher -->|"parses source"| node_parser
node_parser -->|"fetches RSS/Atom"| node_feed_sources
node_database -->|"uses schema"| node_schema

click node_frontend "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/app/page.tsx"
click node_auth_ui "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/auth-provider.tsx"
click node_auth_client "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/lib/auth.ts"
click node_article_ui "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/article-list.tsx"
click node_sidebar "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/sidebar.tsx"
click node_settings_ui "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/settings-view.tsx"
click node_hooks "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-articles.ts"
click node_feed_hooks "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-feeds.ts"
click node_settings_hooks "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-settings.ts"
click node_api_client "https://github.com/muzuiyo/cfrss/blob/main/frontend/src/lib/api.ts"
click node_worker "https://github.com/muzuiyo/cfrss/blob/main/backend/src/index.ts"
click node_auth_routes "https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/auth.ts"
click node_auth_middleware "https://github.com/muzuiyo/cfrss/blob/main/backend/src/middleware/auth.ts"
click node_feed_routes "https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/feeds.ts"
click node_article_routes "https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/articles.ts"
click node_opml_routes "https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/opml.ts"
click node_opml_service "https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/opml.ts"
click node_settings_routes "https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/settings.ts"
click node_fetcher "https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/feed-fetcher.ts"
click node_parser "https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/rss-parser.ts"
click node_database "https://github.com/muzuiyo/cfrss/blob/main/backend/src/db/index.ts"
click node_schema "https://github.com/muzuiyo/cfrss/blob/main/backend/src/db/schema.ts"

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_frontend,node_auth_ui,node_auth_client,node_article_ui,node_sidebar,node_settings_ui,node_hooks,node_feed_hooks,node_settings_hooks,node_api_client toneBlue
class node_worker,node_auth_routes,node_auth_middleware,node_feed_routes,node_article_routes,node_opml_routes,node_opml_service,node_settings_routes toneAmber
class node_fetcher,node_parser toneMint
class node_database,node_schema toneRose
class node_reader,node_scheduled,node_feed_sources,node_github toneIndigo
```

## Components

### Reader interface

- [Reader app](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Auth provider](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/auth-provider.tsx): `frontend/src/components/auth-provider.tsx`
- [Auth client](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/lib/auth.ts): `frontend/src/lib/auth.ts`
- [Article views](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/article-list.tsx): `frontend/src/components/article-list.tsx`
- [Feed sidebar](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/sidebar.tsx): `frontend/src/components/sidebar.tsx`
- [Settings view](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/components/settings-view.tsx): `frontend/src/components/settings-view.tsx`
- [Data hooks](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-articles.ts): `frontend/src/hooks/use-articles.ts`
- [Feed hooks](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-feeds.ts): `frontend/src/hooks/use-feeds.ts`
- [Settings hooks](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/hooks/use-settings.ts): `frontend/src/hooks/use-settings.ts`
- [API client](https://github.com/muzuiyo/cfrss/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Worker API

- [API entry](https://github.com/muzuiyo/cfrss/blob/main/backend/src/index.ts): `backend/src/index.ts`
- [OAuth routes](https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Auth middleware](https://github.com/muzuiyo/cfrss/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`
- [Feed routes](https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/feeds.ts): `backend/src/routes/feeds.ts`
- [Article routes](https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/articles.ts): `backend/src/routes/articles.ts`
- [OPML routes](https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/opml.ts): `backend/src/routes/opml.ts`
- [OPML service](https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/opml.ts): `backend/src/services/opml.ts`
- [Settings routes](https://github.com/muzuiyo/cfrss/blob/main/backend/src/routes/settings.ts): `backend/src/routes/settings.ts`

### Feed ingestion

- [Feed fetcher](https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/feed-fetcher.ts): `backend/src/services/feed-fetcher.ts`
- [RSS/Atom parser](https://github.com/muzuiyo/cfrss/blob/main/backend/src/services/rss-parser.ts): `backend/src/services/rss-parser.ts`

### Persistent data

- [D1 database](https://github.com/muzuiyo/cfrss/blob/main/backend/src/db/index.ts): `backend/src/db/index.ts`
- [Data schema](https://github.com/muzuiyo/cfrss/blob/main/backend/src/db/schema.ts): `backend/src/db/schema.ts`

### Other components

- **Reader**
- **Scheduled trigger**
- **RSS sources**
- **GitHub OAuth**

## Connections

- Reader → Reader app: uses
- Reader app → Auth provider: checks session
- Auth provider → Auth client: calls
- Auth client → API entry: requests auth
- Reader app → Data hooks: selects articles
- Reader app → Feed hooks: loads feeds
- Reader app → Article views: renders
- Reader app → Feed sidebar: renders
- Reader app → Settings view: renders
- Settings view → Settings hooks: reads and updates
- Data hooks → API client: requests data
- Feed hooks → API client: requests data
- Settings hooks → API client: requests data
- API client → API entry: HTTP requests
- API entry → Auth middleware: guards API
- API entry → OAuth routes: dispatches auth
- API entry → Feed routes: dispatches feeds
- API entry → Article routes: dispatches articles
- API entry → OPML routes: dispatches OPML
- API entry → Settings routes: dispatches settings
- API entry → D1 database: creates database access
- OAuth routes → GitHub OAuth: exchanges OAuth
- Auth middleware → D1 database: provides authorized context
- Feed routes → D1 database: reads and writes
- Feed routes → Feed fetcher: refreshes feeds
- Article routes → D1 database: reads and writes
- OPML routes → OPML service: handles transfer
- OPML routes → D1 database: reads and writes
- Settings routes → D1 database: reads and writes
- Scheduled trigger → API entry: triggers schedule
- API entry → Feed fetcher: refreshes all feeds
- Feed fetcher → D1 database: loads and stores feed data
- Feed fetcher → RSS/Atom parser: parses source
- RSS/Atom parser → RSS sources: fetches RSS/Atom
- D1 database → Data schema: uses schema