# log4j-innovations/scrapbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/log4j-innovations/scrapbuddy
- Repository: https://github.com/log4j-innovations/scrapbuddy

## Overview

##### Project type and purpose
- ScrapBuddy is a cross-platform (Android, iOS, Web, Windows, macOS, Linux) Flutter application that uses AI (Google Vertex AI + on-device TensorFlow Lite) to classify waste materials, provide recycling guidance, track user stats, and deliver voice assistance via Sarvam AI.

##### File structure
- Top-level directories:
- android / ios / linux / macos / web / windows → platform embedding and native launchers
- lib → the Dart application code, subdivided into config, localization, models, screens (UI), services (business logic), widgets (UI components)
- assets → audio clips (multi‐lang), ML models (TFLite), labels, other static resources
- scripts → build or codegen helpers (e.g., generate_audio.dart)
- Key patterns:
- Clean Architecture / separation of concerns: UI (screens/widgets) ⇄ service layer (vertex_ai_service, firebase_service, offline_classifier_service) ⇄ data sources (Firestore, Storage, local assets, Shared Preferences)
- Provider or similar state management (implied by “Provider pattern” in README)
- Deployment/config files:
- pubspec.yaml → Flutter dependencies
- android/app/build.gradle, ios/Runner.xcodeproj → native Firebase integration
- analysis_options.yaml → linting rules

##### README for additional insights
- Architecture description: Clean/Repository/Service layer, Provider state management
- Tech stack: Flutter/Dart, Firebase Auth, Firestore, Firebase Storage, Vertex AI, TensorFlow Lite, Sarvam AI TTS, Shared Preferences
- Features: real-time & offline inference, multi-language support, gamification, audio guidance, responsive UI

a. Main components
- Client Application (Flutter UI)
- Service Layer
- Vertex AI Service (remote inference)
- Offline Classifier Service (TFLite on-device)
- Firebase Service (Auth, Firestore, Storage)
- Sarvam AI Service (TTS)
- Data Stores
- Cloud Firestore (user profiles, scan history, stats)
- Firebase Storage (uploaded images)
- Local Storage (Shared Preferences, cached TFLite model, offline audio)
- External Services
- Google Vertex AI
- Sarvam AI TTS
b. Relationships and interactions
- UI screens/widgets invoke Service Layer APIs
- Service Layer delegates to either Vertex AI (REST/gRPC) or Offline TFLite for classification
- Classification results → UI + Service Layer triggers Firestore updates (user points, history)
- Service Layer calls Sarvam AI (or local audio assets) to generate/play audio guidance
- On login/registration, UI → Firebase Auth → Firestore → local cache
- Assets (models/audio) loaded from packaged assets folder on startup
c. Architectural patterns
- Clean Architecture (UI ⇄ Use Cases/Services ⇄ Repositories ⇄ Data Sources)
- Repository pattern for abstracting Firebase vs. local data sources
- Provider (or other DI) for injecting services into widgets
- Offline-first design: fallback to on-device ML and cached audio when network unavailable
d. Key technologies/frameworks
- Flutter & Dart
- TensorFlow Lite (model_unquant.tflite in assets)
- Google Vertex AI (Gemini 2.0 Flash)
- Firebase (Auth, Firestore, Storage)
- Sarvam AI (Text-to-Speech)
- Shared Preferences (local key-value store)
- Audio Players package for playback

## Diagram (Mermaid)

