# chika0221/sweep architecture

> Architecture diagram of the GitHub repository chika0221/sweep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chika0221/sweep
- Repository: https://github.com/chika0221/sweep

## Overview

##### Project Type & Purpose
- Full-stack, cross-platform mobile app (Flutter) with serverless backend (Firebase) and an IoT device (SwapBox).

##### High-Level File Structure Analysis
- Top-level “android”, “ios”, “web”, “linux”, “macos”, “windows” folders: Flutter build targets.
- “lib/”: Dart source—UI pages, state‐management, data models, scripts.
- “functions/”: Firebase Cloud Functions (Node.js) for server‐side logic (notifications, scheduled tasks).
- “pubspec.yaml”/“flutter_launcher_icons.yaml”: project config & resource definitions.

##### Architecture Insights from README
- Clients: Mobile app “Sweep” & separate PC-web “Sweep-Host” (external repo).
- Backend: Firebase for Auth, Firestore, Storage, Cloud Messaging.
- IoT: SwapBox prototypes (M5Stack + HX711 sensor + QR scanner) push data to Firebase.

##### Main Components & Their Relationships
1. Mobile Client (Flutter)
– UI Layers (lib/pages, lib/widgets)
– State Providers (lib/states) subscribing to Firestore & FCM
– Local scripts (lib/scripts) invoking Cloud Functions via HTTPS
2. Firebase Services
– Authentication (Google/Apple OAuth)
– Firestore (collections: posts, users, achievements, trashboxes)
– Storage (images uploaded with posts)
– Cloud Functions (functions/index.js):
- Data‐validation, point logic, notifications, scheduled updates
– FCM (push notifications)
3. IoT Device (SwapBox)
– Hardware: M5Stack + HX711 + QR scanner
– Firmware pushes:
- Sensor data (weight) + QR scan → Firestore via Firebase REST/SDK
4. External Services
– Google Maps API (map tiles, geocoding)
– Apple/Google OAuth endpoints
5. (Optional) PC-Web Host App
– Reads Firestore data, presents analytics/heatmap (external repo)

