docs(mobile-client): expand routing documentation to include two-tiered architecture

- Add detailed explanation of pre-router status pages and their importance
- Include information about the main GoRouter implementation and its features
- Provide a visual representation of the main route tree structure
- Maintain focus on the robustness and maintainability of the routing system

Author: fulleni

src/content/docs/mobile-client/architecture/routing.mdx

@@ -1,11 +1,92 @@
 ---
 title: Routing & Navigation
-description: Learn about the navigation structure and routing implementation in the mobile client.
+description: Learn about the two-tiered routing architecture that powers the mobile client.
 ---
 import { Card, CardGrid } from '@astrojs/starlight/components';
 
-Navigation in the mobile client is managed by the powerful `go_router` package. This provides a declarative, URL-based routing system that is robust, type-safe, and easy to maintain. All routing configuration is centralized within the `lib/router/` directory.
+The mobile client employs a robust, two-tiered architecture to manage application startup and navigation. This ensures the app is in a stable, valid state before rendering the main UI and its nested routes.
 
+## Tier 1: Pre-Router Status Pages
+
+The first tier of logic acts as a global gatekeeper. It is handled by the root `_AppView` widget (`lib/app/view/app.dart`) and the `AppBloc`. This tier determines if a critical, full-screen status page should be displayed *before* the main `GoRouter` instance is ever built.
+
+This pre-flight check is essential for handling states that must block the entire application.
+
+<CardGrid>
+	<Card title="AppStatus.configFetching" icon="cloud-download">
+		On startup, the `AppBloc` immediately attempts to fetch the remote configuration. During this time, the `_AppView` displays a `StatusPage` with a loading indicator.
+	</Card>
+	<Card title="AppStatus.configFetchFailed" icon="error">
+		If the configuration fetch fails (e.g., due to a network error), the `StatusPage` updates to show an error message and a retry button, allowing the user to attempt the fetch again.
+	</Card>
+	<Card title="AppStatus.underMaintenance" icon="construction">
+		If the fetched config indicates that the app is in maintenance mode, the `_AppView` replaces the UI with a dedicated `MaintenancePage`.
+	</Card>
+    <Card title="AppStatus.updateRequired" icon="system-update">
+        If the config indicates a mandatory update is required, the `_AppView` displays an `UpdateRequiredPage` with a link to the appropriate app store.
+    </Card>
+</CardGrid>
+
+In any of these critical states, the main application router is not active. This architecture prevents race conditions and ensures the app only proceeds once it has confirmed it is in a healthy, runnable state.
+
+## Tier 2: Authenticated Routing with GoRouter
+
+Once the pre-flight checks in Tier 1 are passed, the `_AppView` builds the main `MaterialApp.router`, activating `go_router`. From this point on, `go_router` is responsible for all in-app navigation.
+
+### Core Concepts
+
+-   **`GoRouter`**: The main router instance that controls the application's navigation stack. It is configured with a list of routes, redirect logic, and a refresh listener.
+
+-   **`Routes` Class**: A class located in `lib/router/routes.dart` that defines all route paths and names as `static const String` constants. Using named routes (e.g., `context.goNamed(Routes.settingsName)`) instead of raw path strings is a best practice that prevents typos and makes the code more maintainable.
+
+-   **`StatefulShellRoute`**: This is a key component from `go_router` used to implement persistent UI elements, such as the main bottom navigation bar. It wraps the main sections of the app (e.g., Headlines Feed, Search, Account) and manages a separate navigation stack for each section, preserving the navigation state as the user switches between tabs.
+
+### Key Implementations
+
+<CardGrid>
+	<Card title="Centralized Configuration" icon="file-tree">
+		All route definitions are located in `lib/router/router.dart`. This file contains the `GoRouter` setup, including the tree of `GoRoute` and `StatefulShellRoute` widgets that define the entire navigation map of the application.
+	</Card>
+	<Card title="Authentication-Aware Redirects" icon="shield-check">
+		The router is configured with a `redirect` logic that depends on the application's authentication status, which is provided by the `AppBloc`. This ensures that unauthenticated users are automatically redirected to the sign-in page, while authenticated users are directed to the main app content, creating a secure and seamless user experience.
+	</Card>
+	<Card title="Type-Safe Navigation" icon="shield">
+		By using named routes defined in the `Routes` class, navigation calls throughout the app are type-safe. This approach reduces runtime errors and makes it easy to refactor or update routes, as any changes only need to be made in one central location.
+	</Card>
+    <Card title="Passing Arguments" icon="box">
+        The router is used to pass complex data between pages. For example, when navigating to a details page, the full `Headline` object is passed via the `extra` parameter of the navigation call. This is more efficient than passing an ID and re-fetching data that is already available.
+    </Card>
+</CardGrid>
+
+### Route Structure
+
+The main application routes are structured using a `StatefulShellRoute`, which provides the bottom navigation bar. Top-level routes are used for pages that should appear over the main shell, such as authentication or detailed content views.
+
+```tree title="Main Route Tree"
+/
+├─ /feed
+│  ├─ article/:id
+│  ├─ notifications
+│  └─ filter
+│     ├─ topics
+│     └─ sources
+├─ /search
+│  └─ article/:id
+└─ /account
+   ├─ settings
+   │  ├─ appearance
+   │  │  ├─ theme
+   │  │  └─ font
+   │  ├─ feed
+   │  └─ language
+   ├─ manage-followed-items
+   │  ├─ topics
+   │  │  └─ add-topic
+   │  └─ sources
+   │     └─ add-source
+   └─ saved-headlines
+      └─ article/:id
+```
 ## Core Concepts
 
 -   **`GoRouter`**: The main router instance that controls the application's navigation stack. It is configured with a list of routes, redirect logic, and a refresh listener.