media-map/README.md

# Movie Map

A web application that visualizes the origin countries of your media collection from Radarr, Sonarr, and Lidarr, and tracks which foreign movies/shows you've watched.

## Features

### View 1: Collection Map
- Visualizes all media in your *arr instances on a world map
- Shows country of origin for each movie/show/artist
- Color intensity indicates number of items per country
- Filter by media type (movies, shows, music)
- Pin markers show counts per country

### View 2: Watched Map
- Interactive map to track watched foreign movies and TV shows
- Manually add watched items with country information
- Add custom pins to mark countries
- Visualize your personal "watched foreign media" journey

## Architecture

- **Backend**: FastAPI (Python) with PostgreSQL
- **Frontend**: React + TypeScript + Vite + Leaflet
- **Database**: PostgreSQL (via Unix socket)
- **Deployment**: Nix flake with NixOS module

## Development Setup

### Prerequisites

- Nix with flakes enabled
- PostgreSQL running (accessible via socket)
- Access to Radarr, Sonarr, Lidarr instances

### Getting Started

1. Enter the development shell:
```bash
nix develop
```

2. Set up environment variables (create `.env` in `backend/`):
```bash
POSTGRES_SOCKET_PATH=/run/postgresql
POSTGRES_DB=jawz
POSTGRES_USER=jawz
SONARR_API_KEY=your_sonarr_api_key
RADARR_API_KEY=your_radarr_api_key
LIDARR_API_KEY=your_lidarr_api_key
PORT=8080
```

3. Run database migrations:
```bash
cd backend
alembic upgrade head
```

4. Start the backend (in one terminal):
```bash
cd backend
python -m uvicorn main:app --reload --host 127.0.0.1 --port 8080
```

5. Start the frontend dev server (in another terminal):
```bash
cd frontend
npm install
npm run dev
```

6. Open http://localhost:5173 in your browser

## Building

Build the application using Nix:

```bash
nix build
```

This creates a combined package with both backend and frontend.

## NixOS Deployment

### 1. Add the flake to your NixOS configuration

In your `configuration.nix` or a separate module:

```nix
{
  imports = [
    /path/to/movie-map/nixosModules.default
  ];

  services.moviemap = {
    enable = true;
    port = 8080;
    postgresSocketPath = "/run/postgresql";
    # Secrets can be strings or file paths (for sops-nix integration)
    sonarrApiKey = "/run/secrets/sonarr-api-key";  # or "your_key_here"
    radarrApiKey = "/run/secrets/radarr-api-key";   # or "your_key_here"
    lidarrApiKey = "/run/secrets/lidarr-api-key";  # or "your_key_here"
    # Optional: admin token for sync endpoint
    adminToken = "/run/secrets/moviemap-admin-token";  # or "your_token_here"
  };
}
```

Or reference the flake directly:

```nix
{
  imports = [
    (builtins.getFlake "/path/to/movie-map").nixosModules.default
  ];
  
  services.moviemap = {
    enable = true;
    # ... configuration
  };
}
```

### 2. Run database migrations

Before starting the service, run migrations. You can do this either:

**Option A: Run migrations manually before enabling the service**

```bash
# SSH into your server
ssh server

# Enter the flake shell
cd /path/to/movie-map
nix develop

# Run migrations
cd backend
alembic upgrade head
```

**Option B: Add a systemd service to run migrations on first start**

You can add a one-shot systemd service that runs migrations before the main service starts. Add this to your NixOS configuration:

```nix
systemd.services.moviemap-migrate = {
  description = "Movie Map Database Migrations";
  serviceConfig = {
    Type = "oneshot";
    User = "moviemap";
    WorkingDirectory = "${appPackage}/backend";
    ExecStart = "${pythonEnv}/bin/alembic upgrade head";
  };
  before = [ "moviemap-backend.service" ];
  requiredBy = [ "moviemap-backend.service" ];
};
```

Or simply run migrations once manually, then enable the service.

### 3. Rebuild and enable

```bash
sudo nixos-rebuild switch
```

The service will be available at `http://127.0.0.1:8080` (configure your reverse proxy to expose it).

## API Endpoints

### Collection
- `GET /api/collection/summary?types=movie,show,music` - Get collection summary by country

### Watched Items
- `GET /api/watched` - List all watched items
- `GET /api/watched/summary` - Get watched summary by country
- `POST /api/watched` - Create watched item
- `PATCH /api/watched/{id}` - Update watched item
- `DELETE /api/watched/{id}` - Delete watched item

### Pins
- `GET /api/pins` - List all manual pins
- `POST /api/pins` - Create pin
- `DELETE /api/pins/{id}` - Delete pin

### Admin
- `POST /admin/sync` - Trigger sync from all *arr instances (requires admin token if configured)

## Database Schema

The application creates a `moviemap` schema in the `jawz` database with the following tables:

- `source` - *arr instance configuration
- `media_item` - Normalized media items from *arr
- `media_country` - Country associations for media items
- `watched_item` - User-tracked watched items
- `manual_pin` - Custom pins on the map

## Country Extraction

The sync process extracts country information from *arr metadata:

- **Radarr**: Uses `productionCountries` from movie metadata
- **Sonarr**: Uses `originCountry` from series metadata (if available)
- **Lidarr**: Uses `country` field from artist metadata

If country information is not available, the item is stored without a country association (excluded from map visualization).

## License

MIT