BloomWalls 🌸

A beautiful, feature-rich Flutter wallpaper application with user authentication, collections management, and seamless wallpaper application capabilities.

📋 Table of Contents

• Project Overview
• Features
• Architecture
• Technology Stack
• Project Structure
• Getting Started
• Installation
• Usage
• Code Organization
• Contributing

🎯 Project Overview

BloomWalls is a modern wallpaper discovery and management application built with Flutter. It provides users with an extensive collection of high-quality wallpapers, personalized collections (liked/saved), and the ability to set wallpapers directly on their device. The app features a beautiful Material Design 3 UI with dark mode support, smooth animations, and a seamless user experience.

Key Highlights:

• 🎨 Beautiful Material Design 3 interface
• 🌙 Dark and light theme support
• 🔐 Secure user authentication (Google & Email)
• 💾 Cloud-based user data persistence
• 📱 Cross-platform support (iOS, Android, Web, macOS, Windows, Linux)
• ⚡ Optimized image caching and loading
• 🎯 Staggered grid layout for wallpaper display

✨ Features

1. User Authentication

• Google Sign-In integration
• Email/Password registration and login
• Firebase-backed secure authentication
• Session persistence across app restarts

2. Wallpaper Discovery

• Browse extensive wallpaper collections
• Category-based browsing
• Curated feed/discovery screen
• Beautiful staggered grid layout
• Infinite scrolling capabilities

3. Wallpaper Management

• Like/Heart wallpapers
• Save wallpapers to collections
• View liked and saved wallpapers in profile
• Share wallpapers with others
• Wallpaper details and metadata display

4. Wallpaper Application

• Set wallpapers to home screen
• Set wallpapers to lock screen
• Set wallpapers to both home and lock screen
• One-click application process
• Automatic image optimization and caching

5. User Profile

• View user information
• Browse liked wallpapers
• Browse saved wallpapers
• Sign out functionality
• Protected content (requires authentication)

6. UI/UX Enhancements

• Smooth page transitions
• Floating bottom navigation bar
• Loading skeletons using shimmer effect
• Cached image loading
• Responsive design
• Material Design 3 components

🏗️ Architecture

BloomWalls follows a layered architecture pattern with clear separation of concerns:

┌─────────────────────────────────────────────┐
│          Presentation Layer                 │
│        (Screens & Widgets)                  │
└─────────────────────────────────────────────┘
                    ↑
┌─────────────────────────────────────────────┐
│        State Management Layer               │
│         (Provider Pattern)                  │
└─────────────────────────────────────────────┘
                    ↑
┌─────────────────────────────────────────────┐
│          Service Layer                      │
│  (API, Auth, Database Services)             │
└─────────────────────────────────────────────┘
                    ↑
┌─────────────────────────────────────────────┐
│          Data Layer                         │
│  (Firebase, External APIs)                  │
└─────────────────────────────────────────────┘

Design Patterns Used:

• Provider Pattern: Centralized state management using the Provider package
• Service Layer Pattern: Business logic encapsulated in service classes
• Model/View/Provider (MVP): Clean separation between UI and business logic
• Singleton Pattern: Services instantiated as singletons for consistency
• Factory Pattern: JSON serialization/deserialization using factory constructors

📚 Technology Stack

Framework & Language

• Framework: Flutter (latest stable)
• Language: Dart 3.11.3+
• Target SDK: iOS, Android, Web, macOS, Windows, Linux

State Management

• Provider: ^6.1.5+1 - For reactive state management and dependency injection

Authentication & Backend

• Firebase Core: ^4.9.0 - Firebase initialization
• Firebase Auth: ^6.5.1 - User authentication
• Google Sign-In: ^6.2.1 - Google OAuth integration
• Cloud Firestore: ^6.4.1 - Cloud database for user collections

API & Networking

• http: ^1.6.0 - HTTP client for REST API calls
• Wallpaper API: External API from https://walleee.vercel.app/api

