zahar/citypulse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README for clarity and Codespaces compatibility

Browse Source
This commit is contained in:
Zahar
2025-09-26 09:54:12 +08:00
parent abf3ee7e25
commit 4496986d9b
1 changed files with 73 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
README.md
View File

@@ -1,25 +1,65 @@
# FixMate — Front-end (Flutter & React Dashboard) # FixMate — Flutter app + React dashboard (Codespaces-friendly)
## Overview FixMate is a lightweight, demo-friendly citizen maintenance reporter. It lets you quickly capture issues, geotag them, and visualize reports on a simple dashboard. There’s no backend; everything runs locally or in the browser — perfect for hackathons, prototypes, and GitHub Codespaces.
- FixMate is a citizen maintenance reporter used to quickly capture and track community issues during a hackathon-style demo.
- This repository contains front-end only implementations: a Flutter mobile/web app and a static React dashboard. ## Why this repo exists
- There is no backend. AI is simulated deterministically. Data is stored locally or loaded from demo JSON. - Zero-backend demo: data lives on-device (or in demo JSON for the dashboard).
- Deterministic "mock AI" categorization so UX flows are predictable.
- Fast setup in Codespaces or locally with minimal dependencies.
## Quick start in GitHub Codespaces
You can run both the Flutter app (as a web app) and the static React dashboard entirely inside a Codespace. No emulators required.
### 1) Flutter Web (recommended in Codespaces)
- Prerequisites: Flutter SDK is available in your Codespace. If not, install it or use a devcontainer with Flutter preinstalled. Then enable web:
- flutter config --enable-web
- Install dependencies:
- flutter pub get
- Run a local web server (Codespaces will auto-forward the port):
- flutter run -d web-server --web-port 3000
- Open the forwarded port from the Codespaces ports panel. Camera and geolocation typically work over the Codespaces HTTPS tunneled URL.
Notes:
- Geolocation/camera require HTTPS in many browsers; Codespaces forwarded URLs are HTTPS, which helps.
- On web, images are stored as base64; on mobile, images are saved to app storage and paths persist (see [lib/services/storage.dart](lib/services/storage.dart:1)).
- Entry point for the app is [main()](lib/main.dart:8), which wires up i18n and the locale provider and launches [FixMateApp](lib/app.dart:12).
### 2) React dashboard (static site)
- Serve inside Codespaces (Python simple HTTP server):
- cd dashboard && python -m http.server 8000
- Open the forwarded port and view your dashboard.
Behavior:
- Language toggle persists in localStorage.
- Filters drive a clustered Leaflet map, queue, drawer, stats, and optional heatmap overlay.
## Running locally (outside Codespaces)
### Flutter
- Install Flutter (stable) and run:
- flutter pub get
- flutter run (or flutter run -d chrome)
- Android/iOS will prompt for camera and location permissions. On web, geolocation/camera require HTTPS; some browsers restrict camera on http.
- App root: [FixMateApp](lib/app.dart:12). Bottom tabs and routing live in [MainScreen](lib/app.dart:36) and the onboarding/start logic lives in [StartRouter](lib/app.dart:114).
### Dashboard
- Serve the dashboard folder over HTTP:
- cd dashboard && python -m http.server 8000
- Open http://127.0.0.1:8000 (or your dev server URL).
## Features implemented ## Features implemented
- Flutter app tabs: Report, Map, My Reports, Settings (bilingual EN/BM) - Flutter app tabs: Report, Map, My Reports, Settings (bilingual EN/BM)
- Capture flow: camera/gallery, GPS, deterministic mock AI, local storage - Capture flow: camera/gallery, GPS, deterministic mock AI, local storage
- Map: OSM via flutter_map with clustering, filters, marker details, legend, external maps link - Map: OpenStreetMap via flutter_map with clustering, filters, marker details, legend, external maps link
- My Reports: list/detail with status cycle and delete - My Reports: list/detail with status cycle and delete
- Settings: language toggle and clear data - Settings: language toggle and clear data
- React dashboard: filters, clustered map, queue, drawer, stats, heatmap toggle - React dashboard: filters, clustered map, queue, drawer, stats, heatmap toggle
## Tech stack
- Flutter packages: flutter_map, flutter_map_marker_cluster, latlong2, geolocator, image_picker, path_provider, shared_preferences, uuid, url_launcher, provider
- Dashboard: React 18 UMD, Leaflet + markercluster (+ optional heat), Day.js
## Project structure ## Project structure
- Key Flutter files: - Key Flutter files:
- [lib/app.dart](lib/app.dart:1) - [lib/app.dart](lib/app.dart:1)
- [lib/main.dart](lib/main.dart:1)
- [lib/screens/report_flow/capture_screen.dart](lib/screens/report_flow/capture_screen.dart:1) - [lib/screens/report_flow/capture_screen.dart](lib/screens/report_flow/capture_screen.dart:1)
- [lib/screens/map/map_screen.dart](lib/screens/map/map_screen.dart:1) - [lib/screens/map/map_screen.dart](lib/screens/map/map_screen.dart:1)
- [lib/screens/my_reports/my_reports_screen.dart](lib/screens/my_reports/my_reports_screen.dart:1) - [lib/screens/my_reports/my_reports_screen.dart](lib/screens/my_reports/my_reports_screen.dart:1)
@@ -27,39 +67,45 @@
- [lib/services/storage.dart](lib/services/storage.dart:1), [lib/services/mock_ai.dart](lib/services/mock_ai.dart:1), [lib/services/location_service.dart](lib/services/location_service.dart:1) - [lib/services/storage.dart](lib/services/storage.dart:1), [lib/services/mock_ai.dart](lib/services/mock_ai.dart:1), [lib/services/location_service.dart](lib/services/location_service.dart:1)
- [lib/models/report.dart](lib/models/report.dart:1), [lib/models/enums.dart](lib/models/enums.dart:1) - [lib/models/report.dart](lib/models/report.dart:1), [lib/models/enums.dart](lib/models/enums.dart:1)
- [assets/lang/en.json](assets/lang/en.json:1), [assets/lang/ms.json](assets/lang/ms.json:1) - [assets/lang/en.json](assets/lang/en.json:1), [assets/lang/ms.json](assets/lang/ms.json:1)
- Dashboard files: - Dashboard files:
- [dashboard/index.html](dashboard/index.html:1), [dashboard/app.js](dashboard/app.js:1), [dashboard/styles.css](dashboard/styles.css:1) - [dashboard/index.html](dashboard/index.html:1), [dashboard/app.js](dashboard/app.js:1), [dashboard/styles.css](dashboard/styles.css:1)
- [dashboard/i18n/en.json](dashboard/i18n/en.json:1), [dashboard/i18n/ms.json](dashboard/i18n/ms.json:1) - [dashboard/i18n/en.json](dashboard/i18n/en.json:1), [dashboard/i18n/ms.json](dashboard/i18n/ms.json:1)
- [dashboard/data/demo-reports.json](dashboard/data/demo-reports.json:1) - [dashboard/data/demo-reports.json](dashboard/data/demo-reports.json:1)
## Running the Flutter app ## Tech stack
- Prerequisites: Flutter stable installed and a device/emulator or Chrome for web. - Flutter packages: flutter_map, flutter_map_marker_cluster, latlong2, geolocator, image_picker, path_provider, shared_preferences, uuid, url_launcher, provider (see [pubspec.yaml](pubspec.yaml:31))
- Commands: - Dashboard: React 18 UMD, Leaflet + markercluster (+ optional heat), Day.js
- flutter pub get
- flutter run (or flutter run -d chrome)
- Notes:
- Android/iOS will prompt for camera and location permissions.
- On the web, geolocation and camera require HTTPS; some browsers restrict camera on http.
- Photos are stored as base64 on web; on mobile, images are saved to app storage and paths are persisted (see [lib/services/storage.dart](lib/services/storage.dart:1)).
## Running the React dashboard ## Developer notes (for quick orientation)
- Serve the dashboard folder over HTTP (e.g., VSCode Live Server or Python): - App entry: [main()](lib/main.dart:8) initializes locale/i18n and launches [FixMateApp](lib/app.dart:12).
- cd dashboard && python -m http.server 8000 - Tab nav and screens: [MainScreen](lib/app.dart:36) displays tabs for:
- Open http://127.0.0.1:8000 in a browser (or your Live Server URL). - Report: [CaptureScreen](lib/screens/report_flow/capture_screen.dart:1)
- Behavior: - Map: [MapScreen](lib/screens/map/map_screen.dart:1)
- Language toggle persists using localStorage. - My Reports: [MyReportsScreen](lib/screens/my_reports/my_reports_screen.dart:1)
- Filters drive the clustered Leaflet map, queue, drawer, stats, and optional heatmap overlay. - Settings: [SettingsScreen](lib/screens/settings/settings_screen.dart:1)
- Onboarding + welcome handoff: [StartRouter](lib/app.dart:114) decides whether to show onboarding or the main app.
- Themes live in [lib/theme/themes.dart](lib/theme/themes.dart:1), translations in [assets/lang/en.json](assets/lang/en.json:1) and [assets/lang/ms.json](assets/lang/ms.json:1).
## Known limitations ## Known limitations
- No backend; all data is local or demo JSON. - No backend; all data is local or demo JSON.
- AI is simulated; severity/category are heuristic and not model-driven. - "AI" is simulated; severity/category are heuristic and not model-driven.
- Dashboard UI state is not persisted; a refresh resets filters and selections. - Dashboard UI state is not persisted; a refresh resets filters and selections.
- OpenStreetMap tile usage is subject to their terms and rate limits. - OpenStreetMap tile usage is subject to their terms and rate limits.
- Mobile-only features (camera with native picker, GPS background behavior) won’t fully work in Codespaces; use Flutter Web inside Codespaces for best results.
## Visual tokens ## Visual tokens
- Severity colors: High #D32F2F, Medium #F57C00, Low #388E3C - Severity colors: High #D32F2F, Medium #F57C00, Low #388E3C
- Status colors: Submitted #1976D2, In Progress #7B1FA2, Fixed #455A64 - Status colors: Submitted #1976D2, In Progress #7B1FA2, Fixed #455A64
## Troubleshooting
- Browser blocks camera/geolocation on non-HTTPS:
- Use Codespaces forwarded HTTPS URL or run locally over HTTPS.
- Flutter web server port not visible:
- Check Codespaces “Ports” tab, ensure the port is “Public”.
- Slow map tile loads:
- You may be rate-limited or on a constrained network; reduce panning/zoom or cache during demos.
## License ## License
- Placeholder: add a LICENSE file or specify licensing before distribution. - Placeholder: add a LICENSE file or specify licensing before distribution.