feat: implement startup gate in main.dart to ensure backend readiness before app launch

Author: AsieduDevelopmentHub

dashboard/lib/main.dart

@@ -7,25 +7,181 @@ import 'package:sentracore_dashboard/providers/settings_provider.dart';
 import 'package:sentracore_dashboard/navigation/dashboard_navigation.dart';
 import 'package:sentracore_dashboard/screens/dashboard_screen.dart';
 import 'package:sentracore_dashboard/services/desktop_notification_service.dart';
+import 'package:sentracore_dashboard/services/engine_bundled_launcher.dart';
 import 'package:sentracore_dashboard/theme/app_theme.dart';
 
 Future<void> main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  final notifications = DesktopNotificationService();
-  await notifications.init(
-    onDidReceiveNotificationResponse: (response) {
-      if (response.notificationResponseType ==
-          NotificationResponseType.selectedNotification) {
-        DashboardNavigation.openAlertsFromNotification();
-      }
-    },
-  );
-  final settings = SettingsProvider();
-  await settings.load();
-  runApp(SentraCoreApp(
-    settings: settings,
-    notifications: notifications,
-  ));
+  runApp(const StartupGateApp());
+}
+
+class StartupGateApp extends StatefulWidget {
+  const StartupGateApp({super.key});
+
+  @override
+  State<StartupGateApp> createState() => _StartupGateAppState();
+}
+
+class _StartupGateAppState extends State<StartupGateApp> {
+  late Future<_BootResult> _boot;
+
+  @override
+  void initState() {
+    super.initState();
+    _boot = _bootstrap();
+  }
+
+  Future<_BootResult> _bootstrap() async {
+    final notifications = DesktopNotificationService();
+    await notifications.init(
+      onDidReceiveNotificationResponse: (response) {
+        if (response.notificationResponseType ==
+            NotificationResponseType.selectedNotification) {
+          DashboardNavigation.openAlertsFromNotification();
+        }
+      },
+    );
+    final settings = SettingsProvider();
+    await settings.load();
+
+    // READY GATE (strict): do not enter the app until backend is healthy.
+    final out = await EngineBundledLauncher.ensureReady(
+      preferredPort: settings.lastEngineHttpPort,
+      timeout: const Duration(seconds: 25),
+    );
+    return _BootResult(
+        settings: settings, notifications: notifications, gate: out);
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return FutureBuilder<_BootResult>(
+      future: _boot,
+      builder: (context, snap) {
+        final theme = AppTheme.lightTheme;
+        final dark = AppTheme.darkTheme;
+        if (!snap.hasData) {
+          return MaterialApp(
+            debugShowCheckedModeBanner: false,
+            theme: theme,
+            darkTheme: dark,
+            home: const _StartupSplash(),
+          );
+        }
+
+        final data = snap.data!;
+        if (!data.gate.success) {
+          return MaterialApp(
+            debugShowCheckedModeBanner: false,
+            theme: theme,
+            darkTheme: dark,
+            home: _StartupError(
+              message: data.gate.message ?? 'Backend failed to start.',
+              onRetry: () => setState(() => _boot = _bootstrap()),
+            ),
+          );
+        }
+
+        return SentraCoreApp(
+            settings: data.settings, notifications: data.notifications);
+      },
+    );
+  }
+}
+
+class _BootResult {
+  final SettingsProvider settings;
+  final DesktopNotificationService notifications;
+  final EngineBootstrapOutcome gate;
+  const _BootResult({
+    required this.settings,
+    required this.notifications,
+    required this.gate,
+  });
+}
+
+class _StartupSplash extends StatelessWidget {
+  const _StartupSplash();
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: Column(
+          mainAxisSize: MainAxisSize.min,
+          children: [
+            Text(
+              'SentraCore',
+              style: TextStyle(
+                fontSize: 20,
+                fontWeight: FontWeight.w800,
+                color: AppTheme.textPrimaryFor(context),
+              ),
+            ),
+            const SizedBox(height: 12),
+            SizedBox(
+              width: 220,
+              child: LinearProgressIndicator(
+                backgroundColor:
+                    Theme.of(context).dividerColor.withValues(alpha: 0.25),
+                valueColor:
+                    const AlwaysStoppedAnimation<Color>(AppTheme.primary),
+              ),
+            ),
+            const SizedBox(height: 10),
+            Text(
+              'Starting backend…',
+              style: TextStyle(
+                  color: AppTheme.textMutedFor(context), fontSize: 12),
+            ),
+          ],
+        ),
+      ),
+    );
+  }
+}
+
+class _StartupError extends StatelessWidget {
+  final String message;
+  final VoidCallback onRetry;
+  const _StartupError({required this.message, required this.onRetry});
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      body: Center(
+        child: Padding(
+          padding: const EdgeInsets.all(24),
+          child: ConstrainedBox(
+            constraints: const BoxConstraints(maxWidth: 520),
+            child: Column(
+              mainAxisSize: MainAxisSize.min,
+              crossAxisAlignment: CrossAxisAlignment.stretch,
+              children: [
+                Text(
+                  'Backend failed to start',
+                  style: TextStyle(
+                    color: AppTheme.textPrimaryFor(context),
+                    fontSize: 18,
+                    fontWeight: FontWeight.w800,
+                  ),
+                ),
+                const SizedBox(height: 8),
+                Text(
+                  message,
+                  style: TextStyle(color: AppTheme.textMutedFor(context)),
+                ),
+                const SizedBox(height: 16),
+                FilledButton(
+                  onPressed: onRetry,
+                  child: const Text('Retry'),
+                ),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
 }
 
 class SentraCoreApp extends StatelessWidget {