UI & Styling

• Google Fonts: ^8.1.0 - Custom font typography
• Font Awesome Flutter: ^11.0.0 - Icon library
• Flutter Staggered Grid View: ^0.7.0 - Advanced grid layouts
• Shimmer: ^3.0.0 - Loading state animations

Image Handling & Device Features

• Cached Network Image: ^3.4.1 - Optimized image caching and loading
• Async Wallpaper: ^3.1.0 - Set wallpapers on device
• Share Plus: ^10.0.0 - Share wallpapers with other apps

Development Tools

• Flutter Lints: ^6.0.0 - Code quality and style checking

📁 Project Structure

lib/
├── main.dart                          # Application entry point
├── theme.dart                         # Custom theme configuration (Material Design 3)
│
├── models/
│   └── wallpaper.dart                 # Wallpaper data model
│
├── services/
│   ├── auth_service.dart              # Firebase authentication logic
│   ├── api_service.dart               # External wallpaper API integration
│   └── firestore_service.dart         # Cloud Firestore database operations
│
├── providers/
│   └── wallpaper_provider.dart        # Provider for wallpaper state management
│
├── screens/
│   ├── auth_screen.dart               # Login/Registration screen
│   ├── email_auth_screen.dart         # Email-based authentication
│   ├── main_screen.dart               # Main navigation container
│   ├── home_screen.dart               # Featured wallpapers home
│   ├── categories_screen.dart         # Wallpaper categories browsing
│   ├── bloomwalls_feed_screen.dart    # Discovery/Feed screen
│   ├── profile_screen.dart            # User profile and collections
│   ├── wallpaper_preview_screen.dart  # Wallpaper detail/preview view
│   ├── saved_screen.dart              # Saved wallpapers collection
│   └── category_wallpapers_screen.dart # Category-specific wallpapers
│
├── widgets/
│   ├── wallpaper_grid.dart            # Reusable wallpaper grid component
│   ├── wallpaper_interactions.dart    # Like/Save/Share interactions
│   └── skeleton_loader.dart           # Shimmer loading skeleton
│
test/
└── [Test files]

android/                               # Android-specific configuration
ios/                                   # iOS-specific configuration
web/                                   # Web build support
macos/                                 # macOS build support
windows/                               # Windows build support
linux/                                 # Linux build support

pubspec.yaml                           # Project dependencies and configuration
analysis_options.yaml                  # Dart linting rules

🚀 Getting Started

Prerequisites

• Flutter SDK (latest stable version)
• Dart 3.11.3 or higher
• Android Studio / Xcode (for mobile development)
• Firebase project setup
• Git

System Requirements

• Minimum iOS: 11.0
• Minimum Android: API level 21
• Sufficient storage for wallpaper caching (image cache set to 300MB max)

📦 Installation

1. Clone the Repository

git clone https://github.com/Kolass2004/BloomWalls.git
cd BloomWalls

2. Install Flutter Dependencies

flutter pub get

3. Firebase Setup

1. Create a Firebase project at Firebase Console
2. Enable Authentication methods:
   • Email/Password
   • Google Sign-In
3. Create a Firestore database
4. Download and configure Firebase config files:
   • For Android: google-services.json → android/app/
   • For iOS: GoogleService-Info.plist → ios/Runner/

4. Build & Run

# Run on connected device/emulator
flutter run

# Run on specific device
flutter run -d <device-id>

# Run with specific flavor
flutter run --flavor production

# Build APK (Android)
flutter build apk

# Build AAB (Android Play Store)
flutter build appbundle

# Build IPA (iOS)
flutter build ios

# Build for web
flutter build web

💡 Usage

Launching the App

1. Authentication: Start by signing in with Google or creating an account with email/password
2. Browse: Explore wallpapers in Home, Categories, or Feed sections
3. Preview: Tap any wallpaper to see full preview and details
4. Apply: Choose to set as home, lock, or both screens
5. Manage: Like/Save wallpapers and access them from your Profile

