backend/README.md

# backend

Long-running HTTP server that owns the searcher processes (and therefore the
loaded model weights). The UI and the CLI both talk to it — models are loaded
once and reused.

## Run

```bash
# from repo root, using the indexing venv
indexing/.env/bin/python backend/server.py            # default 127.0.0.1:8000
indexing/.env/bin/python backend/server.py --port 8042
```

Make sure the indexes exist first:

```bash
cd indexing && python index.py /path/to/folder
```

## Routes

| route                                | what                                                |
| ------------------------------------ | --------------------------------------------------- |
| `GET /`                              | serves `ui/static/index.html`                       |
| `GET /static/<file>`                 | UI assets                                           |
| `GET /api/modalities`                | `{modalities: [...], groups: {...}}`                |
| `GET /api/search/<modality>?q=&k=`   | per-modality search → `{modality, kind, query, hits:[{score,path}]}` |
| `GET /api/file?path=`                | serve an indexed file (with stale-path healing)     |

Clients fan out across `/api/search/<modality>` themselves — the UI does this
with `Promise.all` so columns render as soon as their modality returns.

## Path healing

The `/api/file` endpoint accepts the absolute path stored in
`indexing/index_data/*_meta.json`. If that file has since been moved, the
server falls back to a basename lookup against `indexing/` and the repo root,
so re-indexing isn't required just to view stale-path results.