# rssnext/folo architecture

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

- Interactive diagram: https://gitdiagram.com/rssnext/folo
- Repository: https://github.com/rssnext/folo

## Overview

Folo is a cross-platform AI RSS reader: users follow diverse sources, read a unified timeline, and can use AI to ask about content, summarize, or translate it. Its product surfaces include desktop/web, mobile, and a CLI. The sampled code shows CLI command registration and client setup, renderer AI-chat support, mobile query persistence, and sync applying remote changes. README claims preserve broader product capabilities, but backend and much renderer/mobile runtime wiring were not sampled, so those links are documented rather than implementation-level.

Main entry points: [`packages/internal/store/src/sync/sync-engine.ts`](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/sync/sync-engine.ts) (Sync engine), [`apps/desktop/layer/renderer/src/App.tsx`](https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/App.tsx) (Desktop and web), [`apps/cli/src/commands`](https://github.com/rssnext/folo/tree/dev/apps/cli/src/commands) (CLI commands), [`apps/desktop/layer/renderer/src/modules/ai-chat`](https://github.com/rssnext/folo/tree/dev/apps/desktop/layer/renderer/src/modules/ai-chat) (AI chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_desktop["Desktop and web<br/>[App.tsx]"]
  node_mobile["Mobile app<br/>[main.tsx]"]
  node_cli["CLI program<br/>[program.ts]"]
  node_commands["CLI commands"]
  node_cli_client["CLI API client<br/>[client.ts]"]
  node_cli_output["CLI output<br/>[output.ts]"]
end

subgraph group_reading["Reading and feeds"]
  node_sources(("Followed sources"))
  node_timeline["Unified timeline<br/>[store.ts]"]
  node_subscriptions["Subscriptions<br/>[store.ts]"]
end

subgraph group_ai["AI assistance"]
  node_ai_chat["AI chat"]
  node_mention_search["AI context search"]
  node_ai_sessions["Chat sessions"]
  node_content["Summaries and translations<br/>[ai-summary.ts]"]
end

subgraph group_state["Sync and state"]
  node_sync["Sync engine<br/>[sync-engine.ts]"]
  node_entry_hooks["Entry updates<br/>[hooks.ts]"]
  node_unread["Unread state<br/>[store.ts]"]
end

node_reader(("Reader"))
node_api["Folo service"]

node_reader -->|"reads with"| node_desktop
node_reader -->|"reads with"| node_mobile
node_reader -->|"uses"| node_cli
node_sources -->|"follows"| node_subscriptions
node_subscriptions -.->|"organize reading"| node_timeline
node_desktop -.->|"reads timeline"| node_timeline
node_mobile -.->|"reads timeline"| node_timeline
node_cli -->|"registers"| node_commands
node_commands -->|"requests data"| node_cli_client
node_commands -->|"formats results"| node_cli_output
node_cli_client -.->|"calls API"| node_api
node_desktop -.->|"offers AI chat"| node_ai_chat
node_ai_chat -->|"searches context"| node_mention_search
node_ai_chat -->|"manages sessions"| node_ai_sessions
node_reader -.->|"uses"| node_content
node_sync -.->|"pulls changes"| node_api
node_sync -->|"refreshes entries"| node_entry_hooks
node_sync -->|"resets unread state"| node_unread

click node_desktop "https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/App.tsx"
click node_mobile "https://github.com/rssnext/folo/blob/dev/apps/mobile/src/main.tsx"
click node_cli "https://github.com/rssnext/folo/blob/dev/apps/cli/src/program.ts"
click node_commands "https://github.com/rssnext/folo/tree/dev/apps/cli/src/commands"
click node_cli_client "https://github.com/rssnext/folo/blob/dev/apps/cli/src/client.ts"
click node_cli_output "https://github.com/rssnext/folo/blob/dev/apps/cli/src/output.ts"
click node_timeline "https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/entry/store.ts"
click node_subscriptions "https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/subscription/store.ts"
click node_sync "https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/sync/sync-engine.ts"
click node_entry_hooks "https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/entry/hooks.ts"
click node_unread "https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/unread/store.ts"
click node_ai_chat "https://github.com/rssnext/folo/tree/dev/apps/desktop/layer/renderer/src/modules/ai-chat"
click node_mention_search "https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/modules/ai-chat/editor/plugins/mention/hooks/useMentionSearchService.ts"
click node_ai_sessions "https://github.com/rssnext/folo/tree/dev/apps/desktop/layer/renderer/src/modules/ai-chat-session"
click node_content "https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/atoms/ai-summary.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_desktop,node_mobile,node_cli,node_commands,node_cli_client,node_cli_output toneBlue
class node_sources,node_timeline,node_subscriptions toneAmber
class node_ai_chat,node_mention_search,node_ai_sessions,node_content toneMint
class node_sync,node_entry_hooks,node_unread toneRose
class node_reader,node_api toneIndigo
```

## Components

### User surfaces

- [Desktop and web](https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/App.tsx): `apps/desktop/layer/renderer/src/App.tsx`
- [Mobile app](https://github.com/rssnext/folo/blob/dev/apps/mobile/src/main.tsx): `apps/mobile/src/main.tsx`
- [CLI program](https://github.com/rssnext/folo/blob/dev/apps/cli/src/program.ts): `apps/cli/src/program.ts`
- [CLI commands](https://github.com/rssnext/folo/tree/dev/apps/cli/src/commands): `apps/cli/src/commands`
- [CLI API client](https://github.com/rssnext/folo/blob/dev/apps/cli/src/client.ts): `apps/cli/src/client.ts`
- [CLI output](https://github.com/rssnext/folo/blob/dev/apps/cli/src/output.ts): `apps/cli/src/output.ts`

### Reading and feeds

- **Followed sources**
- [Unified timeline](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/entry/store.ts): `packages/internal/store/src/modules/entry/store.ts`
- [Subscriptions](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/subscription/store.ts): `packages/internal/store/src/modules/subscription/store.ts`

### AI assistance

- [AI chat](https://github.com/rssnext/folo/tree/dev/apps/desktop/layer/renderer/src/modules/ai-chat): `apps/desktop/layer/renderer/src/modules/ai-chat`
- [AI context search](https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/modules/ai-chat/editor/plugins/mention/hooks/useMentionSearchService.ts): `apps/desktop/layer/renderer/src/modules/ai-chat/editor/plugins/mention/hooks/useMentionSearchService.ts`
- [Chat sessions](https://github.com/rssnext/folo/tree/dev/apps/desktop/layer/renderer/src/modules/ai-chat-session): `apps/desktop/layer/renderer/src/modules/ai-chat-session`
- [Summaries and translations](https://github.com/rssnext/folo/blob/dev/apps/desktop/layer/renderer/src/atoms/ai-summary.ts): `apps/desktop/layer/renderer/src/atoms/ai-summary.ts`

### Sync and state

- [Sync engine](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/sync/sync-engine.ts): `packages/internal/store/src/sync/sync-engine.ts`
- [Entry updates](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/entry/hooks.ts): `packages/internal/store/src/modules/entry/hooks.ts`
- [Unread state](https://github.com/rssnext/folo/blob/dev/packages/internal/store/src/modules/unread/store.ts): `packages/internal/store/src/modules/unread/store.ts`

### Other components

- **Reader**
- **Folo service**

## Connections

- Reader → Desktop and web: reads with
- Reader → Mobile app: reads with
- Reader → CLI program: uses
- Followed sources → Subscriptions: follows
- Subscriptions → Unified timeline: organize reading
- Desktop and web → Unified timeline: reads timeline
- Mobile app → Unified timeline: reads timeline
- CLI program → CLI commands: registers (evidence: `apps/cli/src/program.ts`)
- CLI commands → CLI API client: requests data (evidence: `apps/cli/src/commands/subscription.ts`)
- CLI commands → CLI output: formats results (evidence: `apps/cli/src/commands/subscription.ts`)
- CLI API client → Folo service: calls API
- Desktop and web → AI chat: offers AI chat
- AI chat → AI context search: searches context (evidence: `apps/desktop/layer/renderer/src/modules/ai-chat/editor/plugins/mention/hooks/useMentionSearchService.ts`)
- AI chat → Chat sessions: manages sessions (evidence: `apps/desktop/layer/renderer/src/modules/ai-chat/components/layouts/shared/useChatSessionHandlers.tsx`)
- Reader → Summaries and translations: uses
- Sync engine → Folo service: pulls changes
- Sync engine → Entry updates: refreshes entries (evidence: `packages/internal/store/src/sync/sync-engine.ts`)
- Sync engine → Unread state: resets unread state (evidence: `packages/internal/store/src/sync/sync-engine.ts`)