Main Navigation

• Home (House icon): Featured and trending wallpapers
• Categories (Grid icon): Browse wallpapers by category
• Feed (Flame icon): Discover curated wallpaper feed
• Profile (User icon): View liked/saved wallpapers and account settings

Interaction Patterns

• Like: Heart icon to like wallpapers (stored in Firestore)
• Save: Bookmark icon to save wallpapers for later
• Share: Share button to send wallpapers to other apps
• Apply: One-tap application to device screens

📖 Code Organization

Key Components

Models (lib/models/)

• Wallpaper.dart: Represents a single wallpaper with metadata
  • Properties: id, publicId, url, thumbnailUrl, width, height, format, tags, title
  • Methods: JSON serialization/deserialization, grid thumbnail URL optimization

Services (lib/services/)

• AuthService.dart: Firebase authentication management

  • Methods: signInWithGoogle(), signInWithEmailAndPassword(), registerWithEmailAndPassword(), signOut()
  • Extends ChangeNotifier for reactive updates

• ApiService.dart: External wallpaper API communication

  • Fetches wallpapers from https://walleee.vercel.app/api/wallpapers
  • Handles JSON parsing and error handling

• FirestoreService.dart: Cloud database operations

  • Like wallpapers: likeWallpaper(), unlikeWallpaper(), getLikedWallpapers(), isLiked()
  • Save wallpapers: saveWallpaper(), unsaveWallpaper(), getSavedWallpapers(), isSaved()
  • User document management

Providers (lib/providers/)

• WallpaperProvider.dart: State management for wallpaper data
  • Properties: wallpapers list, loading state, error messages
  • Methods: fetchWallpapers() with shuffling

Screens (lib/screens/)

• All screens follow a stateful/stateless widget pattern
• Utilize Provider for state access
• Implement responsive layouts
• Support both light and dark themes

Widgets (lib/widgets/)

• WallpaperGrid.dart: Reusable staggered grid component
• WallpaperInteractions.dart: Like, save, share interactions
• SkeletonLoader.dart: Shimmer loading placeholders

Theme (lib/theme.dart)

• Custom Material Design 3 theme
• Colors: Primary (reddish-brown), Secondary (light blue), Tertiary (alice blue)
• Typography: Google Fonts (Plus Jakarta Sans for headers, Manrope for body)
• Both light and dark theme definitions

Image Caching Strategy

• Image cache size: 300MB (configured in main.dart)
• Maximum cached images: 500
• Uses CachedNetworkImage for efficient loading
• Grid thumbnails optimized to 400px width
• Full resolution images available on demand

Performance Optimizations

• Staggered grid layout reduces rendering overhead
• IndexedStack preserves screen state during navigation
• Image cache presets prevent repeated network calls
• Shimmer loaders provide perceived performance improvement
• Firebase connection pooling for Firestore operations

🔐 Security Considerations

1. Authentication: Firebase handles secure authentication
2. Data Privacy: Firestore security rules should be configured (not shown in code)
3. API Keys: Firebase config files excluded from version control (.gitignore)
4. Image URLs: Cloudinary-hosted images with automatic optimization
5. User Data: Stored in user-specific Firestore collections

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Code Style

• Follow Dart conventions
• Use meaningful variable names
• Add comments for complex logic
• Keep methods focused and single-responsibility
• Use const constructors where possible

Testing

flutter test

📄 License

This project is private. All rights reserved.

🔗 Resources

• Flutter Documentation
• Firebase Documentation
• Provider Package
• Material Design 3
• Dart Documentation

📧 Contact & Support

For issues, questions, or suggestions, please open an issue on GitHub or contact the project maintainers.

---

Last Updated: May 18, 2026
Version: 1.0.0
Flutter Version: Latest Stable
Dart Version: 3.11.3+