Navigation & Routing

Freak-Flix utilizes a declarative routing system powered by GoRouter. This approach ensures seamless navigation across Windows, Android, and Web, providing support for deep linking, browser history, and complex multi-pane layouts.

🗺️ Route Configuration

The application navigation is organized into several primary branches. Each route is mapped to a specific UI component and supports dynamic parameters for content loading.

| Route | Purpose | Parameters | | :--- | :--- | :--- | | / | Home/Dashboard | N/A | | /library | Media Library | N/A | | /movies/:id | Movie Details | id (Media ID) | | /tv/:id | TV Show Details | id (Series ID) | | /actor/:id | Actor Profile | id (Person ID) | | /settings | App Configuration | N/A | | /auth | Authentication | mode (Login/Register) |

📐 Multi-Pane Navigation Structure

To accommodate the "Netflix-style" immersive interface, Freak-Flix employs an adaptive navigation shell. The UI layout shifts based on the platform and screen real estate:

Desktop & Web (Large Screens)

The application uses a Side Navigation Rail or Persistent Sidebar.

• Primary Pane: Displays the main content (Grid of movies, settings, etc.).
• Overlay/Detail Pane: When a media item is selected, a detail view often slides in or replaces the current view while maintaining the navigation state.

Mobile (Handhelds)

The interface switches to a Bottom Navigation Bar for thumb-friendly access to Home, Search, Library, and Settings.

🚀 Usage & Programmatic Navigation

To navigate between pages within the application, use the context.push or context.go extensions provided by GoRouter.

Basic Navigation

Use go when you want to replace the current stack (ideal for bottom-tab switching).

// Navigate to the Library
context.go('/library');

Navigating with Parameters

When viewing specific media or actor profiles, pass the unique identifier in the URI.

// Navigate to a specific Movie detail page
context.push('/movies/12345');

// Navigate to an Actor profile
context.push('/actor/9876');

Deep Linking

Because Freak-Flix follows standard URI patterns, users can launch the application directly into specific views.

• Web: https://freak-flix.web.app/movies/550
• Windows/Android: External intent filters allow opening freakflix://movies/550 (if configured).

🔒 Protected Routes

Certain routes, such as Settings or Cloud Library, may require an active session. The router includes a redirect logic that checks the authentication state:

1. Auth Guard: If a user attempts to access a protected route without a valid JWT (as seen in the backend authMiddleware), they are redirected to /auth.
2. Adult Content Toggle: Routes related to StashDB or Adult content are dynamically filtered based on the "Privacy First" settings toggled in the configuration.

⚙️ Navigation Observability

For developers or advanced users debugging the navigation flow:

• Navigation Logs: Standard Flutter logs will output route changes when the application is run in --debug mode.
• State Management: The current location is reflected in the application state, allowing the UI to highlight the active tab in the sidebar or bottom bar automatically.