# Connected Papers (Local)

A lightweight, self-hosted web app for exploring academic paper reference graphs. Search for a paper and see an interactive graph of the papers it cites. Dot size is proportional to citation count.

## Features

- Search by paper title, DOI, or arXiv ID
- Interactive force-directed graph (vis-network)
- Node size based on citation count
- Click a node to see details; double-click to re-center the graph
- File-based JSON cache (survives container restarts)
- Works offline for previously cached graphs
- Uses OpenAlex for all paper data
- Shows only outgoing references (papers the seed paper cites)
- Dockerized and ready to plug into your existing Caddy reverse proxy

## Data Source

- **OpenAlex API:** https://openalex.org/

OpenAlex is free. Anonymous usage has rate limits; if you hit them often, get a free API key and set it in a `.env` file (see below).

## Quick Start

```bash
cd /root/connected-papers

# Build and run
docker-compose up -d --build

# Open locally
# http://127.0.0.1:5000
```

## Caddy Integration

Add a new site block to `/root/caddy/Caddyfile` (adjust the subdomain to your preference):

```caddy
papers.ahlgrim.bzh {
    reverse_proxy connected-papers:5000
}
```

Then reload Caddy:

```bash
cd /root/caddy
docker-compose exec caddy caddy reload --config /etc/caddy/Caddyfile
```

The container is already attached to the `caddy_mesh` Docker network, so Caddy can reach it by the service name `connected-papers`.

## Configuration

Edit `docker-compose.yml` to tune these environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `CACHE_TTL_DAYS` | 30 | Days before cached graph is refreshed |
| `SEARCH_LIMIT` | 20 | Number of search results, sorted by citation count |
| `REFERENCE_LIMIT` | 100 | Top N papers cited by the seed paper (outgoing) |
| `OA_API_KEY` | (none) | OpenAlex API key (higher rate limits) |
| `OA_EMAIL` | (none) | Email for OpenAlex polite pool (recommended) |

### Getting an API key (optional but recommended)

- **OpenAlex:** https://openalex.org/rest-api

Copy `.env.example` to `.env`, add your key, and restart:

```bash
cp .env.example .env
# edit .env with your OA_API_KEY and OA_EMAIL
docker-compose up -d
```

## Cache

Cached graphs are stored as JSON files in `./cache/`. To clear the cache:

```bash
rm -f cache/*.json
```

You can also inspect the cache files directly — they are plain JSON.

## Troubleshooting

### 429 / "Too Many Requests" or 503 from OpenAlex

The public IP you are running from has hit OpenAlex's rate limit. Set `OA_API_KEY` and `OA_EMAIL` for higher limits.

### Offline mode

If the APIs are unreachable but a cached graph exists, the app returns the cached graph automatically.

## Useful Commands

```bash
# View logs
docker-compose logs -f

# Restart
docker-compose restart

# Stop
docker-compose down

# Rebuild after code changes
docker-compose up -d --build
```