A modern, feature-rich mobile application for organizing Secret Santa gift exchanges. Built with Flutter and Firebase, this app makes coordinating gift exchanges easy and fun!
- 🔐 Secure Authentication - Email and Password login powered by Firebase Authentication
- 👥 Create & Manage Groups - Organize Secret Santa groups with friends and family
- 🎁 Smart Matching - (Upcoming) Automatic Secret Santa pair matching algorithm
- 💬 Real-time Updates - Instant synchronization across devices using Firestore
- 🌍 Multi-language Support - Support for multiple languages (i18n)
- 🎨 Dark & Light Themes - Adaptive UI with system theme support
- 📱 Cross-platform - Available on iOS, Android, Web, Windows, macOS, and Linux
- 🚀 State Management - Clean architecture with BLoC pattern
- 📦 Component Library - Pre-built UI components with Widgetbook documentation
- Framework: Flutter 3.7+
- Language: Dart 3.7+
- State Management: BLoC Pattern with flutter_bloc
- Routing: GoRouter for navigation
- UI Components: Widgetbook for component documentation
- Backend: Firebase
- Authentication: Firebase Auth (Email/Password)
- Database: Cloud Firestore
- Realtime: Real-time synchronization
- Localization: intl & flutter_localizations
- Dependency Injection: GetIt
- Functional Programming: fpdart (Functional Programming Dart)
- Code Generation: build_runner
lib/
├── main.dart # Application entry point
├── firebase_options.dart # Firebase configuration
├── injection_container.dart # Dependency injection setup
├── core/ # Core functionality
│ ├── enums/ # Enums used across app
│ ├── errors/ # Error handling
│ ├── extensions/ # Dart extensions
│ ├── l10n/ # Localization
│ ├── router/ # Navigation routes
│ ├── theme/ # App theming
│ └── utils/ # Utility functions
├── features/ # Feature modules
│ ├── auth/ # Authentication feature
│ ├── groups/ # Groups management
│ └── home/ # Home screen
└── assets/ # Images, fonts, etc.
- Flutter SDK 3.7+ (Install Flutter)
- Dart 3.7+
- Firebase project setup
-
Clone the repository
git clone https://github.com/yourusername/secret-santa.git cd secret-santa -
Get Flutter dependencies
flutter pub get
-
Configure Firebase
- Create a Firebase project on Firebase Console
- Download your
google-services.json(Android) andGoogleService-Info.plist(iOS) - Place them in the appropriate directories:
- Android:
android/app/ - iOS:
ios/Runner/
- Android:
-
Run code generation
flutter pub run build_runner build
-
Run the app
flutter run
iOS
flutter run -d iphoneAndroid
flutter run -d androidWeb
flutter run -d chromeWindows/macOS/Linux
flutter run -d windows # or macos, linuxWatch for changes and rebuild
flutter runBuild APK (Android)
flutter build apkBuild IPA (iOS)
flutter build iosBuild release
flutter build webWidgetbook - Component Library
cd widgetbook
flutter run -d chromeThis project follows Clean Architecture principles with clear separation of concerns:
Feature Module
├── Data Layer
│ ├── datasources (local, remote)
│ ├── models
│ └── repositories
├── Domain Layer
│ ├── entities
│ ├── repositories (interfaces)
│ └── usecases
└── Presentation Layer
├── bloc
├── pages
└── widgets
Key Patterns:
- BLoC Pattern for state management
- Dependency Injection with GetIt
- Functional Programming with fpdart for error handling
- Repository Pattern for data access
- Equatable for value equality
- Go to Firebase Console
- Create a new project or use existing one
- Enable Authentication methods:
- Email/Password
- Create Firestore Database:
- Collections:
groups,users,pairings - Set appropriate security rules
- Collections:
- Download config files and add to project
- Follow Dart Style Guide
- Run
flutter analyzeto check code quality - Use
dart formatto format code