# ludalunizz/the-researcher architecture

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

- Interactive diagram: https://gitdiagram.com/ludalunizz/the-researcher
- Repository: https://github.com/ludalunizz/the-researcher

## Overview

The Researcher is a local research loader for Claude Code and opencode. Its main workflow discovers documents, expands configured or custom sets, presents a selective chooser, converts selected material to cached plain text, and loads only the checked items. Separate capabilities cover prior-chat context, source-code profiles, saved UI choices, and anonymous opt-in usage reporting. The excerpts establish the CLI’s library setup and worker validation path; some runtime wiring is supported only by README descriptions, so uncertain internal calls are omitted.

Main entry points: [`src/main.rs`](https://github.com/ludalunizz/the-researcher/blob/main/src/main.rs) (CLI Orchestrator), [`src/popup.rs`](https://github.com/ludalunizz/the-researcher/blob/main/src/popup.rs) (Selection Popup), [`src/sessions.rs`](https://github.com/ludalunizz/the-researcher/blob/main/src/sessions.rs) (Chat Sessions), [`worker/src/index.js`](https://github.com/ludalunizz/the-researcher/blob/main/worker/src/index.js) (Usage Receiver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Selection"]
  node_cli["CLI Orchestrator<br/>[main.rs]"]
  node_chooser["Selection Popup<br/>[popup.rs]"]
  node_saved[("Saved Choices<br/>[state.rs]")]
  node_time["Time Grouping<br/>[bands.rs]"]
end

subgraph group_research["Research Library"]
  node_library["Library Scanner<br/>[library.rs]"]
  node_text[("Text Cache<br/>[text.rs]")]
  node_documents["Research Files"]
end

subgraph group_context["Context and Profiles"]
  node_sessions["Chat Sessions<br/>[sessions.rs]"]
  node_code["Code Profiles<br/>[code.rs]"]
end

subgraph group_telemetry["Usage Reporting"]
  node_usage[("Usage Log and Reports<br/>[usage.rs]")]
  node_worker["Usage Receiver<br/>[index.js]"]
  node_validator["Payload Validator<br/>[validate.js]"]
  node_d1[("Usage Database<br/>[schema.sql]")]
end

node_user(("User"))
node_claude(("Claude Session"))
node_opencode(("opencode"))

node_user -->|"starts load"| node_cli
node_cli -->|"scans library"| node_library
node_cli -->|"opens chooser"| node_chooser
node_chooser -.->|"saves choices"| node_saved
node_chooser -->|"groups chats"| node_time
node_library -->|"reads files"| node_documents
node_cli -->|"prepares text"| node_text
node_text -->|"converts selected"| node_documents
node_cli -->|"loads selection"| node_claude
node_cli -.->|"loads context"| node_sessions
node_sessions -->|"reads chat history"| node_claude
node_sessions -->|"exports sessions"| node_opencode
node_cli -.->|"scans profiles"| node_code
node_cli -->|"records loads"| node_usage
node_usage -->|"sends opt-in records"| node_worker
node_worker -->|"validates payload"| node_validator
node_worker -->|"stores records"| node_d1

click node_cli "https://github.com/ludalunizz/the-researcher/blob/main/src/main.rs"
click node_chooser "https://github.com/ludalunizz/the-researcher/blob/main/src/popup.rs"
click node_saved "https://github.com/ludalunizz/the-researcher/blob/main/src/state.rs"
click node_time "https://github.com/ludalunizz/the-researcher/blob/main/src/bands.rs"
click node_library "https://github.com/ludalunizz/the-researcher/blob/main/src/library.rs"
click node_text "https://github.com/ludalunizz/the-researcher/blob/main/src/text.rs"
click node_sessions "https://github.com/ludalunizz/the-researcher/blob/main/src/sessions.rs"
click node_code "https://github.com/ludalunizz/the-researcher/blob/main/src/code.rs"
click node_usage "https://github.com/ludalunizz/the-researcher/blob/main/src/usage.rs"
click node_worker "https://github.com/ludalunizz/the-researcher/blob/main/worker/src/index.js"
click node_validator "https://github.com/ludalunizz/the-researcher/blob/main/worker/src/validate.js"
click node_d1 "https://github.com/ludalunizz/the-researcher/blob/main/worker/schema.sql"

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_cli,node_chooser,node_saved,node_time,node_user toneBlue
class node_library,node_text,node_documents toneAmber
class node_sessions,node_code toneMint
class node_usage,node_worker,node_validator,node_d1 toneRose
class node_claude,node_opencode toneIndigo
```

## Components

### CLI and Selection

- [CLI Orchestrator](https://github.com/ludalunizz/the-researcher/blob/main/src/main.rs): `src/main.rs`
- [Selection Popup](https://github.com/ludalunizz/the-researcher/blob/main/src/popup.rs): `src/popup.rs`
- [Saved Choices](https://github.com/ludalunizz/the-researcher/blob/main/src/state.rs): `src/state.rs`
- [Time Grouping](https://github.com/ludalunizz/the-researcher/blob/main/src/bands.rs): `src/bands.rs`

### Research Library

- [Library Scanner](https://github.com/ludalunizz/the-researcher/blob/main/src/library.rs): `src/library.rs`
- [Text Cache](https://github.com/ludalunizz/the-researcher/blob/main/src/text.rs): `src/text.rs`
- **Research Files**

### Context and Profiles

- [Chat Sessions](https://github.com/ludalunizz/the-researcher/blob/main/src/sessions.rs): `src/sessions.rs`
- [Code Profiles](https://github.com/ludalunizz/the-researcher/blob/main/src/code.rs): `src/code.rs`

### Usage Reporting

- [Usage Log and Reports](https://github.com/ludalunizz/the-researcher/blob/main/src/usage.rs): `src/usage.rs`
- [Usage Receiver](https://github.com/ludalunizz/the-researcher/blob/main/worker/src/index.js): `worker/src/index.js`
- [Payload Validator](https://github.com/ludalunizz/the-researcher/blob/main/worker/src/validate.js): `worker/src/validate.js`
- [Usage Database](https://github.com/ludalunizz/the-researcher/blob/main/worker/schema.sql): `worker/schema.sql`

### Other components

- **User**
- **Claude Session**
- **opencode**

## Connections

- User → CLI Orchestrator: starts load (evidence: `README.md`)
- CLI Orchestrator → Library Scanner: scans library (evidence: `src/main.rs`)
- CLI Orchestrator → Selection Popup: opens chooser (evidence: `README.md`)
- Selection Popup → Saved Choices: saves choices
- Selection Popup → Time Grouping: groups chats (evidence: `src/popup.rs`)
- Library Scanner → Research Files: reads files (evidence: `src/library.rs`)
- CLI Orchestrator → Text Cache: prepares text (evidence: `README.md`)
- Text Cache → Research Files: converts selected (evidence: `README.md`)
- CLI Orchestrator → Claude Session: loads selection (evidence: `README.md`)
- CLI Orchestrator → Chat Sessions: loads context (evidence: `src/main.rs`)
- Chat Sessions → Claude Session: reads chat history (evidence: `README.md`)
- Chat Sessions → opencode: exports sessions (evidence: `src/sessions.rs`)
- CLI Orchestrator → Code Profiles: scans profiles (evidence: `src/main.rs`)
- CLI Orchestrator → Usage Log and Reports: records loads (evidence: `README.md`)
- Usage Log and Reports → Usage Receiver: sends opt-in records (evidence: `README.md`)
- Usage Receiver → Payload Validator: validates payload (evidence: `worker/src/index.js`)
- Usage Receiver → Usage Database: stores records (evidence: `worker/src/index.js`)
