# orangecoding/nanosearch architecture

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

- Interactive diagram: https://gitdiagram.com/orangecoding/nanosearch
- Repository: https://github.com/orangecoding/nanosearch

## Overview

nanosearch is a local-directory full-text search web app. Users create or update an index, which scans configured directories, detects additions, edits, moves and removals, extracts document text (including OCR where needed), and stores searchable content; they then search and view results in the browser. The graph includes search, indexing, progress, and document viewing capabilities documented by the README. Several route and viewer implementation details were not excerpted, so uncertain connections are omitted or marked unverified.

Main entry points: [`lib/frontend/src/App.jsx`](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/App.jsx) (Search application), [`lib/backend/src/indexer/pipeline.js`](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/pipeline.js) (Indexing pipeline), [`lib/backend/src/server.js`](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/server.js) (Fastify server), [`lib/backend/src/db/queries.js`](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/db/queries.js) (Database operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser interface"]
  node_app["Search application<br/>[App.jsx]"]
  node_searchui["Search controls<br/>[SearchBox.jsx]"]
  node_querybuilder["Query builder<br/>[QueryBuilder.jsx]"]
  node_results["Search results<br/>[ResultList.jsx]"]
  node_viewer["Document viewer<br/>[DocumentViewer.jsx]"]
  node_progressui["Index progress UI"]
  node_searchhook["Search requests<br/>[useSearch.js]"]
  node_ssehook["Progress events<br/>[useSSE.js]"]
end

subgraph group_api["HTTP API"]
  node_server["Fastify server<br/>[server.js]"]
  node_searchroute["Search endpoint<br/>[search.js]"]
  node_indexroute["Index endpoint<br/>[index.js]"]
  node_progressroute["Progress endpoint<br/>[progress.js]"]
  node_fileroute["File endpoint<br/>[file.js]"]
end

subgraph group_indexing["Indexing pipeline"]
  node_scanner["Directory scanner<br/>[scanner.js]"]
  node_diff["Change detection<br/>[diff.js]"]
  node_extractor["Text extraction<br/>[extractor.js]"]
  node_formats["Format extractors"]
  node_ocr["OCR backends"]
  node_pipeline["Indexing pipeline<br/>[pipeline.js]"]
  node_scheduler["Rescan scheduler<br/>[scheduler.js]"]
end

subgraph group_storage["Search storage"]
  node_database[("SQLite FTS index<br/>[schema.js]")]
  node_queries["Database operations<br/>[queries.js]"]
end

node_user(("Local user"))

node_user -->|"searches and manages"| node_app
node_app -->|"renders"| node_searchui
node_app -->|"renders"| node_results
node_app -->|"offers advanced queries"| node_querybuilder
node_app -->|"shows progress"| node_progressui
node_app -->|"uses"| node_searchhook
node_app -->|"uses"| node_ssehook
node_results -.->|"opens documents"| node_viewer
node_searchhook -->|"requests search"| node_searchroute
node_ssehook -->|"subscribes to events"| node_progressroute
node_server -->|"registers"| node_searchroute
node_server -->|"registers"| node_indexroute
node_server -->|"registers"| node_progressroute
node_server -->|"registers"| node_fileroute
node_server -->|"creates"| node_database
node_searchroute -->|"searches through"| node_queries
node_indexroute -.->|"starts indexing"| node_pipeline
node_progressroute -.->|"streams indexing updates"| node_pipeline
node_fileroute -->|"reads indexed file data"| node_queries
node_pipeline -->|"reads and updates metadata"| node_queries
node_pipeline -->|"scans directories"| node_scanner
node_pipeline -->|"classifies changes"| node_diff
node_pipeline -->|"extracts changed files"| node_extractor
node_extractor -->|"dispatches by format"| node_formats
node_extractor -.->|"uses for scanned files"| node_ocr
node_scheduler -->|"triggers rescans"| node_pipeline
node_queries -->|"reads and writes"| node_database

click node_app "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/App.jsx"
click node_searchui "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/SearchBox.jsx"
click node_querybuilder "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/QueryBuilder.jsx"
click node_results "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/ResultList.jsx"
click node_viewer "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/DocumentViewer.jsx"
click node_progressui "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/ProgressOverlay.jsx"
click node_searchhook "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/hooks/useSearch.js"
click node_ssehook "https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/hooks/useSSE.js"
click node_server "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/server.js"
click node_searchroute "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/search.js"
click node_indexroute "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/index.js"
click node_progressroute "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/progress.js"
click node_fileroute "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/file.js"
click node_scanner "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/scanner.js"
click node_diff "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/diff.js"
click node_extractor "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/extractor.js"
click node_formats "https://github.com/orangecoding/nanosearch/tree/master/lib/backend/src/indexer/extractors"
click node_ocr "https://github.com/orangecoding/nanosearch/tree/master/lib/backend/src/indexer/ocr"
click node_pipeline "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/pipeline.js"
click node_scheduler "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/scheduler.js"
click node_database "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/db/schema.js"
click node_queries "https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/db/queries.js"

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_app,node_searchui,node_querybuilder,node_results,node_viewer,node_progressui,node_searchhook,node_ssehook,node_user toneBlue
class node_server,node_searchroute,node_indexroute,node_progressroute,node_fileroute toneAmber
class node_scanner,node_diff,node_extractor,node_formats,node_ocr,node_pipeline,node_scheduler toneMint
class node_database,node_queries toneRose
```

## Components

### Browser interface

- [Search application](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/App.jsx): `lib/frontend/src/App.jsx`
- [Search controls](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/SearchBox.jsx): `lib/frontend/src/components/SearchBox.jsx`
- [Query builder](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/QueryBuilder.jsx): `lib/frontend/src/components/QueryBuilder.jsx`
- [Search results](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/ResultList.jsx): `lib/frontend/src/components/ResultList.jsx`
- [Document viewer](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/DocumentViewer.jsx): `lib/frontend/src/components/DocumentViewer.jsx`
- [Index progress UI](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/components/ProgressOverlay.jsx): `lib/frontend/src/components/ProgressOverlay.jsx`
- [Search requests](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/hooks/useSearch.js): `lib/frontend/src/hooks/useSearch.js`
- [Progress events](https://github.com/orangecoding/nanosearch/blob/master/lib/frontend/src/hooks/useSSE.js): `lib/frontend/src/hooks/useSSE.js`

### HTTP API

- [Fastify server](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/server.js): `lib/backend/src/server.js`
- [Search endpoint](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/search.js): `lib/backend/src/routes/search.js`
- [Index endpoint](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/index.js): `lib/backend/src/routes/index.js`
- [Progress endpoint](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/progress.js): `lib/backend/src/routes/progress.js`
- [File endpoint](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/routes/file.js): `lib/backend/src/routes/file.js`

### Indexing pipeline

- [Directory scanner](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/scanner.js): `lib/backend/src/indexer/scanner.js`
- [Change detection](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/diff.js): `lib/backend/src/indexer/diff.js`
- [Text extraction](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/extractor.js): `lib/backend/src/indexer/extractor.js`
- [Format extractors](https://github.com/orangecoding/nanosearch/tree/master/lib/backend/src/indexer/extractors): `lib/backend/src/indexer/extractors`
- [OCR backends](https://github.com/orangecoding/nanosearch/tree/master/lib/backend/src/indexer/ocr): `lib/backend/src/indexer/ocr`
- [Indexing pipeline](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/pipeline.js): `lib/backend/src/indexer/pipeline.js`
- [Rescan scheduler](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/indexer/scheduler.js): `lib/backend/src/indexer/scheduler.js`

### Search storage

- [SQLite FTS index](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/db/schema.js): `lib/backend/src/db/schema.js`
- [Database operations](https://github.com/orangecoding/nanosearch/blob/master/lib/backend/src/db/queries.js): `lib/backend/src/db/queries.js`

### Other components

- **Local user**

## Connections

- Local user → Search application: searches and manages
- Search application → Search controls: renders (evidence: `lib/frontend/src/App.jsx`)
- Search application → Search results: renders (evidence: `lib/frontend/src/App.jsx`)
- Search application → Query builder: offers advanced queries (evidence: `lib/frontend/src/App.jsx`)
- Search application → Index progress UI: shows progress (evidence: `lib/frontend/src/App.jsx`)
- Search application → Search requests: uses (evidence: `lib/frontend/src/App.jsx`)
- Search application → Progress events: uses (evidence: `lib/frontend/src/App.jsx`)
- Search results → Document viewer: opens documents
- Search requests → Search endpoint: requests search (evidence: `lib/frontend/src/hooks/useSearch.js`)
- Progress events → Progress endpoint: subscribes to events (evidence: `lib/frontend/src/hooks/useSSE.js`)
- Fastify server → Search endpoint: registers (evidence: `lib/backend/src/server.js`)
- Fastify server → Index endpoint: registers (evidence: `lib/backend/src/server.js`)
- Fastify server → Progress endpoint: registers (evidence: `lib/backend/src/server.js`)
- Fastify server → File endpoint: registers (evidence: `lib/backend/src/server.js`)
- Fastify server → SQLite FTS index: creates (evidence: `lib/backend/src/server.js`)
- Search endpoint → Database operations: searches through (evidence: `lib/backend/src/routes/search.js`)
- Index endpoint → Indexing pipeline: starts indexing
- Progress endpoint → Indexing pipeline: streams indexing updates
- File endpoint → Database operations: reads indexed file data (evidence: `lib/backend/src/routes/file.js`)
- Indexing pipeline → Database operations: reads and updates metadata (evidence: `lib/backend/src/indexer/pipeline.js`)
- Indexing pipeline → Directory scanner: scans directories (evidence: `lib/backend/src/indexer/pipeline.js`)
- Indexing pipeline → Change detection: classifies changes (evidence: `lib/backend/src/indexer/pipeline.js`)
- Indexing pipeline → Text extraction: extracts changed files (evidence: `lib/backend/src/indexer/pipeline.js`)
- Text extraction → Format extractors: dispatches by format (evidence: `lib/backend/src/indexer/extractor.js`)
- Text extraction → OCR backends: uses for scanned files
- Rescan scheduler → Indexing pipeline: triggers rescans (evidence: `lib/backend/src/indexer/scheduler.js`)
- Database operations → SQLite FTS index: reads and writes (evidence: `lib/backend/src/db/queries.js`)