##### Architectural Patterns & Design Principles
- Client–Server (thin client, serverless backend)
- Pub/Sub (Firestore triggers → Cloud Functions → FCM)
- MVVM-style state management in Flutter (Providers/Notifiers)
- Microservices‐style (each Cloud Function is a discrete endpoint)
- Cross-platform code reuse

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    subgraph "External Services" 
        direction TB
        OAuth["OAuth (Google/Apple)"]:::external
        MapsAPI["Google Maps API"]:::external
    end

    %% User and IoT
    subgraph "Clients & Devices"
        direction TB
        User["User (Citizen)"]:::client
        SwapBox["SwapBox IoT Device"]:::iot
    end

    %% Flutter App
    subgraph "Sweep App (iOS/Android/Web/etc.)" 
        direction TB
        Main["Flutter App Entry Point"]:::client
        subgraph "UI Layers" 
            direction TB
            Pages["UI Layers (Pages)"]:::client
            Widgets["UI Components (Widgets)"]:::client
        end
        States["State Providers / MVVM Notifiers"]:::client
        subgraph "Scripts / Local Invocations" 
            direction TB
            ScriptsFirebaseUpdate["Cloud‐Function Invocations\n(lib/scripts/firebase_update_script.dart)"]:::client
            ScriptsNotification["Notification Script\n(lib/scripts/notification_script.dart)"]:::client
        end
        Models["Data Models\n(lib/classes/)"]:::client
        DataAchievements["Static Data Definitions\n(lib/data/achievements_data.dart)"]:::client
        Theme["App Theme / Styling\n(lib/themes/app_theme.dart)"]:::client
        Assets["Assets\n(Fonts/Icons/Images)"]:::client
    end

    %% Firebase Backend
    subgraph "Google Cloud / Firebase" 
        direction TB
        Auth["Authentication"]:::backend
        Firestore["Firestore DB"]:::backend
        Storage["Storage"]:::backend
        Functions["Cloud Functions\n(functions/index.js)"]:::backend
        FCM["FCM (Push Notifications)"]:::backend
    end

    %% Cloud Functions Dependencies
    subgraph "Functions Dependencies"
        direction TB
        PackageJSON["package.json"]:::backend
        PackageLock["package-lock.json"]:::backend
    end

    %% Platform Config & Project Config
    subgraph "Project Configuration"
        direction TB
        Pubspec["pubspec.yaml\nflutter_launcher_icons.yaml"]:::config
        AndroidConfig["AndroidManifest.xml\nbuild.gradle"]:::config
        iOSConfig["GoogleService-Info.plist\nRunner/Info.plist"]:::config
    end

    %% Web Dashboard (optional)
    subgraph "Web Dashboard (Host App)" 
        direction TB
        WebDashboard["Web Dashboard"]:::external
    end

    %% Connections
    User -->|"Login"| Auth
    Main -->|"calls"| Auth
    Main -->|"fetch map tiles"| MapsAPI
    Main -->|"fetch geocoding"| MapsAPI

    Main -->|"write post"| Firestore
    Pages -->|"write post"| Firestore
    Pages -->|"fetch trashboxes"| Firestore
    States -->|"subscribe to changes"| Firestore
    States -->|"subscribe to FCM"| FCM

    ScriptsFirebaseUpdate -->|"scheduled update"| Firestore
    ScriptsFirebaseUpdate -->|"update achievements"| Firestore
    ScriptsNotification -->|"invoke notification CF"| Functions

    Functions -->|"trigger onNewPost"| FCM
    Firestore -->|"onWrite posts"| Functions
    Firestore -->|"onSchedule"| Functions
    FCM -->|"push notifications"| Main

    SwapBox -->|"POST weight + QR"| Firestore

    OAuth --> Auth
    MapsAPI --> Pages

    WebDashboard -->|"reads collections"| Firestore

    %% Click Events
    click Main "https://github.com/chika0221/sweep/blob/master/lib/main.dart"
    click Pages "https://github.com/chika0221/sweep/tree/master/lib/pages/"
    click Widgets "https://github.com/chika0221/sweep/tree/master/lib/widgets/"
    click States "https://github.com/chika0221/sweep/tree/master/lib/states/"
    click ScriptsFirebaseUpdate "https://github.com/chika0221/sweep/blob/master/lib/scripts/firebase_update_script.dart"
    click ScriptsNotification "https://github.com/chika0221/sweep/blob/master/lib/scripts/notification_script.dart"
    click Models "https://github.com/chika0221/sweep/tree/master/lib/classes/"
    click DataAchievements "https://github.com/chika0221/sweep/blob/master/lib/data/achievements_data.dart"
    click Theme "https://github.com/chika0221/sweep/blob/master/lib/themes/app_theme.dart"
    click Assets "https://github.com/chika0221/sweep/tree/master/assets/fonts/, assets/icons/, assets/images/"
    click Functions "https://github.com/chika0221/sweep/blob/master/functions/index.js"
    click PackageJSON "https://github.com/chika0221/sweep/blob/master/functions/package.json"
    click PackageLock "https://github.com/chika0221/sweep/blob/master/functions/package-lock.json"
    click Pubspec "https://github.com/chika0221/sweep/blob/master/pubspec.yaml"
    click AndroidConfig "https://github.com/chika0221/sweep/blob/master/android/app/src/main/AndroidManifest.xml"
    click AndroidConfig "https://github.com/chika0221/sweep/blob/master/android/app/build.gradle"
    click iOSConfig "https://github.com/chika0221/sweep/blob/master/ios/GoogleService-Info.plist"
    click iOSConfig "https://github.com/chika0221/sweep/blob/master/ios/Runner/Info.plist"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef iot fill:#ffe5b4,stroke:#cc7000,color:#cc7000;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef config fill:#f8d7da,stroke:#721c24,color:#721c24;
```
