From 11ea469b6de89dfc93f18ffa650b96d315762e4f Mon Sep 17 00:00:00 2001 From: Zahar Date: Fri, 26 Sep 2025 19:31:24 +0800 Subject: [PATCH] Update README to reflect new project structure and features - Revamped project description to highlight the integration of Flutter frontend, Python FastAPI backend, and AI-powered image classification. - Added detailed sections on system architecture, quick start guide, API endpoints, and features overview. - Enhanced troubleshooting and performance considerations for both frontend and backend. - Included future enhancements and acknowledgments for technologies used in the project. --- README.md | 446 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 354 insertions(+), 92 deletions(-) diff --git a/README.md b/README.md index 1aa5e53..05969d3 100644 --- a/README.md +++ b/README.md @@ -1,113 +1,375 @@ -# FixMate โ€” Flutter app + React dashboard (Codespaces-friendly) +# ๐Ÿ—๏ธ FixMate - Smart Citizen-Driven Urban Maintenance Platform -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 comprehensive citizen reporting application that combines **Flutter frontend** with **Python FastAPI backend** and **AI-powered image classification**. Users can capture urban issues (potholes, broken streetlights, trash, etc.), get automatic AI classification, and track their reports through a complete management system. -## Why this repo exists -- 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. +## ๐ŸŽฏ System Architecture -## Quick start in GitHub Codespaces +### Frontend (Flutter) +- **Location**: Root directory +- **Technology**: Flutter (Dart) with Material Design +- **Purpose**: Cross-platform mobile and web interface for citizens +- **Features**: Camera integration, GPS location, map visualization, bilingual support (EN/BM) -You can run both the Flutter app (as a web app) and the static React dashboard entirely inside a Codespace. No emulators required. +### Backend (Python FastAPI) +- **Location**: `backend/` directory +- **Technology**: Python FastAPI with SQLAlchemy + SQLite +- **Purpose**: RESTful API server with AI-powered image classification +- **Features**: YOLO-based object detection, severity classification, ticket management -### 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. +### Data Flow +``` +User takes photo โ†’ Flutter App โ†’ FastAPI Backend โ†’ AI Analysis โ†’ Database + โ†“ โ†“ โ†“ โ†“ โ†“ + Reports List โ†โ”€โ”€โ”€โ”€โ”€โ”€ API Calls โ†โ”€โ”€โ”€ HTTP/REST โ”€โ”€โ†’ YOLO Model โ”€โ†’ SQLite +``` -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). +## ๐Ÿš€ Quick Start Guide -### 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. +### Prerequisites +- **Flutter SDK** 3.8.1+ ([Install Guide](https://docs.flutter.dev/get-started/install)) +- **Python** 3.11+ ([Install Guide](https://python.org/downloads/)) +- **Git** for version control -Behavior: -- Language toggle persists in localStorage. -- Filters drive a clustered Leaflet map, queue, drawer, stats, and optional heatmap overlay. +### 1. Clone and Setup +```bash +git clone +cd fixmate-frontend +``` -## Running locally (outside Codespaces) +### 2. Install Flutter Dependencies +```bash +flutter pub get +``` -### 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). +### 3. Setup Backend +```bash +cd backend +pip install -r requirements.txt +``` -### 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). +### 4. Start Backend Server (Terminal 1) +```bash +cd backend +python main.py +``` +โœ… Backend will run on: `http://127.0.0.1:8000` -## Features implemented -- Flutter app tabs: Report, Map, My Reports, Settings (bilingual EN/BM) -- Capture flow: camera/gallery, GPS, deterministic mock AI, local storage -- Map: OpenStreetMap via flutter_map with clustering, filters, marker details, legend, external maps link -- My Reports: list/detail with status cycle and delete -- Settings: language toggle and clear data -- React dashboard: filters, clustered map, queue, drawer, stats, heatmap toggle +### 5. Start Flutter App (Terminal 2) +```bash +# Navigate back to project root +cd .. -## Project structure -- Key Flutter files: - - [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/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/settings/settings_screen.dart](lib/screens/settings/settings_screen.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) - - [assets/lang/en.json](assets/lang/en.json:1), [assets/lang/ms.json](assets/lang/ms.json:1) +# Start Flutter app (choose your target) +flutter run # Mobile (Android/iOS) +# OR +flutter run -d chrome # Web (Chrome) +# OR +flutter run -d web-server # Web Server +``` -- Dashboard files: - - [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/data/demo-reports.json](dashboard/data/demo-reports.json:1) +## ๐Ÿ”ง Alternative Startup Methods -## Tech stack -- 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)) -- Dashboard: React 18 UMD, Leaflet + markercluster (+ optional heat), Day.js +### Method A: Backend Only +```bash +cd backend +python main.py +``` -## Developer notes (for quick orientation) -- App entry: [main()](lib/main.dart:8) initializes locale/i18n and launches [FixMateApp](lib/app.dart:12). -- Tab nav and screens: [MainScreen](lib/app.dart:36) displays tabs for: - - Report: [CaptureScreen](lib/screens/report_flow/capture_screen.dart:1) - - Map: [MapScreen](lib/screens/map/map_screen.dart:1) - - My Reports: [MyReportsScreen](lib/screens/my_reports/my_reports_screen.dart:1) - - 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). +### Method B: Using Uvicorn (Alternative) +```bash +cd backend +uvicorn main:app --host 127.0.0.1 --port 8000 --reload +``` -## Known limitations -- No backend; all data is local or demo JSON. -- "AI" is simulated; severity/category are heuristic and not model-driven. -- Dashboard UI state is not persisted; a refresh resets filters and selections. -- 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. +### Method C: Flutter Web (Web Version) +```bash +flutter run -d chrome # or firefox, edge +``` -## Visual tokens -- Severity colors: High #D32F2F, Medium #F57C00, Low #388E3C -- Status colors: Submitted #1976D2, In Progress #7B1FA2, Fixed #455A64 +### Method D: Development Mode (Hot Reload) +```bash +# Terminal 1 - Backend with auto-reload +cd backend +uvicorn main:app --reload -## 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. +# Terminal 2 - Flutter with hot reload +flutter run +``` -## License -- Placeholder: add a LICENSE file or specify licensing before distribution. +## ๐Ÿ“ฑ API Endpoints -## Acknowledgements -- OpenStreetMap, Leaflet, flutter_map and community plugins, React, Day.js, Flutter community. \ No newline at end of file +The Flutter app communicates with these backend endpoints: + +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/api/tickets` | GET | Fetch all reports | +| `/api/report` | POST | Submit new report with image | +| `/api/tickets/{id}` | GET | Get specific report | +| `/api/tickets/{id}` | PATCH | Update report status | +| `/api/analytics` | GET | Get dashboard analytics | +| `/api/users` | POST | Create user account | + +### API Documentation +View interactive API documentation at: `http://127.0.0.1:8000/docs` + +--- + +## ๐ŸŽฎ Features Overview + +### Flutter Frontend Features +- โœ… **Report Flow**: Camera/gallery photo capture with GPS location +- โœ… **AI Classification**: Automatic issue type and severity detection +- โœ… **Map View**: Interactive OpenStreetMap with clustering and filtering +- โœ… **Report Management**: View, edit, and track report status +- โœ… **Bilingual Support**: English and Bahasa Malaysia +- โœ… **Settings**: Language toggle and data management + +### Backend AI Features +- โœ… **YOLO Object Detection**: Detects urban issues from images +- โœ… **Severity Classification**: ML model assesses issue severity +- โœ… **SQLite Database**: Local data storage with full CRUD operations +- โœ… **RESTful API**: Complete API for mobile app integration +- โœ… **File Upload**: Image storage and processing + +## ๐Ÿ“ Project Structure + +### Frontend (Flutter) +``` +lib/ +โ”œโ”€โ”€ app.dart # Main app widget and routing +โ”œโ”€โ”€ main.dart # App entry point +โ”œโ”€โ”€ models/ +โ”‚ โ”œโ”€โ”€ report.dart # Report data model +โ”‚ โ””โ”€โ”€ enums.dart # Category, severity, status enums +โ”œโ”€โ”€ screens/ +โ”‚ โ”œโ”€โ”€ report_flow/ # Photo capture flow +โ”‚ โ”œโ”€โ”€ map/ # Map visualization screen +โ”‚ โ”œโ”€โ”€ my_reports/ # User reports management +โ”‚ โ””โ”€โ”€ settings/ # App settings +โ”œโ”€โ”€ services/ +โ”‚ โ”œโ”€โ”€ api_service.dart # Backend API communication +โ”‚ โ”œโ”€โ”€ storage.dart # Local data storage +โ”‚ โ”œโ”€โ”€ location_service.dart # GPS location services +โ”‚ โ””โ”€โ”€ mock_ai.dart # AI classification logic +โ”œโ”€โ”€ theme/ +โ”‚ โ””โ”€โ”€ themes.dart # App theming +โ”œโ”€โ”€ widgets/ # Reusable UI components +โ””โ”€โ”€ l10n/ # Internationalization +``` + +### Backend (Python) +``` +backend/ +โ”œโ”€โ”€ main.py # FastAPI server entry point +โ”œโ”€โ”€ requirements.txt # Python dependencies +โ”œโ”€โ”€ app/ +โ”‚ โ”œโ”€โ”€ database.py # SQLite database setup +โ”‚ โ”œโ”€โ”€ models/ # Database models +โ”‚ โ”œโ”€โ”€ routes/ # API route handlers +โ”‚ โ”œโ”€โ”€ services/ # Business logic and AI services +โ”‚ โ”œโ”€โ”€ schemas/ # Pydantic data models +โ”‚ โ””โ”€โ”€ static/uploads/ # Image storage +โ””โ”€โ”€ test/ # Test files and utilities +``` + +## ๐Ÿ› ๏ธ Technology Stack + +### Frontend Technology Stack +- **Flutter**: 3.8.1+ with Material Design +- **Key Packages**: + - `flutter_map` + `flutter_map_marker_cluster` (Interactive maps) + - `geolocator` (GPS location services) + - `image_picker` (Camera integration) + - `http` (API communication) + - `provider` (State management) + - `shared_preferences` (Local storage) + +### Backend Technology Stack +- **FastAPI**: 0.117.1+ (Modern Python web framework) +- **SQLAlchemy**: 2.0.43+ (ORM for database operations) +- **PyTorch**: 2.8.0+ (Machine learning framework) +- **Ultralytics YOLO**: 8.3.203+ (Object detection) +- **SQLite**: Local database for data persistence + +### AI Models +- **Object Detection**: YOLOv12n for issue identification +- **Severity Classification**: Custom PyTorch model +- **Model Storage**: `backend/app/models/` directory + +## ๐Ÿ› ๏ธ Troubleshooting + +### Backend Issues + +**Port 8000 already in use:** +```bash +# Windows +netstat -ano | findstr :8000 +taskkill /F /IM python.exe + +# Alternative: Kill specific process +Get-Process -Name python | Stop-Process -Force +``` + +**Missing dependencies:** +```bash +cd backend +pip install -r requirements.txt +pip install python-multipart pydantic[email] +``` + +**Backend not starting:** +```bash +# Test if modules can be imported +cd backend +python -c "import main; print('Import successful')" +``` + +### Frontend Issues + +**Flutter dependencies:** +```bash +flutter clean +flutter pub get +``` + +**Device connection issues:** +```bash +flutter devices # List connected devices +flutter doctor # Check Flutter installation +``` + +**Web-specific issues:** +```bash +flutter config --enable-web +``` + +### Common Issues + +**"Connection refused" errors:** +- Ensure backend server is running on port 8000 +- Check firewall settings +- Verify API base URL in `lib/services/api_service.dart` + +**Camera/Geolocation not working:** +- Grant permissions in device settings +- Use HTTPS for web deployment +- Check browser permissions + +**Slow AI processing:** +- First startup downloads ML models (may take time) +- Consider using CPU-only builds for faster startup +- Check available memory + +## ๐Ÿงช Testing & Development + +### Backend Testing +```bash +cd backend +python -m pytest test/ # Run all tests +python test/check_torch.py # Verify PyTorch setup +``` + +### Flutter Testing +```bash +flutter test # Run unit tests +flutter test --coverage # With coverage report +``` + +### Database Management +```bash +cd backend +python -c "from app.database import engine; print('Database file:', engine.url.database)" +# Database file: backend/app/db/fixmate.db +``` + +## ๐Ÿ“Š Performance Considerations + +### Backend Performance +- **First Startup**: ML models download (~200MB) - may take several minutes +- **Memory Usage**: PyTorch models require significant RAM +- **CPU vs GPU**: CPU-only builds available for compatibility +- **Database**: SQLite suitable for small-scale deployments + +### Frontend Performance +- **Image Processing**: Images compressed before upload +- **Map Rendering**: Clustering optimizes marker display +- **Caching**: Local storage for offline functionality + +## ๐Ÿš€ Production Deployment + +### Backend Deployment +```bash +cd backend +# Production server +uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4 + +# Or with Gunicorn +gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker +``` + +### Flutter Deployment +```bash +# Build for production +flutter build apk --release # Android +flutter build ios --release # iOS +flutter build web --release # Web + +# Build for specific targets +flutter build appbundle # Android App Bundle +flutter build ipa # iOS Archive +``` + +## ๐Ÿ“š Key Files Reference + +### Essential Flutter Files +- `lib/main.dart` - App entry point +- `lib/app.dart` - Main app widget and navigation +- `lib/services/api_service.dart` - Backend communication +- `lib/models/report.dart` - Data models +- `pubspec.yaml` - Flutter dependencies + +### Essential Backend Files +- `backend/main.py` - FastAPI server +- `backend/app/database.py` - Database configuration +- `backend/app/routes/tickets.py` - Ticket API endpoints +- `backend/app/services/ai_service.py` - AI classification logic +- `backend/requirements.txt` - Python dependencies + +## ๐ŸŽฏ Future Enhancements + +### Planned Features +- [ ] Real-time notifications for status updates +- [ ] Advanced filtering and search capabilities +- [ ] User authentication and profiles +- [ ] Admin dashboard for report management +- [ ] Push notifications for mobile +- [ ] Offline mode with sync capabilities +- [ ] Multi-language support expansion +- [ ] Analytics and reporting dashboard + +### Technical Improvements +- [ ] Database optimization for large datasets +- [ ] Caching layer implementation +- [ ] API rate limiting +- [ ] Image compression optimization +- [ ] Background processing for AI tasks +- [ ] Monitoring and logging enhancement + +## ๐Ÿ“„ License & Acknowledgments + +### License +- Placeholder: Add appropriate license for your project + +### Acknowledgments +- **OpenStreetMap** - Map data and tile services +- **Leaflet** - Interactive mapping library +- **Flutter Community** - Dart packages and plugins +- **Ultralytics** - YOLO implementation +- **PyTorch** - Machine learning framework +- **FastAPI** - Modern Python web framework + +### References +1. [Flutter Documentation](https://docs.flutter.dev/) +2. [FastAPI Documentation](https://fastapi.tiangolo.com/) +3. [YOLOv12 Implementation](https://github.com/ultralytics/ultralytics) +4. [PyTorch Models](https://pytorch.org/)