chore: bump version

- loading.html: check for unresolved folders before redirecting, go to /login if none
- unresolved.html: redirect to /loading instead of / after skip/timeout
- add docs/NAVIGATION.md navigation flow documentation

Docker/VERSION

@@ -1 +1 @@
-v1.4.7
+v1.4.9

docs/NAVIGATION.md

@@ -0,0 +1,174 @@
+# 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         │
+│        │                │           │                    │          │
+│        │                │           │                    │          │
+│        ▼                ▼           ▼                    ▼          │
+│   (first time)    (WebSocket)    (has folders)      (all resolved)  │
+│                         │                    │                      │
+│                         ▼                    │                      │
+│                   /login ◄───────────────────┴──────────────────────┤
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## 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 `/loading`
+3. **Setup complete, accessing `/loading`** → Allow access (page handles its own redirect)
+4. **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
+
+**Post-resolution flow:**
+```javascript
+function checkEmptyList() {
+    if (listEl.children.length === 0) {
+        // All folders resolved → return to loading
+        setTimeout(() => { window.location.href = '/loading'; }, 2000);
+    }
+}
+```
+
+### 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 |
+
+### 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.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "aniworld-web",
-  "version": "1.4.7",
+  "version": "1.4.9",
   "description": "Aniworld Anime Download Manager - Web Frontend",
   "type": "module",
   "scripts": {

src/server/api/auth.py

@@ -147,10 +147,7 @@ async def setup_auth(req: SetupRequest):
         # Trigger initialization in background task
         import asyncio
 
-        from src.server.services.initialization_service import (
+        from src.server.services.initialization_service import perform_initial_setup
-            perform_initial_setup,
-            perform_nfo_scan_if_needed,
-        )
         from src.server.services.progress_service import get_progress_service
         
         progress_service = get_progress_service()
@@ -161,9 +158,6 @@ async def setup_auth(req: SetupRequest):
                 # Perform the initial series sync and mark as completed
                 await perform_initial_setup(progress_service)
                 
-                # Perform NFO scan if configured
-                await perform_nfo_scan_if_needed(progress_service)
-                
                 # Start scheduler if anime_directory is now set
                 try:
                     from src.server.services.scheduler.scheduler_service import (

src/server/fastapi_app.py

@@ -344,7 +344,6 @@ async def lifespan(_application: FastAPI):
         from src.server.services.initialization_service import (
             perform_initial_setup,
             perform_media_scan_if_needed,
-            perform_nfo_scan_if_needed,
         )
         
         try:
@@ -373,9 +372,6 @@ async def lifespan(_application: FastAPI):
                         "exist yet): %s", e
                     )
 
-                # Run NFO scan only on first run (if configured)
-                await perform_nfo_scan_if_needed()
-
                 # Initialize download service
                 try:
                     from src.server.utils.dependencies import get_download_service

src/server/middleware/setup_redirect.py

@@ -127,21 +127,10 @@ class SetupRedirectMiddleware(BaseHTTPMiddleware):
                     # Otherwise redirect to login
                     return RedirectResponse(url="/login", status_code=302)
                 elif path == "/loading":
-                    # Check if initialization is complete
+                    # Always allow access to loading page - it handles its own
-                    try:
+                    # redirect flow via WebSocket events (initialization_complete
-                        from src.server.database.connection import get_db_session
+                    # event triggers redirect to /setup/unresolved)
-                        from src.server.database.system_settings_service import (
+                    pass
-                            SystemSettingsService,
-                        )
-                        
-                        async with get_db_session() as db:
-                            is_complete = await SystemSettingsService.is_initial_scan_completed(db)
-                            if is_complete:
-                                # Initialization complete, redirect to login
-                                return RedirectResponse(url="/login", status_code=302)
-                    except Exception:
-                        # If we can't check, allow access to loading page
-                        pass
         
         # Skip setup check for exempt paths
         if self._is_path_exempt(path):

src/server/web/templates/loading.html

@@ -281,15 +281,11 @@
         let isComplete = false;
 
         const stepOrder = [
-            'series_sync',
+            'series_sync'
-            'nfo_scan',
-            'media_scan'
         ];
 
         const stepTitles = {
-            'series_sync': 'Syncing Series Database',
+            'series_sync': 'Syncing Series Database'
-            'nfo_scan': 'Processing NFO Metadata',
-            'media_scan': 'Scanning Media Files'
         };
 
         function connectWebSocket() {
@@ -479,44 +475,26 @@
         }
 
         async function checkUnresolvedAndProceed() {
+            // Fetch unresolved folders and only redirect if there are any
+            // Otherwise go directly to login
             try {
                 const token = localStorage.getItem('auth_token');
-                console.log('Checking unresolved folders, token exists:', !!token);
-                if (!token) {
-                    // No token, go to login
-                    console.log('No auth token found, showing completion');
-                    document.getElementById('completionMessage').style.display = 'block';
-                    return;
-                }
-                
                 const res = await fetch('/api/setup/unresolved', {
                     headers: { 'Authorization': `Bearer ${token}` }
                 });
-                console.log('Unresolved API response status:', res.status);
-                
                 if (res.ok) {
-                    const unresolved = await res.json();
+                    const folders = await res.json();
-                    console.log('Unresolved folders:', unresolved);
+                    if (folders && folders.length > 0) {
-                    if (unresolved && unresolved.length > 0) {
+                        // Has unresolved folders - go to resolution page
-                        // Has unresolved folders - redirect to unresolved page
-                        console.log('Redirecting to /setup/unresolved');
                         window.location.href = '/setup/unresolved';
                         return;
                     }
-                } else if (res.status === 401) {
-                    // Token invalid, clear it
-                    localStorage.removeItem('auth_token');
-                    console.log('Token invalid, showing completion');
-                    document.getElementById('completionMessage').style.display = 'block';
-                    return;
                 }
-            } catch (e) {
+            } catch (err) {
-                console.error('Error checking unresolved folders:', e);
+                console.error('Failed to check unresolved folders:', err);
             }
-            
+            // No unresolved folders or error - go to login
-            // No unresolved folders or error - show completion message
+            window.location.href = '/login';
-            console.log('No unresolved folders or error, showing completion');
-            document.getElementById('completionMessage').style.display = 'block';
         }
 
         function showError(message) {

src/server/web/templates/unresolved.html

@@ -552,7 +552,7 @@
                 listEl.style.display = 'none';
                 emptyEl.style.display = 'block';
                 document.getElementById('skip-link').style.display = 'block';
-                setTimeout(() => { window.location.href = '/'; }, 2000);
+                setTimeout(() => { window.location.href = '/loading'; }, 2000);
             } else {
                 listEl.style.display = 'flex';
                 emptyEl.style.display = 'none';
@@ -690,7 +690,7 @@
                 emptyEl.style.display = 'block';
                 skipLink.style.display = 'block';
                 showToast('All series configured!', 'success');
-                setTimeout(() => { window.location.href = '/'; }, 2000);
+                setTimeout(() => { window.location.href = '/loading'; }, 2000);
             }
         }