Aniworld/Docs/NAVIGATION.md

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:

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:

// 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.