```mermaid
graph TB

  %% Client Boundary
  subgraph "Client Application (Flutter UI)" 
    direction TB
    UI["Flutter UI\n(screens/widgets)"]:::frontend
    STATE["State Management\n(Provider)"]:::frontend
    CONFIG["App Theme\n(lib/config/app_theme.dart)"]:::frontend

    UI -->|interacts via| STATE
    STATE -->|calls| SERVICE_LAYER

    click UI "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/main.dart"
    click UI "https://github.com/log4j-innovations/scrapbuddy/tree/main/lib/screens/"
    click UI "https://github.com/log4j-innovations/scrapbuddy/tree/main/lib/widgets/"
    click CONFIG "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/config/app_theme.dart"
  end

  %% Service Layer
  subgraph "Service Layer" 
    direction TB
    SERVICE_LAYER["Service Layer"]:::service

    VERTEX["Vertex AI Service\n(remote inference)"]:::service
    OFFLINE_CLASSIFY["Offline Classifier Service\n(on-device TFLite)"]:::service
    FIREBASE_SVC["Firebase Service\n(Auth, Firestore, Storage)"]:::service
    SARVAM["Sarvam AI TTS Service"]:::service
    OFFLINE_RES["Offline Resources\n(Shared Preferences, cached assets)"]:::service

    SERVICE_LAYER --> VERTEX
    SERVICE_LAYER --> OFFLINE_CLASSIFY
    SERVICE_LAYER --> FIREBASE_SVC
    SERVICE_LAYER --> SARVAM
    SERVICE_LAYER --> OFFLINE_RES

    click VERTEX "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/services/vertex_ai_service.dart"
    click VERTEX "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/config/api_config.dart"
    click VERTEX "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/config/api_keys_helper.dart"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/services/offline_classifier_service.dart"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/assets/models/model_unquant.tflite"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/assets/models/labels.txt"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/android/app/src/main/assets/model_unquant.tflite"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/android/app/src/main/assets/labels.txt"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/assets/tflite/model_unquant.tflite"
    click OFFLINE_CLASSIFY "https://github.com/log4j-innovations/scrapbuddy/blob/main/assets/tflite/labels.txt"
    click FIREBASE_SVC "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/services/firebase_service.dart"
    click FIREBASE_SVC "https://github.com/log4j-innovations/scrapbuddy/blob/main/pubspec.yaml"
    click FIREBASE_SVC "https://github.com/log4j-innovations/scrapbuddy/blob/main/ios/Runner/Info.plist"
    click FIREBASE_SVC "https://github.com/log4j-innovations/scrapbuddy/blob/main/ios/Runner/Runner-Bridging-Header.h"
    click SARVAM "https://github.com/log4j-innovations/scrapbuddy/blob/main/scripts/generate_audio.dart"
    click OFFLINE_RES "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/services/offline_resources.dart"
  end

  %% Localization
  subgraph "Localization & Intl" 
    direction TB
    LOCAL["App Localizations"]:::frontend
    EN["en.json"]:::frontend
    HI["hi.json"]:::frontend
    TA["ta.json"]:::frontend
    TE["te.json"]:::frontend

    LOCAL --> EN
    LOCAL --> HI
    LOCAL --> TA
    LOCAL --> TE

    click LOCAL "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/localization/app_localizations.dart"
    click EN "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/localization/en.json"
    click HI "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/localization/hi.json"
    click TA "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/localization/ta.json"
    click TE "https://github.com/log4j-innovations/scrapbuddy/blob/main/lib/localization/te.json"
  end

  %% Data Stores
  subgraph "Data Stores" 
    direction TB
    FIRESTORE[(Cloud Firestore)]:::datastore
    STORAGE[(Firebase Storage)]:::datastore
    LOCAL_STORAGE[(Local Storage\nShared Preferences)]:::datastore

    FIREBASE_SVC -->|Read/Write| FIRESTORE
    FIREBASE_SVC -->|Upload/Download| STORAGE
    OFFLINE_RES -->|Cache| LOCAL_STORAGE
  end

  %% External Services
  subgraph "External Services" 
    direction TB
    VAI[(Google Vertex AI)]:::external
    SARVAM_API[(Sarvam AI TTS)]:::external

    VERTEX -->|REST/gRPC| VAI
    SARVAM -->|TTS API| SARVAM_API
  end

  %% Platform Embeddings
  subgraph "Platform Embeddings" 
    direction TB
    ANDROID["android/"]:::frontend
    IOS["ios/"]:::frontend
    WEB["web/"]:::frontend
    LINUX["linux/"]:::frontend
    MACOS["macos/"]:::frontend
    WINDOWS["windows/"]:::frontend

    click ANDROID "https://github.com/log4j-innovations/scrapbuddy/tree/main/android/"
    click IOS "https://github.com/log4j-innovations/scrapbuddy/tree/main/ios/"
    click WEB "https://github.com/log4j-innovations/scrapbuddy/tree/main/web/"
    click LINUX "https://github.com/log4j-innovations/scrapbuddy/tree/main/linux/"
    click MACOS "https://github.com/log4j-innovations/scrapbuddy/tree/main/macos/"
    click WINDOWS "https://github.com/log4j-innovations/scrapbuddy/tree/main/windows/"
  end

  %% Build & Config
  subgraph "Build & Configuration" 
    direction TB
    PUBSPEC["pubspec.yaml"]:::frontend
    ANALYSIS["analysis_options.yaml"]:::frontend
    GRADLE["android/app/build.gradle"]:::frontend
    XCODE["ios/Runner.xcodeproj/"]:::frontend
    HTML["web/index.html"]:::frontend

    click PUBSPEC "https://github.com/log4j-innovations/scrapbuddy/blob/main/pubspec.yaml"
    click ANALYSIS "https://github.com/log4j-innovations/scrapbuddy/blob/main/analysis_options.yaml"
    click GRADLE "https://github.com/log4j-innovations/scrapbuddy/blob/main/android/app/build.gradle"
    click XCODE "https://github.com/log4j-innovations/scrapbuddy/tree/main/ios/Runner.xcodeproj/"
    click HTML "https://github.com/log4j-innovations/scrapbuddy/blob/main/web/index.html"
  end

  %% Styles
  classDef frontend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
  classDef service fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20;
  classDef datastore fill:#FFE0B2,stroke:#E65100,color:#E65100;
  classDef external fill:#E1BEE7,stroke:#4A148C,color:#4A148C;
```
