# athou/commafeed architecture

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

## Overview

CommaFeed is a self-hosted RSS reader with a React client and Quarkus server. Users authenticate, subscribe to feeds or import OPML, browse entries by feed/category/tag, and mark or star them; settings and administration are separate workflows. The server fetches and parses subscribed feeds, stores entries and per-user status, then refreshes clients and sends configured notifications. The graph preserves documented API compatibility, cleanup, and customization capabilities; unsampled endpoint and page wiring is represented at subsystem level where the tree supports it.

Main entry points: [`commafeed-server/src/main/java/com/commafeed/frontend/resource/EntryREST.java`](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/resource/EntryREST.java) (REST resources), [`commafeed-client/src/app/store.ts`](https://github.com/athou/commafeed/blob/master/commafeed-client/src/app/store.ts) (Client state), [`commafeed-client/src/App.tsx`](https://github.com/athou/commafeed/blob/master/commafeed-client/src/App.tsx) (Reader UI), [`commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryService.java`](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryService.java) (Entry processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Reader client"]
  node_reader["Reader UI<br/>[App.tsx]"]
  node_clientstate["Client state<br/>[store.ts]"]
  node_clientapi["HTTP client<br/>[client.ts]"]
  node_entrypages["Reading pages"]
  node_sidebar["Feed navigation<br/>[Tree.tsx]"]
  node_settingsui["Settings UI<br/>[SettingsPage.tsx]"]
end

subgraph group_api["Server interfaces"]
  node_rest["REST resources<br/>[EntryREST.java]"]
  node_compatapi["Reader APIs<br/>[FeverREST.java]"]
  node_websocket["Live updates"]
  node_customize["Custom CSS JS"]
end

subgraph group_reading["Feed processing"]
  node_feedservice["Feed subscriptions<br/>[FeedService.java]"]
  node_refresh["Refresh engine"]
  node_fetchparse["Fetch and parse<br/>[FeedFetcher.java]"]
  node_entryservice["Entry processing"]
  node_contentclean["Content cleaning"]
  node_opml["OPML import export<br/>[OPMLImporter.java]"]
end

subgraph group_identity["Accounts and persistence"]
  node_users["User service<br/>[UserService.java]"]
  node_auth["Authentication"]
  node_daos["Data access<br/>[FeedEntryDAO.java]"]
  node_database[("Application database<br/>[UnitOfWork.java]")]
end

subgraph group_operations["Background and integrations"]
  node_scheduled["Scheduled cleanup<br/>[TaskScheduler.java]"]
  node_cleaning["Database cleanup"]
  node_push["Push notifications"]
  node_mail["Email service<br/>[MailService.java]"]
end

node_user(("Reader user"))
node_publisher(("Feed publishers"))
node_pushservice["Push providers"]
node_emailservice["Mail provider"]

node_user -->|"uses"| node_reader
node_reader -->|"dispatches"| node_clientstate
node_reader -->|"routes to"| node_entrypages
node_reader -->|"renders"| node_sidebar
node_entrypages -->|"dispatches"| node_clientstate
node_sidebar -->|"reads"| node_clientstate
node_settingsui -->|"dispatches"| node_clientstate
node_clientstate -->|"requests"| node_clientapi
node_clientapi -->|"HTTP calls"| node_rest
node_rest -->|"authenticates"| node_auth
node_rest -->|"invokes"| node_feedservice
node_rest -->|"invokes"| node_entryservice
node_rest -->|"invokes"| node_users
node_compatapi -->|"authenticates"| node_auth
node_compatapi -->|"invokes"| node_entryservice
node_feedservice -->|"queues refresh"| node_refresh
node_refresh -->|"refreshes feeds"| node_fetchparse
node_fetchparse -->|"fetches feeds"| node_publisher
node_fetchparse -->|"parsed entries"| node_entryservice
node_entryservice -->|"cleans content"| node_contentclean
node_feedservice -->|"reads writes"| node_daos
node_entryservice -->|"reads writes"| node_daos
node_users -->|"reads writes"| node_daos
node_daos -->|"queries"| node_database
node_opml -->|"imports subscriptions"| node_feedservice
node_rest -->|"imports exports"| node_opml
node_refresh -->|"notifies"| node_websocket
node_websocket -->|"pushes updates"| node_clientstate
node_refresh -->|"sends notifications"| node_push
node_push -.->|"posts notification"| node_pushservice
node_users -->|"sends account mail"| node_mail
node_mail -.->|"sends mail"| node_emailservice
node_scheduled -->|"runs cleanup"| node_cleaning
node_cleaning -->|"deletes records"| node_daos
node_customize -->|"serves customization"| node_reader

click node_reader "https://github.com/athou/commafeed/blob/master/commafeed-client/src/App.tsx"
click node_clientstate "https://github.com/athou/commafeed/blob/master/commafeed-client/src/app/store.ts"
click node_clientapi "https://github.com/athou/commafeed/blob/master/commafeed-client/src/app/client.ts"
click node_entrypages "https://github.com/athou/commafeed/blob/master/commafeed-client/src/pages/app/FeedEntriesPage.tsx"
click node_sidebar "https://github.com/athou/commafeed/blob/master/commafeed-client/src/components/sidebar/Tree.tsx"
click node_settingsui "https://github.com/athou/commafeed/blob/master/commafeed-client/src/pages/app/SettingsPage.tsx"
click node_rest "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/resource/EntryREST.java"
click node_compatapi "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/resource/fever/FeverREST.java"
click node_websocket "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/ws/WebSocketEndpoint.java"
click node_feedservice "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedService.java"
click node_refresh "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/feed/FeedRefreshEngine.java"
click node_fetchparse "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/feed/FeedFetcher.java"
click node_entryservice "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryService.java"
click node_contentclean "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryContentCleaningService.java"
click node_users "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/UserService.java"
click node_auth "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/security/AuthenticationContext.java"
click node_daos "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/dao/FeedEntryDAO.java"
click node_database "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/dao/UnitOfWork.java"
click node_opml "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/opml/OPMLImporter.java"
click node_scheduled "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/task/TaskScheduler.java"
click node_cleaning "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/db/DatabaseCleaningService.java"
click node_push "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/PushNotificationService.java"
click node_mail "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/MailService.java"
click node_customize "https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/servlet/CustomCssServlet.java"

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_reader,node_clientstate,node_clientapi,node_entrypages,node_sidebar,node_settingsui,node_user toneBlue
class node_rest,node_compatapi,node_websocket,node_customize toneAmber
class node_feedservice,node_refresh,node_fetchparse,node_entryservice,node_contentclean,node_opml toneMint
class node_users,node_auth,node_daos,node_database toneRose
class node_scheduled,node_cleaning,node_push,node_mail,node_publisher,node_pushservice,node_emailservice toneIndigo
```

## Components

### Reader client

- [Reader UI](https://github.com/athou/commafeed/blob/master/commafeed-client/src/App.tsx): `commafeed-client/src/App.tsx`
- [Client state](https://github.com/athou/commafeed/blob/master/commafeed-client/src/app/store.ts): `commafeed-client/src/app/store.ts`
- [HTTP client](https://github.com/athou/commafeed/blob/master/commafeed-client/src/app/client.ts): `commafeed-client/src/app/client.ts`
- [Reading pages](https://github.com/athou/commafeed/blob/master/commafeed-client/src/pages/app/FeedEntriesPage.tsx): `commafeed-client/src/pages/app/FeedEntriesPage.tsx`
- [Feed navigation](https://github.com/athou/commafeed/blob/master/commafeed-client/src/components/sidebar/Tree.tsx): `commafeed-client/src/components/sidebar/Tree.tsx`
- [Settings UI](https://github.com/athou/commafeed/blob/master/commafeed-client/src/pages/app/SettingsPage.tsx): `commafeed-client/src/pages/app/SettingsPage.tsx`

### Server interfaces

- [REST resources](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/resource/EntryREST.java): `commafeed-server/src/main/java/com/commafeed/frontend/resource/EntryREST.java`
- [Reader APIs](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/resource/fever/FeverREST.java): `commafeed-server/src/main/java/com/commafeed/frontend/resource/fever/FeverREST.java`
- [Live updates](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/ws/WebSocketEndpoint.java): `commafeed-server/src/main/java/com/commafeed/frontend/ws/WebSocketEndpoint.java`
- [Custom CSS JS](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/frontend/servlet/CustomCssServlet.java): `commafeed-server/src/main/java/com/commafeed/frontend/servlet/CustomCssServlet.java`

### Feed processing

- [Feed subscriptions](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/FeedService.java`
- [Refresh engine](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/feed/FeedRefreshEngine.java): `commafeed-server/src/main/java/com/commafeed/backend/feed/FeedRefreshEngine.java`
- [Fetch and parse](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/feed/FeedFetcher.java): `commafeed-server/src/main/java/com/commafeed/backend/feed/FeedFetcher.java`
- [Entry processing](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryService.java`
- [Content cleaning](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryContentCleaningService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/FeedEntryContentCleaningService.java`
- [OPML import export](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/opml/OPMLImporter.java): `commafeed-server/src/main/java/com/commafeed/backend/opml/OPMLImporter.java`

### Accounts and persistence

- [User service](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/UserService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/UserService.java`
- [Authentication](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/security/AuthenticationContext.java): `commafeed-server/src/main/java/com/commafeed/security/AuthenticationContext.java`
- [Data access](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/dao/FeedEntryDAO.java): `commafeed-server/src/main/java/com/commafeed/backend/dao/FeedEntryDAO.java`
- [Application database](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/dao/UnitOfWork.java): `commafeed-server/src/main/java/com/commafeed/backend/dao/UnitOfWork.java`

### Background and integrations

- [Scheduled cleanup](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/task/TaskScheduler.java): `commafeed-server/src/main/java/com/commafeed/backend/task/TaskScheduler.java`
- [Database cleanup](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/db/DatabaseCleaningService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/db/DatabaseCleaningService.java`
- [Push notifications](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/PushNotificationService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/PushNotificationService.java`
- [Email service](https://github.com/athou/commafeed/blob/master/commafeed-server/src/main/java/com/commafeed/backend/service/MailService.java): `commafeed-server/src/main/java/com/commafeed/backend/service/MailService.java`

### Other components

- **Reader user**
- **Feed publishers**
- **Push providers**
- **Mail provider**

## Connections

- Reader user → Reader UI: uses
- Reader UI → Client state: dispatches
- Reader UI → Reading pages: routes to
- Reader UI → Feed navigation: renders
- Reading pages → Client state: dispatches
- Feed navigation → Client state: reads
- Settings UI → Client state: dispatches
- Client state → HTTP client: requests
- HTTP client → REST resources: HTTP calls
- REST resources → Authentication: authenticates
- REST resources → Feed subscriptions: invokes
- REST resources → Entry processing: invokes
- REST resources → User service: invokes
- Reader APIs → Authentication: authenticates
- Reader APIs → Entry processing: invokes
- Feed subscriptions → Refresh engine: queues refresh
- Refresh engine → Fetch and parse: refreshes feeds
- Fetch and parse → Feed publishers: fetches feeds
- Fetch and parse → Entry processing: parsed entries
- Entry processing → Content cleaning: cleans content
- Feed subscriptions → Data access: reads writes
- Entry processing → Data access: reads writes
- User service → Data access: reads writes
- Data access → Application database: queries
- OPML import export → Feed subscriptions: imports subscriptions
- REST resources → OPML import export: imports exports
- Refresh engine → Live updates: notifies
- Live updates → Client state: pushes updates
- Refresh engine → Push notifications: sends notifications
- Push notifications → Push providers: posts notification
- User service → Email service: sends account mail
- Email service → Mail provider: sends mail
- Scheduled cleanup → Database cleanup: runs cleanup
- Database cleanup → Data access: deletes records
- Custom CSS JS → Reader UI: serves customization