# karakeep-app/karakeep architecture

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

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

## Overview

Karakeep is a self-hostable bookmark manager: users save links, notes, images, and PDFs, then organize, search, read, and revisit them across web, mobile, browser, and agent-oriented clients. The documented product also includes crawling and archival, AI tagging and summaries, semantic search, RSS, rules, highlights, imports, collaboration, and offline mobile reading. The graph shows these major capabilities while keeping asynchronous processing distinct. Some backend modules and storage implementations are not present in the supplied tree or excerpts, so uncertain internal connections are omitted.

Main entry points: [`apps/web/app/api/[[...route]]/route.ts`](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/api/%5B%5B...route%5D%5D/route.ts) (API and tRPC), [`apps/mobile/app`](https://github.com/karakeep-app/karakeep/tree/main/apps/mobile/app) (Mobile app), [`apps/workers/workers/crawler/assetStorage.ts`](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/crawler/assetStorage.ts) (Crawling and archival), [`apps/workers/workers/inference/inferenceWorker.ts`](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/inference/inferenceWorker.ts) (AI tagging and summaries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web["Web app"]
  node_mobile["Mobile app"]
  node_extension["Browser extension"]
  node_cli["CLI"]
  node_mcp["MCP tools"]
end

subgraph group_product["Bookmark experience"]
  node_bookmark["Bookmark views<br/>[page.tsx]"]
  node_reader["Reader and highlights<br/>[page.tsx]"]
  node_search["Full-text and semantic search<br/>[page.tsx]"]
end

subgraph group_processing["Background processing"]
  node_crawler["Crawling and archival<br/>[assetStorage.ts]"]
  node_inference["AI tagging and summaries<br/>[inferenceWorker.ts]"]
  node_embeddings["Embedding indexing"]
  node_ruleworker["Rule execution"]
end

subgraph group_management["Organization and access"]
  node_lists["Lists and sharing<br/>[page.tsx]"]
  node_tags["Tags and favorites<br/>[page.tsx]"]
  node_feeds["RSS feeds<br/>[page.tsx]"]
  node_rules["Rule configuration"]
  node_imports["Import sessions"]
  node_ruleengine["Rule engine<br/>[ruleEngine.ts]"]
end

subgraph group_services["Data and integrations"]
  node_api["API and tRPC<br/>[route.ts]"]
  node_database[("Application database")]
  node_queue["Job queues"]
  node_vectorstore[("Vector search store")]
  node_inferenceprovider["Inference provider"]
  node_searchservice["Meilisearch"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_user -->|"uses"| node_mobile
node_user -->|"saves with"| node_extension
node_user -->|"uses"| node_cli
node_user -.->|"asks agents"| node_mcp
node_web -->|"requests"| node_api
node_mobile -->|"requests"| node_api
node_extension -->|"saves bookmarks"| node_api
node_cli -->|"commands"| node_api
node_mcp -.->|"invokes tools"| node_api
node_api -->|"reads and writes"| node_database
node_api -->|"enqueues work"| node_queue
node_bookmark -->|"loads and updates"| node_api
node_reader -->|"loads content"| node_api
node_search -->|"queries"| node_api
node_lists -->|"manages lists"| node_api
node_tags -->|"manages tags"| node_api
node_feeds -->|"configures feeds"| node_api
node_rules -->|"saves rules"| node_api
node_imports -->|"stages imports"| node_database
node_queue -->|"dispatches jobs"| node_crawler
node_queue -->|"dispatches jobs"| node_inference
node_queue -->|"dispatches jobs"| node_embeddings
node_queue -->|"dispatches jobs"| node_ruleworker
node_crawler -->|"stores crawl data"| node_database
node_crawler -->|"enqueues follow-up"| node_queue
node_inference -->|"reads and updates"| node_database
node_inference -.->|"requests inference"| node_inferenceprovider
node_embeddings -->|"loads bookmark data"| node_database
node_embeddings -.->|"writes vectors"| node_vectorstore
node_ruleworker -->|"runs rules"| node_ruleengine
node_ruleengine -->|"reads and updates"| node_database
node_ruleengine -->|"queues archival"| node_queue
node_search -.->|"searches content"| node_searchservice
node_mobile -->|"reads offline"| node_reader

click node_web "https://github.com/karakeep-app/karakeep/tree/main/apps/web/app"
click node_mobile "https://github.com/karakeep-app/karakeep/tree/main/apps/mobile/app"
click node_extension "https://github.com/karakeep-app/karakeep/tree/main/apps/browser-extension/src"
click node_cli "https://github.com/karakeep-app/karakeep/tree/main/apps/cli/src"
click node_mcp "https://github.com/karakeep-app/karakeep/tree/main/apps/mcp/src"
click node_api "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/api/%5B%5B...route%5D%5D/route.ts"
click node_bookmark "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/bookmarks/page.tsx"
click node_reader "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/reader/%5BbookmarkId%5D/page.tsx"
click node_search "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/search/page.tsx"
click node_lists "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/lists/page.tsx"
click node_tags "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/tags/page.tsx"
click node_feeds "https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/settings/feeds/page.tsx"
click node_rules "https://github.com/karakeep-app/karakeep/blob/main/apps/web/components/dashboard/rules/RuleEngineRuleEditor.tsx"
click node_imports "https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/models/importSessions.service.ts"
click node_crawler "https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/crawler/assetStorage.ts"
click node_inference "https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/inference/inferenceWorker.ts"
click node_embeddings "https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/embeddingsWorker.ts"
click node_ruleworker "https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/ruleEngineWorker.ts"
click node_ruleengine "https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/lib/ruleEngine.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_web,node_mobile,node_extension,node_cli,node_mcp,node_user toneBlue
class node_bookmark,node_reader,node_search toneAmber
class node_crawler,node_inference,node_embeddings,node_ruleworker toneMint
class node_lists,node_tags,node_feeds,node_rules,node_imports,node_ruleengine toneRose
class node_api,node_database,node_queue,node_vectorstore,node_inferenceprovider,node_searchservice toneIndigo
```

## Components

### User clients

- [Web app](https://github.com/karakeep-app/karakeep/tree/main/apps/web/app): `apps/web/app`
- [Mobile app](https://github.com/karakeep-app/karakeep/tree/main/apps/mobile/app): `apps/mobile/app`
- [Browser extension](https://github.com/karakeep-app/karakeep/tree/main/apps/browser-extension/src): `apps/browser-extension/src`
- [CLI](https://github.com/karakeep-app/karakeep/tree/main/apps/cli/src): `apps/cli/src`
- [MCP tools](https://github.com/karakeep-app/karakeep/tree/main/apps/mcp/src): `apps/mcp/src`

### Bookmark experience

- [Bookmark views](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/bookmarks/page.tsx): `apps/web/app/dashboard/bookmarks/page.tsx`
- [Reader and highlights](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/reader/%5BbookmarkId%5D/page.tsx): `apps/web/app/reader/[bookmarkId]/page.tsx`
- [Full-text and semantic search](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/search/page.tsx): `apps/web/app/dashboard/search/page.tsx`

### Background processing

- [Crawling and archival](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/crawler/assetStorage.ts): `apps/workers/workers/crawler/assetStorage.ts`
- [AI tagging and summaries](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/inference/inferenceWorker.ts): `apps/workers/workers/inference/inferenceWorker.ts`
- [Embedding indexing](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/embeddingsWorker.ts): `apps/workers/workers/embeddingsWorker.ts`
- [Rule execution](https://github.com/karakeep-app/karakeep/blob/main/apps/workers/workers/ruleEngineWorker.ts): `apps/workers/workers/ruleEngineWorker.ts`

### Organization and access

- [Lists and sharing](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/lists/page.tsx): `apps/web/app/dashboard/lists/page.tsx`
- [Tags and favorites](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/dashboard/tags/page.tsx): `apps/web/app/dashboard/tags/page.tsx`
- [RSS feeds](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/settings/feeds/page.tsx): `apps/web/app/settings/feeds/page.tsx`
- [Rule configuration](https://github.com/karakeep-app/karakeep/blob/main/apps/web/components/dashboard/rules/RuleEngineRuleEditor.tsx): `apps/web/components/dashboard/rules/RuleEngineRuleEditor.tsx`
- [Import sessions](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/models/importSessions.service.ts): `packages/trpc/models/importSessions.service.ts`
- [Rule engine](https://github.com/karakeep-app/karakeep/blob/main/packages/trpc/lib/ruleEngine.ts): `packages/trpc/lib/ruleEngine.ts`

### Data and integrations

- [API and tRPC](https://github.com/karakeep-app/karakeep/blob/main/apps/web/app/api/%5B%5B...route%5D%5D/route.ts): `apps/web/app/api/[[...route]]/route.ts`
- **Application database**
- **Job queues**
- **Vector search store**
- **Inference provider**
- **Meilisearch**

### Other components

- **User**

## Connections

- User → Web app: uses
- User → Mobile app: uses
- User → Browser extension: saves with
- User → CLI: uses
- User → MCP tools: asks agents
- Web app → API and tRPC: requests
- Mobile app → API and tRPC: requests
- Browser extension → API and tRPC: saves bookmarks
- CLI → API and tRPC: commands
- MCP tools → API and tRPC: invokes tools
- API and tRPC → Application database: reads and writes
- API and tRPC → Job queues: enqueues work
- Bookmark views → API and tRPC: loads and updates
- Reader and highlights → API and tRPC: loads content
- Full-text and semantic search → API and tRPC: queries
- Lists and sharing → API and tRPC: manages lists
- Tags and favorites → API and tRPC: manages tags
- RSS feeds → API and tRPC: configures feeds
- Rule configuration → API and tRPC: saves rules
- Import sessions → Application database: stages imports
- Job queues → Crawling and archival: dispatches jobs
- Job queues → AI tagging and summaries: dispatches jobs
- Job queues → Embedding indexing: dispatches jobs
- Job queues → Rule execution: dispatches jobs
- Crawling and archival → Application database: stores crawl data
- Crawling and archival → Job queues: enqueues follow-up
- AI tagging and summaries → Application database: reads and updates
- AI tagging and summaries → Inference provider: requests inference
- Embedding indexing → Application database: loads bookmark data
- Embedding indexing → Vector search store: writes vectors
- Rule execution → Rule engine: runs rules
- Rule engine → Application database: reads and updates
- Rule engine → Job queues: queues archival
- Full-text and semantic search → Meilisearch: searches content
- Mobile app → Reader and highlights: reads offline
