Skip to content

Show a Banner in HomeScreen When the Backend Is Unreachable #26

@TheZupZup

Description

@TheZupZup

Overview

Context: The Flutter app currently gives no visual indication when the Python backend is unreachable. If the backend goes down after the initial connection, the user sees a blank notes list (or stale data) with no explanation. There is no persistent UI element that communicates backend reachability.

This issue adds a simple, non-intrusive banner to the HomeScreen that appears when the backend is unreachable.

What needs to be done

  • In AppState (app/lib/services/app_state.dart), add a bool _backendReachable = true field with a getter, and expose it via notifyListeners() whenever it changes
  • Set _backendReachable = false in any catch block in AppState where an API call fails due to a connection error (distinguish connection errors from 4xx/5xx errors — a 404 is not "offline")
  • Set _backendReachable = true when any API call succeeds
  • In HomeScreen (home_screen.dart), wrap the main content in a Column and conditionally show a MaterialBanner or AnimatedSwitcher-wrapped container at the top when !appState.backendReachable:
    ⚠ Cannot reach the backend. Check that the Python server is running.
    
  • The banner should include a Retry button that calls AppState.checkBackendHealth() (or AppState.connect())
  • The banner should dismiss automatically when _backendReachable becomes true again

Goal

When the Python backend stops responding, a yellow/red banner appears at the top of the HomeScreen within one API call's worth of time. When the backend comes back and any call succeeds, the banner disappears automatically.

Where to look

  • app/lib/services/app_state.dart — add _backendReachable, update it in all catch blocks
  • app/lib/screens/home_screen.dart_DesktopLayout and _MobileLayout — add the banner above the main content area
  • Flutter MaterialBanner widget docs for reference

Edge cases

  • Do not show the banner if sync is simply unconfigured (no WebDAV set up) — only when the backend API itself is unreachable
  • Do not show the banner on the ConnectScreen — it only belongs on the HomeScreen
  • The banner should not push the notebook sidebar or notes list out of position on the desktop layout

Testing steps

  • Kill the Python backend while on the home screen — verify the banner appears after the next failed API call
  • Restart the backend and tap "Retry" — verify the banner disappears
  • Keep the backend running the whole time — verify the banner never appears

Notes

This is a good first issue. It requires only Flutter changes — a new boolean in AppState and a conditional widget in HomeScreen.

Related to: #12, #22, #23, #24

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions