# School Connect Africa — Web dashboard

The desktop/browser dashboard for school admins, head teachers, bursars and the super
admin. Built on Flutter Web and the shared [`sca_core`](../packages/sca_core) package.

## Web-specific UX
- Persistent **role-based left sidebar** (navigates via `go_router`, highlights the
  current route, with a user chip + sign-out in the footer).
- Top **header bar** per page.
- **Width-constrained, multi-column** content (e.g. the dashboard shows a 4-column metric
  grid beside an "Upcoming Events" panel).

The shell lives in `lib/shell/web_scaffold.dart`; the dashboard layout in
`lib/dashboard/web_dashboard.dart`. All module **content** comes from `sca_core`
(`FeesView`, `StructureView`, `CctvView`, …) — identical logic to the mobile app, only the
shell differs.

## School registration & approvals
The web app now hosts the **full verified registration flow** (shared from `sca_core`):
account → GPS capture (browser geolocation) + map → school info → school-email OTP →
officers (photo + phone/email OTP) → submit. Super Admins also get a **School Approvals**
sidebar item to review the captured location (map), officers and audit trail, then approve/reject.

> Browser geolocation requires a secure context (HTTPS) in production; `localhost` works in dev.
> No native config is needed — `geolocator`, `image_picker` and `flutter_map` use their web
> implementations automatically.

## Run
```bash
flutter create . --platforms=web   # generates the web/ platform folder (keeps lib/)
flutter pub get                    # resolves the local sca_core path dependency
flutter run -d chrome --dart-define=API_BASE_URL=http://127.0.0.1:8000/api
```

For production: `flutter build web --dart-define=API_BASE_URL=https://app.schoolconnectafrica.com/api`
and serve `build/web`. The web app also tries the current site's `/api` path as a
backup for safe read requests such as the location hierarchy. Make sure the API enables
CORS for every public web origin:
`CORS_ALLOWED_ORIGINS=https://schoolconnectafrica.com,https://www.schoolconnectafrica.com,https://app.schoolconnectafrica.com`.

Quick backend check:
```bash
curl https://app.schoolconnectafrica.com/api/health
```

Or use the scripted build:
```bash
./tool/build_pwa.sh https://app.schoolconnectafrica.com/api
```

Optional explicit fallback list:
```bash
./tool/build_pwa.sh https://app.schoolconnectafrica.com/api "https://schoolconnectafrica.com/api,https://www.schoolconnectafrica.com/api"
```

## PWA support (offline + install)
The web app includes:
- `web/manifest.json` (name, short_name, icons, theme/background colors)
- Flutter-generated `flutter_service_worker.js` (created during `flutter build web`)
- install prompt hook in `web/index.html` (uses `beforeinstallprompt`)

### HTTPS requirement
PWA installability and service workers require a secure context:
- Production: serve over **HTTPS**
- Local dev: `localhost` is allowed by browsers

### Offline behavior
The generated Flutter service worker caches the app shell and static assets for offline use.
The app data layer also uses local persistence fallback for key dashboard endpoints (events,
messages, notifications, structure, students, CCTV, and dashboard summary) when the backend
is temporarily unavailable.

Critical backend actions (payments, OTP verification, registration submit) still require
online Laravel confirmation.

## Windows desktop app
The project now includes a native Flutter Windows target in `windows/`.

### Build Windows app
On Windows machine:
```powershell
pwsh ./tool/build_windows.ps1 -ApiBaseUrl "https://api.yourdomain/api"
```

Outputs:
- Native release binaries in `build/windows/x64/runner/Release`
- Portable ZIP in `dist/windows/SchoolConnectAfrica-win64.zip`

### Create installer (teachers' PCs)
1. Install Inno Setup 6+ on Windows.
2. Open `windows/installer/SchoolConnectAfrica.iss`.
3. Build the installer script.

Installer output goes to `dist/installer/SchoolConnectAfrica-Setup.exe`.

### Notifications, persistence, and updates
- Notifications are supported through in-app banners/snackbars on desktop.
- Native Windows toast notifications can be added after upgrading Flutter/Dart to a newer SDK baseline.
- Local file persistence helper is available in `lib/core/storage/windows_file_store.dart`.
- Startup update check calls Laravel endpoint:
  - `GET /desktop/updates/latest?platform=windows`
  - Expected response shape: `{ "version": "1.0.1", "download_url": "https://.../SchoolConnectAfrica-Setup.exe" }`
  - If a newer version exists, users see a notification and install prompt.

## Layout
```
lib/
  main.dart                    app entry (ProviderScope + MaterialApp.router)
  router.dart                  auth-driven, role-based go_router
  shell/web_scaffold.dart      sidebar + header + constrained content area
  dashboard/web_dashboard.dart wide dashboard (4-col grid + events panel)
```
