# omnivore-app/omnivore architecture

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

- Interactive diagram: https://gitdiagram.com/omnivore-app/omnivore
- Repository: https://github.com/omnivore-app/omnivore

## Overview

Omnivore is a self-hosted read-it-later product with web, Android, and Apple clients. A typical workflow is to share or add a URL, fetch and parse its content, save it to a library, then read, search, label, highlight, or listen to it; clients synchronize through the API. The repository also includes newsletter ingestion, RSS discovery, PDF reading, and text-to-speech. Several client and service subsystems are represented by paths from the tree rather than inspected implementation excerpts, so only documented or indexed connections are drawn.

Main entry points: [`packages/api/src/server.ts`](https://github.com/omnivore-app/omnivore/blob/main/packages/api/src/server.ts) (API server), [`apple/OmnivoreKit/Sources/App`](https://github.com/omnivore-app/omnivore/tree/main/apple/OmnivoreKit/Sources/App) (Apple app), [`packages/web`](https://github.com/omnivore-app/omnivore/tree/main/packages/web) (Web app), [`packages/content-fetch/src/request_handler.ts`](https://github.com/omnivore-app/omnivore/blob/main/packages/content-fetch/src/request_handler.ts) (Content fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Reading clients"]
  node_web["Web app"]
  node_android["Android app"]
  node_apple["Apple app"]
end

subgraph group_capture["Capture and discovery"]
  node_share["Share extension"]
  node_fetch["Content fetch<br/>[request_handler.ts]"]
  node_parser["Page parser<br/>[index.ts]"]
  node_handler["Content handlers<br/>[content-handler.ts]"]
  node_rss["RSS discovery<br/>[rssIngestor.ts]"]
  node_email["Newsletter email<br/>[index.ts]"]
end

subgraph group_services["API services"]
  node_api["API server<br/>[server.ts]"]
  node_auth["Authentication<br/>[auth_router.ts]"]
  node_graphql["GraphQL API"]
end

subgraph group_content["Reading features"]
  node_reader["Article reader"]
  node_search["Search and library"]
  node_highlights["Highlights and labels"]
  node_audio["Text to speech"]
  node_pdf["PDF reading<br/>[PDFViewer.swift]"]
end

subgraph group_state["Persistence and sync"]
  node_androiddata["Android data service<br/>[DataService.kt]"]
  node_localdb[("Android local database")]
  node_appledata["Apple data service<br/>[DataService.swift]"]
  node_postgres[("PostgreSQL")]
end

node_user(("Reader"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_android
node_user -->|"uses"| node_apple
node_user -->|"shares content"| node_share
node_web -->|"queries"| node_graphql
node_api -->|"routes auth"| node_auth
node_androiddata -->|"uses database"| node_localdb
node_androiddata -.->|"calls networker"| node_api
node_apple -->|"uses services"| node_appledata
node_appledata -.->|"syncs remotely"| node_api
node_share -->|"saves page"| node_appledata
node_fetch -->|"requests parsing"| node_parser
node_email -.->|"submits content"| node_fetch
node_rss -.->|"adds discoveries"| node_api
node_handler -.->|"handles content"| node_fetch
node_api -->|"persists records"| node_postgres
node_web -->|"fetches library"| node_search
node_android -.->|"opens saved items"| node_reader
node_reader -.->|"creates annotations"| node_highlights
node_apple -->|"plays speech"| node_audio
node_apple -->|"opens PDFs"| node_pdf

click node_web "https://github.com/omnivore-app/omnivore/tree/main/packages/web"
click node_android "https://github.com/omnivore-app/omnivore/tree/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore"
click node_apple "https://github.com/omnivore-app/omnivore/tree/main/apple/OmnivoreKit/Sources/App"
click node_share "https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/App/AppExtensions/Share/ShareExtensionViewModel.swift"
click node_fetch "https://github.com/omnivore-app/omnivore/blob/main/packages/content-fetch/src/request_handler.ts"
click node_parser "https://github.com/omnivore-app/omnivore/blob/main/packages/puppeteer-parse/src/index.ts"
click node_handler "https://github.com/omnivore-app/omnivore/blob/main/packages/content-handler/src/content-handler.ts"
click node_rss "https://github.com/omnivore-app/omnivore/blob/main/packages/discover/src/lib/inputSources/articles/rss/rssIngestor.ts"
click node_email "https://github.com/omnivore-app/omnivore/blob/main/packages/local-mail-watcher/src/index.ts"
click node_api "https://github.com/omnivore-app/omnivore/blob/main/packages/api/src/server.ts"
click node_auth "https://github.com/omnivore-app/omnivore/blob/main/packages/api/src/routers/auth/auth_router.ts"
click node_graphql "https://github.com/omnivore-app/omnivore/tree/main/packages/api/src"
click node_reader "https://github.com/omnivore-app/omnivore/tree/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/feature/reader"
click node_search "https://github.com/omnivore-app/omnivore/blob/main/packages/web/lib/networking/library_items/useLibraryItems.tsx"
click node_highlights "https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/HighlightActionHandlers.kt"
click node_audio "https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/Services/AudioSession/AudioController.swift"
click node_pdf "https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/App/PDFSupport/PDFViewer.swift"
click node_androiddata "https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/DataService.kt"
click node_localdb "https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/database/OmnivoreDatabase.kt"
click node_appledata "https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/Services/DataService/DataService.swift"

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_web,node_android,node_apple toneBlue
class node_share,node_fetch,node_parser,node_handler,node_rss,node_email toneAmber
class node_api,node_auth,node_graphql toneMint
class node_reader,node_search,node_highlights,node_audio,node_pdf toneRose
class node_androiddata,node_localdb,node_appledata,node_postgres,node_user toneIndigo
```

## Components

### Reading clients

- [Web app](https://github.com/omnivore-app/omnivore/tree/main/packages/web): `packages/web`
- [Android app](https://github.com/omnivore-app/omnivore/tree/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore): `android/Omnivore/app/src/main/java/app/omnivore/omnivore`
- [Apple app](https://github.com/omnivore-app/omnivore/tree/main/apple/OmnivoreKit/Sources/App): `apple/OmnivoreKit/Sources/App`

### Capture and discovery

- [Share extension](https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/App/AppExtensions/Share/ShareExtensionViewModel.swift): `apple/OmnivoreKit/Sources/App/AppExtensions/Share/ShareExtensionViewModel.swift`
- [Content fetch](https://github.com/omnivore-app/omnivore/blob/main/packages/content-fetch/src/request_handler.ts): `packages/content-fetch/src/request_handler.ts`
- [Page parser](https://github.com/omnivore-app/omnivore/blob/main/packages/puppeteer-parse/src/index.ts): `packages/puppeteer-parse/src/index.ts`
- [Content handlers](https://github.com/omnivore-app/omnivore/blob/main/packages/content-handler/src/content-handler.ts): `packages/content-handler/src/content-handler.ts`
- [RSS discovery](https://github.com/omnivore-app/omnivore/blob/main/packages/discover/src/lib/inputSources/articles/rss/rssIngestor.ts): `packages/discover/src/lib/inputSources/articles/rss/rssIngestor.ts`
- [Newsletter email](https://github.com/omnivore-app/omnivore/blob/main/packages/local-mail-watcher/src/index.ts): `packages/local-mail-watcher/src/index.ts`

### API services

- [API server](https://github.com/omnivore-app/omnivore/blob/main/packages/api/src/server.ts): `packages/api/src/server.ts`
- [Authentication](https://github.com/omnivore-app/omnivore/blob/main/packages/api/src/routers/auth/auth_router.ts): `packages/api/src/routers/auth/auth_router.ts`
- [GraphQL API](https://github.com/omnivore-app/omnivore/tree/main/packages/api/src): `packages/api/src`

### Reading features

- [Article reader](https://github.com/omnivore-app/omnivore/tree/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/feature/reader): `android/Omnivore/app/src/main/java/app/omnivore/omnivore/feature/reader`
- [Search and library](https://github.com/omnivore-app/omnivore/blob/main/packages/web/lib/networking/library_items/useLibraryItems.tsx): `packages/web/lib/networking/library_items/useLibraryItems.tsx`
- [Highlights and labels](https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/HighlightActionHandlers.kt): `android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/HighlightActionHandlers.kt`
- [Text to speech](https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/Services/AudioSession/AudioController.swift): `apple/OmnivoreKit/Sources/Services/AudioSession/AudioController.swift`
- [PDF reading](https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/App/PDFSupport/PDFViewer.swift): `apple/OmnivoreKit/Sources/App/PDFSupport/PDFViewer.swift`

### Persistence and sync

- [Android data service](https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/DataService.kt): `android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/DataService.kt`
- [Android local database](https://github.com/omnivore-app/omnivore/blob/main/android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/database/OmnivoreDatabase.kt): `android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/database/OmnivoreDatabase.kt`
- [Apple data service](https://github.com/omnivore-app/omnivore/blob/main/apple/OmnivoreKit/Sources/Services/DataService/DataService.swift): `apple/OmnivoreKit/Sources/Services/DataService/DataService.swift`
- **PostgreSQL**

### Other components

- **Reader**

## Connections

- Reader → Web app: uses (evidence: `README.md`)
- Reader → Android app: uses (evidence: `README.md`)
- Reader → Apple app: uses (evidence: `README.md`)
- Reader → Share extension: shares content (evidence: `README.md`)
- Web app → GraphQL API: queries (evidence: `packages/web/lib/networking/networkHelpers.ts`)
- API server → Authentication: routes auth (evidence: `packages/api/src/server.ts`)
- Android data service → Android local database: uses database (evidence: `android/Omnivore/app/src/main/java/app/omnivore/omnivore/core/data/DataService.kt`)
- Android data service → API server: calls networker
- Apple app → Apple data service: uses services (evidence: `apple/OmnivoreKit/Sources/App/Services.swift`)
- Apple data service → API server: syncs remotely
- Share extension → Apple data service: saves page (evidence: `apple/OmnivoreKit/Sources/App/AppExtensions/Share/ShareExtensionViewModel.swift`)
- Content fetch → Page parser: requests parsing (evidence: `packages/content-fetch/src/request_handler.ts`)
- Newsletter email → Content fetch: submits content
- RSS discovery → API server: adds discoveries
- Content handlers → Content fetch: handles content
- API server → PostgreSQL: persists records (evidence: `README.md`)
- Web app → Search and library: fetches library (evidence: `packages/web/lib/networking/queries/useGetArticleQuery.tsx`)
- Android app → Article reader: opens saved items
- Article reader → Highlights and labels: creates annotations
- Apple app → Text to speech: plays speech (evidence: `apple/OmnivoreKit/Sources/App/Services.swift`)
- Apple app → PDF reading: opens PDFs (evidence: `README.md`)
