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 backend 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
HOST=0.0.0.0  # Use 127.0.0.1 for localhost only

# Optional: External APIs for country data
TMDB_API_KEY=your_tmdb_api_key  # Get from https://www.themoviedb.org/settings/api
```

3. (Optional) Set up frontend environment variables (create `.env.local` in `frontend/`):
```bash
# Only needed if backend port/host differs from defaults
VITE_BACKEND_HOST=127.0.0.1
VITE_BACKEND_PORT=8080
VITE_PORT=5173
```

5. Start the backend (in one terminal):
```bash
cd backend
# Uses HOST and PORT from .env file (defaults to 0.0.0.0:8080)
python -m uvicorn main:app --reload --host ${HOST:-0.0.0.0} --port ${PORT:-8080}
```

6. Start the frontend dev server (in another terminal):
```bash
cd frontend
npm install
# Optional: Set backend URL if different from default
# export VITE_BACKEND_HOST=127.0.0.1
# export VITE_BACKEND_PORT=8080
npm run dev
```

7. Open http://localhost:5173 in your browser (or http://<your-server-ip>:5173 from another computer)

### Development vs Production

**Development Mode:**
- Backend runs on port 8080 (configurable)
- Frontend dev server runs on port 5173 (configurable)
- Frontend proxies API requests to backend
- Both are accessible from other computers (bound to 0.0.0.0)

**Production Mode (NixOS deployment):**
- Backend runs on configured port (default 8080)
- Frontend is built and served as static files by the backend
- No separate frontend server needed
- Access via backend URL only

**Note**: The frontend dev server runs on port 5173 by default and proxies API requests to the backend. If you changed the backend port, set `VITE_BACKEND_PORT` environment variable to match. The frontend dev server binds to `0.0.0.0` by default, so it's accessible from other computers.

## 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;
    host = "0.0.0.0";  # Bind to all interfaces (use "127.0.0.1" for localhost only)
    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://0.0.0.0:8080` (or your server's IP address). If you set `host = "127.0.0.1"`, it will only be accessible from localhost (use a reverse proxy in that case).

**Note**: If you're accessing from another computer, make sure:
1. The service is bound to `0.0.0.0` (default) or your server's IP address
2. Your firewall allows incoming connections on the configured port
3. If using NixOS, you may need to open the port in your firewall configuration:
   ```nix
   networking.firewall.allowedTCPPorts = [ 8080 ];
   ```

## 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)
- `GET /admin/missing-countries?source_kind=sonarr&media_type=show&limit=100` - List items without country metadata
- `POST /admin/assign-country?item_id=<uuid>&country_code=US` - Manually assign country to an item

## 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 using multiple methods:

### Automatic Extraction

- **Radarr (Movies)**: 
  - First tries `productionCountries` from Radarr metadata
  - Falls back to TMDB API (requires `TMDB_API_KEY` env var) using `tmdbId`
  
- **Sonarr (TV Shows)**: 
  - First tries `seriesMetadata.originCountry` from Sonarr metadata
  - Falls back to TMDB API (requires `TMDB_API_KEY` env var) using `tmdbId`
  
- **Lidarr (Music)**: 
  - First tries `country` field from Lidarr metadata
  - Falls back to MusicBrainz API (no API key required) using `foreignArtistId` (MBID)

### External API Setup

**TMDB API (for Movies & TV Shows):**
1. Get a free API key from https://www.themoviedb.org/settings/api
2. Set environment variable: `TMDB_API_KEY=your_api_key_here`
3. Re-run sync to fetch country data

**MusicBrainz API (for Music):**
- No API key required (uses public API)
- Automatically used if `foreignArtistId` (MusicBrainz ID) is available in Lidarr

### Manual Assignment

If automatic extraction fails, you can manually assign countries:

1. **View missing countries:**
   ```bash
   curl http://127.0.0.1:8888/admin/missing-countries?source_kind=sonarr&limit=50
   ```

2. **Assign country manually:**
   ```bash
   curl -X POST "http://127.0.0.1:8888/admin/assign-country?item_id=<uuid>&country_code=US"
   ```

Items without country information are stored but excluded from map visualization until a country is assigned.

## Implementation Status

### ✅ Completed Features

- ✅ Project scaffolding (FastAPI backend + React frontend)
- ✅ Database schema and migrations (PostgreSQL)
- ✅ *arr sync integration (Radarr, Sonarr, Lidarr)
- ✅ Collection Map UI (View 1) with filters
- ✅ Watched Map UI (View 2) with manual tracking
- ✅ NixOS module and systemd deployment
- ✅ TMDB API integration for movies and TV shows
- ✅ MusicBrainz API integration for music
- ✅ Manual country assignment feature
- ✅ Missing metadata admin view

### 🔄 Future Enhancements (Optional)

- Batch country assignment UI
- Country extraction from file paths/metadata
- Export/import functionality
- Statistics and analytics
- Multi-user support

## License

MIT