# Navigation & Redirect Logic

This document describes the setup flow navigation, covering how users progress from initial setup through to the main application.

## Overview

The application uses a middleware-based redirect system to ensure users complete setup before accessing the main app. The flow involves multiple pages handling setup completion, unresolved folder detection, and initialization.

## Setup Flow

```
┌─────────────────────────────────────────────────────────────────────┐
│                         SETUP FLOW                                   │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   /setup ──► /loading ──► /setup/unresolved ──► /loading ──► /login │
│        │         │              │                  │                │
│        │         │              │                  │                │
│        ▼         ▼              ▼                  ▼                │
│   (first    (Series Scan +  (has folders)     (all resolved)        │
│    time)     NFO Scan)         │                                     │
│                      │        │                                     │
│                      │        │                                     │
│                      │        ▼                                     │
│                      │    [Done button] ──► marks complete         │
│                      │        │                                     │
│                      │        ▼                                     │
│                      │    /loading (NFO phase runs again)           │
│                      │        │                                     │
│                      └────────┴─────────────────────────────────────┘
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘
```

**New Navigation Order:**
1. `/setup` → Initial configuration
2. `/loading` → Series scan + NFO scan
3. `/setup/unresolved` → Resolve folders (if any)
4. `/loading` → NFO scan runs again
5. `/login` → Authentication

**Key Changes:**
- After `/setup/unresolved`, the "Done" button marks the phase as complete
- Revisiting `/setup/unresolved` after completion → redirects to `/loading`
- `/loading` always goes to `/setup/unresolved` if unresolved folders exist
- NFO scan runs as a separate phase after series sync during initialization

## Middleware: SetupRedirectMiddleware

**File:** `src/server/middleware/setup_redirect.py`

The middleware intercepts all requests and redirects to `/setup` if:
- No master password is configured
- Configuration file is missing or invalid

### Exempt Paths (always accessible)

| Path | Purpose |
|------|---------|
| `/setup` | Initial setup page |
| `/setup/unresolved` | Unresolved folder resolution |
| `/loading` | Initialization progress page |
| `/login` | Authentication |
| `/api/auth/*` | Auth endpoints |
| `/api/config/*` | Config API |
| `/api/health` | Health check |
| `/static/*` | Static assets |

### Middleware Logic

1. **Setup incomplete** → Redirect to `/setup`
2. **Setup complete, accessing `/setup`** → Redirect to `/login`
3. **Setup complete, accessing `/loading`** → Allow access (page handles its own redirect)
4. **Setup complete, accessing `/setup/unresolved`**:
   - If `unresolved_completed` flag is set → Redirect to `/loading`
   - Otherwise → Allow access
5. **API requests during setup** → Return 503 with `setup_url`

## Pages

### 1. Setup Page (`/setup`)

**File:** `src/server/web/templates/setup.html`

Handles initial configuration:
- Master password creation
- Anime directory selection
- Database initialization

**Post-completion flow:**
- Redirects to `/loading` to begin initialization

### 2. Loading Page (`/loading`)

**File:** `src/server/web/templates/loading.html`

Shows initialization progress via WebSocket:
- Series scanning
- Database population
- Logo/image loading

**Post-initialization flow:**
```javascript
async function checkUnresolvedAndProceed() {
    // Fetch unresolved folders via API
    const res = await fetch('/api/setup/unresolved', {
        headers: { 'Authorization': `Bearer ${token}` }
    });
    const folders = await res.json();
    
    if (folders.length > 0) {
        // Has unresolved folders → go to resolution page
        window.location.href = '/setup/unresolved';
    } else {
        // No unresolved folders → go to login
        window.location.href = '/login';
    }
}
```

### 3. Unresolved Folders Page (`/setup/unresolved`)

**File:** `src/server/web/templates/unresolved.html`

Allows manual resolution of folders that couldn't be auto-matched:
- Shows list of unresolved folders
- Provides search suggestions
- Input field for entering provider key
- Resolve/delete actions
- **Done button** at top to complete the phase without resolving all folders

**Post-resolution flow:**
```javascript
// After clicking "Done" button
async function handleDone() {
    // Call API to mark phase as complete
    await fetch('/api/setup/unresolved/done', { method: 'POST' });
    // Redirect to loading for final NFO scan
    window.location.href = '/loading';
}
```

**Done button behavior:**
- Marks all remaining folders as handled
- Sets `unresolved_completed` flag in config
- Redirects to `/loading` to run final NFO scan
- After completion, `/setup/unresolved` becomes inaccessible (redirects to `/loading`)

### 4. Login Page (`/login`)

**File:** `src/server/web/templates/login.html`

Authentication page. After successful login → redirect to `/` (main app).

## API Endpoints

### Unresolved Folders API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/setup/unresolved` | List all unresolved folders |
| `GET` | `/api/setup/unresolved/{folder_name}` | Get specific folder details |
| `POST` | `/api/setup/unresolved/{folder_name}/resolve` | Resolve with provider key |
| `POST` | `/api/setup/unresolved/{folder_name}/search` | Re-search for matches |
| `DELETE` | `/api/setup/unresolved/{folder_name}` | Remove folder from tracking |
| `POST` | `/api/setup/unresolved/done` | Mark unresolved phase as complete |

### Auth API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/auth/setup` | Create master password |
| `POST` | `/api/auth/login` | Authenticate |
| `POST` | `/api/auth/logout` | End session |

## Key Files

| File | Purpose |
|------|---------|
| `src/server/middleware/setup_redirect.py` | Redirect middleware |
| `src/server/controllers/page_controller.py` | Page route handlers |
| `src/server/web/templates/setup.html` | Setup template |
| `src/server/web/templates/loading.html` | Loading template |
| `src/server/web/templates/unresolved.html` | Unresolved folders template |
| `src/server/api/setup_endpoints.py` | Unresolved folders API |
| `src/server/database/service.py` | UnresolvedFolderService |

## Common Issues

### Redirect Loop

**Symptom:** Browser keeps redirecting between pages.

**Causes:**
1. `loading.html` always redirected to `/setup/unresolved` without checking if any exist
2. `unresolved.html` redirected to `/` which middleware redirected back to `/login`

**Fix:** See the navigation logic updates in loading.html and unresolved.html.

### Can't Access Unresolved Page After Setup

**Symptom:** Middleware redirects to `/login` instead of allowing access to `/setup/unresolved`.

**Cause:** `/setup/unresolved` is in the exempt paths but the request may not be reaching it due to completion check timing.

**Fix:** The middleware allows access to `/loading` which handles the redirect to `/setup/unresolved` after initialization.