# samsar/curio architecture

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

- Interactive diagram: https://gitdiagram.com/samsar/curio
- Repository: https://github.com/samsar/curio

## Overview

Curio is a local bookmark archive with hybrid search and an MCP interface for AI agents. The main workflow imports saved links, queues background fetching and indexing, then exposes the resulting library through CLI, dashboard, and MCP search. Separate branches cover topic discovery and related reading, along with setup and daemon management. Some subsystem links are documented or visible in wiring excerpts; unsampled implementation details are not inferred, so uncertain dispatch is shown as unverified.

Main entry points: [`internal/jobs/handlers.go`](https://github.com/samsar/curio/blob/main/internal/jobs/handlers.go) (Fetch and index handlers), [`internal/api/server.go`](https://github.com/samsar/curio/blob/main/internal/api/server.go) (HTTP API), [`internal/store/sqlite/db.go`](https://github.com/samsar/curio/blob/main/internal/store/sqlite/db.go) (Library store), [`internal/setup/import.go`](https://github.com/samsar/curio/blob/main/internal/setup/import.go) (Setup and import)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Import and indexing"]
  node_setup["Setup and import<br/>[import.go]"]
  node_bookmark_sources["Bookmark sources<br/>[source.go]"]
  node_handlers["Fetch and index handlers<br/>[handlers.go]"]
  node_fetcher["Page fetching<br/>[native.go]"]
  node_indexer["Document indexing<br/>[indexer.go]"]
end

subgraph group_runtime["Daemon and storage"]
  node_queue["Job queue<br/>[jobs.go]"]
  node_worker["Job workers<br/>[worker.go]"]
  node_database[("Library store<br/>[db.go]")]
  node_daemon["Daemon lifecycle<br/>[lifecycle.go]"]
  node_service["Background service<br/>[service.go]"]
end

subgraph group_access["Search and interfaces"]
  node_api["HTTP API<br/>[server.go]"]
  node_search_api["Search endpoint<br/>[search.go]"]
  node_search_engine["Hybrid search<br/>[search.go]"]
  node_cli["CLI commands<br/>[search.go]"]
  node_mcp["MCP tools<br/>[main.go]"]
  node_client["Local API client<br/>[client.go]"]
  node_dashboard["Web dashboard<br/>[pages.go]"]
end

subgraph group_insights["Library insights"]
  node_insights["Interest discovery<br/>[engine.go]"]
  node_ollama["Local model service<br/>[client.go]"]
end

node_reader(("Reader"))
node_agent(("AI agent"))

node_reader -->|"imports links"| node_setup
node_setup -->|"reads bookmarks"| node_bookmark_sources
node_setup -->|"submits import"| node_api
node_reader -->|"searches library"| node_cli
node_cli -->|"ensures running"| node_daemon
node_cli -->|"requests search"| node_client
node_client -.->|"calls local API"| node_api
node_api -->|"routes requests"| node_search_api
node_search_api -->|"runs search"| node_search_engine
node_search_engine -->|"reads library"| node_database
node_api -.->|"enqueues work"| node_queue
node_worker -->|"claims jobs"| node_queue
node_worker -.->|"dispatches jobs"| node_handlers
node_handlers -->|"fetches pages"| node_fetcher
node_handlers -->|"indexes documents"| node_indexer
node_handlers -->|"writes metadata"| node_database
node_fetcher -.->|"reads document"| node_database
node_agent -->|"asks questions"| node_mcp
node_mcp -->|"requests tools"| node_client
node_mcp -->|"searches bookmarks"| node_search_api
node_reader -->|"views library"| node_dashboard
node_reader -->|"explores interests"| node_insights
node_insights -->|"stores clusters"| node_database
node_insights -.->|"labels topics"| node_ollama
node_daemon -->|"manages service"| node_service

click node_setup "https://github.com/samsar/curio/blob/main/internal/setup/import.go"
click node_bookmark_sources "https://github.com/samsar/curio/blob/main/internal/importer/source.go"
click node_api "https://github.com/samsar/curio/blob/main/internal/api/server.go"
click node_queue "https://github.com/samsar/curio/blob/main/internal/store/sqlite/jobs.go"
click node_worker "https://github.com/samsar/curio/blob/main/internal/jobs/worker.go"
click node_handlers "https://github.com/samsar/curio/blob/main/internal/jobs/handlers.go"
click node_fetcher "https://github.com/samsar/curio/blob/main/internal/fetcher/native.go"
click node_indexer "https://github.com/samsar/curio/blob/main/internal/indexer/indexer.go"
click node_database "https://github.com/samsar/curio/blob/main/internal/store/sqlite/db.go"
click node_search_api "https://github.com/samsar/curio/blob/main/internal/api/search.go"
click node_search_engine "https://github.com/samsar/curio/blob/main/internal/search/search.go"
click node_cli "https://github.com/samsar/curio/blob/main/internal/cli/search.go"
click node_mcp "https://github.com/samsar/curio/blob/main/cmd/curio-mcp/main.go"
click node_client "https://github.com/samsar/curio/blob/main/internal/client/client.go"
click node_dashboard "https://github.com/samsar/curio/blob/main/internal/ui/pages.go"
click node_insights "https://github.com/samsar/curio/blob/main/internal/insight/engine.go"
click node_ollama "https://github.com/samsar/curio/blob/main/internal/ollama/client.go"
click node_daemon "https://github.com/samsar/curio/blob/main/internal/daemonctl/lifecycle.go"
click node_service "https://github.com/samsar/curio/blob/main/internal/service/service.go"

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_setup,node_bookmark_sources,node_handlers,node_fetcher,node_indexer toneBlue
class node_queue,node_worker,node_database,node_daemon,node_service toneAmber
class node_api,node_search_api,node_search_engine,node_cli,node_mcp,node_client,node_dashboard toneMint
class node_insights,node_ollama toneRose
class node_reader,node_agent toneIndigo
```

## Components

### Import and indexing

- [Setup and import](https://github.com/samsar/curio/blob/main/internal/setup/import.go): `internal/setup/import.go`
- [Bookmark sources](https://github.com/samsar/curio/blob/main/internal/importer/source.go): `internal/importer/source.go`
- [Fetch and index handlers](https://github.com/samsar/curio/blob/main/internal/jobs/handlers.go): `internal/jobs/handlers.go`
- [Page fetching](https://github.com/samsar/curio/blob/main/internal/fetcher/native.go): `internal/fetcher/native.go`
- [Document indexing](https://github.com/samsar/curio/blob/main/internal/indexer/indexer.go): `internal/indexer/indexer.go`

### Daemon and storage

- [Job queue](https://github.com/samsar/curio/blob/main/internal/store/sqlite/jobs.go): `internal/store/sqlite/jobs.go`
- [Job workers](https://github.com/samsar/curio/blob/main/internal/jobs/worker.go): `internal/jobs/worker.go`
- [Library store](https://github.com/samsar/curio/blob/main/internal/store/sqlite/db.go): `internal/store/sqlite/db.go`
- [Daemon lifecycle](https://github.com/samsar/curio/blob/main/internal/daemonctl/lifecycle.go): `internal/daemonctl/lifecycle.go`
- [Background service](https://github.com/samsar/curio/blob/main/internal/service/service.go): `internal/service/service.go`

### Search and interfaces

- [HTTP API](https://github.com/samsar/curio/blob/main/internal/api/server.go): `internal/api/server.go`
- [Search endpoint](https://github.com/samsar/curio/blob/main/internal/api/search.go): `internal/api/search.go`
- [Hybrid search](https://github.com/samsar/curio/blob/main/internal/search/search.go): `internal/search/search.go`
- [CLI commands](https://github.com/samsar/curio/blob/main/internal/cli/search.go): `internal/cli/search.go`
- [MCP tools](https://github.com/samsar/curio/blob/main/cmd/curio-mcp/main.go): `cmd/curio-mcp/main.go`
- [Local API client](https://github.com/samsar/curio/blob/main/internal/client/client.go): `internal/client/client.go`
- [Web dashboard](https://github.com/samsar/curio/blob/main/internal/ui/pages.go): `internal/ui/pages.go`

### Library insights

- [Interest discovery](https://github.com/samsar/curio/blob/main/internal/insight/engine.go): `internal/insight/engine.go`
- [Local model service](https://github.com/samsar/curio/blob/main/internal/ollama/client.go): `internal/ollama/client.go`

### Other components

- **Reader**
- **AI agent**

## Connections

- Reader → Setup and import: imports links (evidence: `README.md`)
- Setup and import → Bookmark sources: reads bookmarks (evidence: `internal/setup/import.go`)
- Setup and import → HTTP API: submits import (evidence: `internal/setup/import.go`)
- Reader → CLI commands: searches library (evidence: `README.md`)
- CLI commands → Daemon lifecycle: ensures running (evidence: `internal/cli/search.go`)
- CLI commands → Local API client: requests search (evidence: `internal/cli/search.go`)
- Local API client → HTTP API: calls local API
- HTTP API → Search endpoint: routes requests (evidence: `internal/api/server.go`)
- Search endpoint → Hybrid search: runs search (evidence: `internal/api/search.go`)
- Hybrid search → Library store: reads library (evidence: `internal/search/search.go`)
- HTTP API → Job queue: enqueues work
- Job workers → Job queue: claims jobs (evidence: `internal/jobs/worker.go`)
- Job workers → Fetch and index handlers: dispatches jobs
- Fetch and index handlers → Page fetching: fetches pages (evidence: `internal/jobs/handlers.go`)
- Fetch and index handlers → Document indexing: indexes documents (evidence: `internal/jobs/handlers.go`)
- Fetch and index handlers → Library store: writes metadata (evidence: `internal/jobs/handlers.go`)
- Page fetching → Library store: reads document
- AI agent → MCP tools: asks questions (evidence: `README.md`)
- MCP tools → Local API client: requests tools (evidence: `cmd/curio-mcp/main.go`)
- MCP tools → Search endpoint: searches bookmarks (evidence: `cmd/curio-mcp/main.go`)
- Reader → Web dashboard: views library (evidence: `README.md`)
- Reader → Interest discovery: explores interests (evidence: `README.md`)
- Interest discovery → Library store: stores clusters (evidence: `internal/insight/engine.go`)
- Interest discovery → Local model service: labels topics
- Daemon lifecycle → Background service: manages service (evidence: `internal/daemonctl/lifecycle.go`)
