🚀 Grex

A production-ready Grex project with Clean Architecture, enterprise-grade configuration management, and comprehensive developer tooling.

✨ Features

🏗️ Architecture & Code Quality

✅ Clean Architecture - Separation of concerns with Domain, Data, and Presentation layers
✅ State Management - BLoC pattern for reactive state management
✅ Code Generation - Freezed for immutable classes and JSON serialization
✅ Linting - Very Good Analysis for comprehensive code quality checks
✅ Testing - Comprehensive test coverage with 87 property-based tests (100+ iterations each)

⚙️ Configuration & Environment

✅ Multi-Environment Support - Development, Staging, Production
✅ Flexible Configuration - .env files for local dev, --dart-define for CI/CD
✅ Feature Flags - Local and remote (Firebase Remote Config) feature flags
✅ Environment-Aware Defaults - Smart defaults based on environment
✅ Type-Safe Configuration - Typed getters with fallback chain

🌐 Internationalization

✅ Multi-Language Support - English, Vietnamese, Spanish, Arabic
✅ RTL Support - Right-to-left language support for Arabic
✅ Locale Persistence - Save and restore user language preference
✅ Standardized Localization - Context extension for easy access (context.l10n)

🔐 Security & Storage

✅ Secure Storage - Flutter Secure Storage for sensitive data
✅ Shared Preferences - Simple key-value storage for non-sensitive data
✅ Storage Migration - Version-based storage migration system
✅ Error Handling - Comprehensive error handling with custom exceptions

🔐 Authentication & Social Login

✅ Email/Password Authentication - Complete auth system with email verification
✅ Social Login - Google OAuth and Apple Sign In integration (98% complete)
✅ Account Linking - Link social providers to existing accounts
✅ Profile Setup - Guided profile completion for new social users
✅ Deep Link Handling - OAuth callback processing with performance optimization
✅ Session Management - Persistent sessions across app restarts
✅ Security Compliance - HTTPS-only, minimal scopes, secure token storage

💰 Expense Sharing Features

✅ Group Management - Create and manage expense groups with role-based permissions
✅ Expense Tracking - Record expenses with 4 split methods (equal, percentage, exact, shares)
✅ Payment Recording - Track payments between group members
✅ Balance Calculation - Real-time balance calculations with settlement plan generation
✅ Data Export - Export group data in CSV/PDF formats
✅ Search & Filter - Advanced search and filtering across expenses

🌐 Network Layer

✅ HTTP Client - Dio with interceptors support
✅ Configurable Timeouts - Environment-based timeout configuration
✅ Request/Response Logging - Debug-friendly HTTP logging
✅ Error Interceptors - Automatic error handling and conversion
✅ Auth Interceptors - Automatic token injection and refresh

🎨 UI & UX

✅ Material Design - Material 3 theme support
✅ Dark Mode - Built-in dark theme support
✅ Accessibility - Semantic labels and accessibility support
✅ Responsive Design - Adaptive layouts for different screen sizes

🧭 Routing & Navigation

✅ Type-Safe Routing - GoRouter with type-safe route definitions
✅ Deep Linking - Support for deep links and URL navigation
✅ Auth-Based Routing - Protected routes with authentication redirects
✅ Navigation Logging - Automatic route tracking and logging

📊 Logging & Monitoring

✅ Comprehensive Logging - Multi-level logging with file and console output
✅ Log Rotation - Automatic log file rotation
✅ Structured Logging - JSON formatting for production
✅ Performance Monitoring - Firebase Performance integration
✅ Screen Tracking - Automatic screen load time tracking

🚀 Deployment & CI/CD

✅ Multi-Platform - Android, iOS, Web, Linux, macOS, Windows support
✅ CI/CD Ready - GitHub Actions workflows included (disabled by default, uncomment triggers to enable)
✅ Version Management - Automated version bumping scripts
✅ Fastlane Integration - iOS and Android deployment automation

📚 Documentation

✅ Comprehensive Docs - Architecture, guides, API documentation
✅ Migration Guides - From MVC, GetX, Bloc, and other architectures
✅ Best Practices - Code examples and patterns
✅ API Documentation - Complete API reference
✅ Example Features - Complete features demonstrating Clean Architecture (Auth, Groups, Expenses, Balances, etc.)

🧪 Testing

✅ 66 Test Files - Comprehensive test coverage
✅ Unit Tests - Domain and data layer testing
✅ Widget Tests - UI component testing
✅ Integration Tests - End-to-end flow testing
✅ Test Helpers - Reusable test utilities and fixtures

🛠️ Tech Stack

Core Dependencies

Flutter - UI framework
Riverpod - State management
Dio - HTTP client
Freezed - Code generation for immutable classes
Equatable - Value equality comparison

Firebase

Firebase Core - Firebase initialization
Firebase Remote Config - Remote feature flags
Firebase Performance - Performance monitoring and tracking

Storage

flutter_secure_storage - Secure storage for sensitive data
shared_preferences - Simple key-value storage

Localization

flutter_localizations - Flutter localization support
intl - Internationalization utilities

Routing & Navigation

go_router - Declarative routing with deep linking

Logging & Monitoring

logger - Comprehensive logging solution
path_provider - File system access for log files

Development Tools

build_runner - Code generation runner
very_good_analysis - Linting rules
mocktail - Testing and mocking

📁 Project Structure

lib/
├── core/                    # Core infrastructure
│   ├── config/             # Configuration system
│   ├── constants/          # App constants
│   ├── di/                 # Dependency injection (Riverpod providers)
│   ├── errors/             # Error handling
│   ├── feature_flags/      # Feature flags infrastructure
│   ├── localization/       # Localization service
│   ├── logging/            # Logging service
│   ├── network/            # Network layer (Dio setup)
│   ├── performance/        # Performance monitoring
│   ├── routing/            # Routing system (go_router)
│   ├── storage/            # Storage services (with migration)
│   └── utils/              # Utility functions
│
├── features/                # Feature modules (Clean Architecture)
│   ├── auth/               # Authentication feature with social login
│   │   ├── data/          # Data layer (models, data sources, repositories)
│   │   │   ├── handlers/  # OAuth deep link handlers
│   │   │   ├── models/    # User, profile, social auth models
│   │   │   └── repositories/ # Social auth and user repositories
│   │   ├── domain/        # Domain layer (entities, use cases, repository interfaces)
│   │   │   ├── entities/  # User, SocialAuthProvider, ProfileSetupData
│   │   │   └── repositories/ # SocialAuthRepository interface
│   │   └── presentation/  # Presentation layer (screens, widgets, providers)
│   │       ├── pages/     # Login, register, profile setup pages
│   │       └── widgets/   # Social login buttons, dialogs, error widgets
│   ├── feature_flags/      # Feature flags feature
│   │   └── presentation/   # Feature flags UI
│   ├── groups/             # Group management
│   ├── expenses/           # Expense tracking
│   ├── payments/           # Built-in payments tracking
│   ├── balances/           # Balance calculation engine
│   └── export/             # Data export utilities
│
├── shared/                  # Shared resources
│   ├── accessibility/      # Accessibility utilities
│   ├── extensions/         # Dart extensions
│   ├── theme/              # App theme configuration
│   └── widgets/            # Reusable widgets
│
├── l10n/                   # Localization files (generated)
└── main.dart               # App entry point

🚀 Getting Started

Prerequisites

Flutter SDK (>=3.0.0)
Dart SDK (>=3.0.0)
Android Studio / VS Code with Flutter extensions
Xcode (for iOS development on macOS)

Local Development with Supabase

For fully offline development using a local Supabase instance:

Install Supabase CLI
```
npm install -g supabase
```
Start local Supabase
```
supabase start
```
The CLI will print the API URL and anon key once running.

Configure .env for local

ENVIRONMENT=development
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=<anon key from supabase start output>

The default anon key is already available in .env.example under SUPABASE_LOCAL_ANON_KEY.

Apply migrations (if any)
```
supabase db reset
```
Run the app
```
flutter run
```
Stop local Supabase when done
```
supabase stop
```

Note: When using Android Emulator, replace localhost with 10.0.2.2:
SUPABASE_URL=http://10.0.2.2:54321

Installation

Create repository from template (if using GitHub template)
- Click "Use this template" button on GitHub
- Create a new repository from this template
- Clone your new repository:
```
git clone <your-repository-url>
cd <your-project-name>
```
OR clone directly (if not using template):
```
git clone <repository-url>
cd grex
```
Install dependencies
```
flutter pub get
```

Generate code (Freezed, JSON serialization)

flutter pub run build_runner build --delete-conflicting-outputs

Set up environment configuration

# Copy the example environment file
cp .env.example .env

# Edit .env with your configuration
# See Configuration System section below

Set up Git hooks (optional but recommended)

Linux/macOS:
```
./scripts/linux/development/setup-git-hooks.sh
```
Windows:
```
.\scripts\windows\development\setup-git-hooks.ps1
```
This will install Git hooks for:
- Code formatting checks (pre-commit)
- Commit message validation (commit-msg)
- Test execution (pre-push)
Run the app
```
flutter run
```

Social Login Setup

The app includes comprehensive social login integration with Google OAuth and Apple Sign In.

OAuth Provider Configuration

Google OAuth Setup:
- Create OAuth 2.0 Client ID in Google Cloud Console
- Add authorized redirect URIs: https://[project-id].supabase.co/auth/v1/callback
- Configure in Supabase Dashboard → Authentication → Providers
Apple Sign In Setup:
- Create Services ID in Apple Developer Portal
- Configure Sign In with Apple
- Generate private key (.p8 file)
- Configure in Supabase Dashboard → Authentication → Providers

Deep Link Configuration

Android (android/app/src/main/AndroidManifest.xml):

<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="io.supabase.grex"
          android:host="login-callback" />
</intent-filter>

iOS (ios/Runner/Info.plist):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>io.supabase.grex</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>io.supabase.grex</string>
        </array>
    </dict>
</array>

Features

OAuth Integration: Google and Apple OAuth with external browser launch
Account Linking: Link social providers to existing email accounts
Profile Setup: Guided profile completion for new social users
Deep Link Handling: Fast OAuth callback processing (< 1 second)
Session Management: Persistent sessions with automatic refresh
Error Handling: User-friendly error messages with retry options
Localization: Multi-language support for all social login UI
Security: HTTPS-only, minimal scopes, secure token storage
Performance: OAuth flow completion < 5 seconds after authorization

For detailed implementation guide, see Social Login Developer Guide.

First Steps

Rename the project (if needed) - Update package name from grex to your project name
Configure your environment - See Configuration System below
Set up Firebase (optional) - For remote feature flags and performance monitoring
- Add google-services.json (Android) and GoogleService-Info.plist (iOS)
- Initialize Firebase in your app
Customize the theme - Edit lib/shared/theme/app_theme.dart
Explore example features - Check out lib/features/ for examples:
- Auth - Authentication flow with social login
- Groups & Expenses - Core expense sharing implementation
- Feature Flags - Conditional UI rendering based on flags
Add your first feature - Follow the pattern in example features
Read the documentation - Check out docs/ folder for detailed guides

⚙️ Configuration System

This project includes a production-ready, multi-environment configuration system that supports:

Local Development: .env files for easy local configuration
CI/CD: --dart-define flags for build-time configuration
Fallback Chain: .env → --dart-define → defaults
Environment-Aware Defaults: Different configurations per environment
Feature Flags: Enable/disable features per environment
Network Configuration: Timeout settings for API calls
Debug Utilities: Tools for inspecting configuration

Architecture

The configuration system consists of two main classes:

EnvConfig (lib/core/config/env_config.dart): Low-level environment variable loader
- Loads from .env files using flutter_dotenv
- Reads from --dart-define flags
- Provides fallback chain: .env → --dart-define → defaults
AppConfig (lib/core/config/app_config.dart): High-level application configuration
- Uses EnvConfig to get values
- Provides typed getters (String, bool, int)
- Environment-aware defaults
- Feature flags
- Network timeout configuration
- Debug utilities

Setup

1. Create `.env` file for local development

# Copy the example file
cp .env.example .env

# Edit .env with your values
# The .env file is gitignored and won't be committed

2. Configure your environment variables

Edit .env with your configuration:

ENVIRONMENT=development
BASE_URL=http://localhost:3000
ENABLE_LOGGING=true
ENABLE_ANALYTICS=false

Usage Examples

Local Development (using `.env` file)

Create .env file from .env.example
Fill in your values
Run the app normally:

flutter run

The app will automatically load values from .env.

Staging Build (using `--dart-define`)

For CI/CD or when you don't want to use .env files:

flutter run \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=BASE_URL=https://api-staging.example.com \
  --dart-define=ENABLE_ANALYTICS=true

Production Build (using `--dart-define`)

flutter build apk \
  --dart-define=ENVIRONMENT=production \
  --dart-define=BASE_URL=https://api.example.com \
  --dart-define=ENABLE_ANALYTICS=true \
  --dart-define=ENABLE_CRASH_REPORTING=true

Using Configuration in Code

Basic Usage

import 'package:grex/core/config/app_config.dart';

// Get environment
final env = AppConfig.environment; // 'development', 'staging', or 'production'

// Check environment
if (AppConfig.isDevelopment) {
  // Development-specific code
}

// Get API base URL
final baseUrl = AppConfig.baseUrl;

// Check feature flags
if (AppConfig.enableLogging) {
  logger.info('App started');
}

if (AppConfig.enableAnalytics) {
  analytics.trackEvent('app_opened');
}

Network Configuration

import 'package:grex/core/config/app_config.dart';
import 'package:dio/dio.dart';

final dio = Dio(
  BaseOptions(
    baseUrl: AppConfig.baseUrl,
    connectTimeout: Duration(seconds: AppConfig.apiConnectTimeout),
    receiveTimeout: Duration(seconds: AppConfig.apiReceiveTimeout),
    sendTimeout: Duration(seconds: AppConfig.apiSendTimeout),
  ),
);

Debug Utilities

import 'package:grex/core/config/app_config.dart';

// Print configuration to console (only in debug mode)
AppConfig.printConfig();

// Get configuration as a map
final config = AppConfig.getDebugInfo();
print(config);

Available Configuration Options

Environment Variables

Variable	Type	Default	Description
`ENVIRONMENT`	String	`development`	Environment name: `development`, `staging`, or `production`
`BASE_URL`	String	Environment-aware	API base URL (see defaults below)
`API_TIMEOUT`	int	`30`	API timeout in seconds
`API_CONNECT_TIMEOUT`	int	`10`	API connect timeout in seconds
`API_RECEIVE_TIMEOUT`	int	`30`	API receive timeout in seconds
`API_SEND_TIMEOUT`	int	`30`	API send timeout in seconds
`ENABLE_LOGGING`	bool	Environment-aware	Enable logging (default: true in dev/staging)
`ENABLE_ANALYTICS`	bool	Environment-aware	Enable analytics (default: true in staging/prod)
`ENABLE_CRASH_REPORTING`	bool	Environment-aware	Enable crash reporting (default: true in staging/prod)
`ENABLE_PERFORMANCE_MONITORING`	bool	Environment-aware	Enable performance monitoring (default: true in staging/prod)
`ENABLE_DEBUG_FEATURES`	bool	Environment-aware	Enable debug features (default: true in dev)
`ENABLE_HTTP_LOGGING`	bool	Environment-aware	Enable HTTP request/response logging (default: true in dev)
`APP_VERSION`	String	`0.0.1`	App version
`APP_BUILD_NUMBER`	String	`1`	App build number

Environment-Aware Defaults

BASE_URL defaults:

Development: http://localhost:3000
Staging: https://api-staging.example.com
Production: https://api.example.com

Feature Flag defaults:

Logging: Enabled in development and staging
Analytics: Enabled in staging and production
Crash Reporting: Enabled in staging and production
Performance Monitoring: Enabled in staging and production
Debug Features: Enabled in development only
HTTP Logging: Enabled in development only

Best Practices

Never commit .env files: They contain sensitive information and are gitignored
Use .env.example as a template: Commit this file with placeholder values
Use .env for local development: Easy to change values without rebuilding
Use --dart-define for CI/CD: More secure and doesn't require file management
Set environment-specific defaults: Let the system handle defaults based on environment
Use feature flags: Enable/disable features per environment without code changes

Troubleshooting

Configuration not loading

Ensure EnvConfig.load() is called in main() before runApp()
Check that .env file exists in the project root
Verify pubspec.yaml includes .env in assets
Run flutter pub get after adding flutter_dotenv

Values not updating

Hot reload doesn't reload environment variables - do a full restart
For --dart-define values, rebuild the app
Check that you're using the correct variable name (case-sensitive)

Debug configuration

Use AppConfig.printConfig() in debug mode to see all configuration values:

if (AppConfig.isDebugMode) {
  AppConfig.printConfig();
}

This will print all configuration values to the console, helping you verify what values are being used.

🧪 Testing

Run Tests

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/features/auth/domain/usecases/login_test.dart

Test Structure

Tests follow the same structure as the source code:

66 test files with comprehensive coverage
Unit tests for use cases and utilities
Widget tests for UI components
Integration tests for end-to-end flows
Property-based tests for social login (35 properties with 100+ iterations each)
Test helpers and fixtures for reusable test utilities

Social Login Testing

The social login feature includes extensive testing:

# Run social login tests specifically
flutter test test/features/auth/data/repositories/social_auth_repository_test.dart
flutter test test/features/auth/presentation/widgets/social_login_button_test.dart

# Run property-based tests (100+ iterations each)
flutter test test/features/auth/property_tests/

Property Tests Include:

OAuth flow completion within performance requirements
Profile setup data preservation
Account linking detection and handling
Session persistence across app restarts
Error handling for all failure scenarios

Test Coverage

The project includes:

✅ Domain layer tests (use cases, entities)
✅ Data layer tests (repositories, data sources, models)
✅ Presentation layer tests (screens, widgets, providers)
✅ Core infrastructure tests (config, network, storage, logging, performance)
✅ Integration tests for complete flows

🏗️ Building

Android

# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release

# App Bundle (for Play Store)
flutter build appbundle --release

iOS

# Debug
flutter build ios --debug

# Release
flutter build ios --release

Web

# Debug
flutter build web --debug

# Release
flutter build web --release

📚 Documentation

Architecture

Architecture Documentation - Complete architecture documentation index
Architecture Overview - Why Clean Architecture, benefits, trade-offs, and learning resources
Design Decisions - Detailed rationale for routing, state management, error handling, logging, storage, and HTTP client choices

Guides

Getting Started - Step-by-step setup guide
Understanding the Codebase - Architecture and patterns
Common Tasks - Frequently performed tasks
Routing Guide - GoRouter navigation and deep linking
Git Hooks Setup - Setup Git hooks for code quality (similar to Husky)
Adding Features - How to add new features

Migration Guides

Features

Social Login - Complete social login implementation guide
Feature Flags - Feature flags system documentation
[Expense Sharing Engine] - Core sharing models
- Groups - Group management
- Expenses - Expense tracking
- Balances - Real-time calculation engine
- Payments - P2P payment tracking
- Export - Data export utilities
Localization - i18n setup and usage
Logging - Logging system documentation
Performance - Performance monitoring guides
Routing - Routing and navigation guide

Deployment

Deployment Guide - Complete deployment documentation
Quick Start - Get started in 5 minutes
Android Deployment - Android-specific guide
iOS Deployment - iOS-specific guide
Web Deployment - Web-specific guide
Release Process - Version management and releases
Monitoring & Analytics - Crashlytics and analytics setup

API Documentation

API Overview - API documentation index
Examples - Code examples and patterns

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

How to report bugs
How to suggest enhancements
Development setup and workflow
Coding standards and guidelines
Testing requirements
Commit message conventions

Quick Start

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes following our coding standards
Write or update tests
Commit your changes using conventional commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

For detailed guidelines, please read CONTRIBUTING.md.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Flutter - The framework
Riverpod - State management
Very Good Ventures - Linting rules and best practices
Freezed - Code generation

📞 Support

For questions, issues, or contributions, please open an issue on GitHub.

Made with ❤️ using Flutter

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.claude		.claude
.github/workflows		.github/workflows
.vscode		.vscode
android		android
assets		assets
designs		designs
docs		docs
fastlane		fastlane
integration_test		integration_test
ios		ios
lib		lib
linux		linux
macos		macos
scripts		scripts
supabase		supabase
test		test
tool		tool
web		web
windows		windows
.env.example		.env.example
.firebaserc		.firebaserc
.gitignore		.gitignore
.metadata		.metadata
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
analysis_options.yaml		analysis_options.yaml
codecov.yml		codecov.yml
devtools_options.yaml		devtools_options.yaml
firebase.json		firebase.json
flutter_launcher_icons.yaml		flutter_launcher_icons.yaml
l10n.yaml		l10n.yaml
pubspec.lock		pubspec.lock
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation

🚀 Grex

✨ Features

🏗️ Architecture & Code Quality

⚙️ Configuration & Environment

🌐 Internationalization

🔐 Security & Storage

🔐 Authentication & Social Login

💰 Expense Sharing Features

🌐 Network Layer

🎨 UI & UX

🧭 Routing & Navigation

📊 Logging & Monitoring

🚀 Deployment & CI/CD

📚 Documentation

🧪 Testing

🛠️ Tech Stack

Core Dependencies

Firebase

Storage

Localization

Routing & Navigation

Logging & Monitoring

Development Tools

📁 Project Structure

🚀 Getting Started

Prerequisites

Local Development with Supabase

Installation

Social Login Setup

OAuth Provider Configuration

Deep Link Configuration

Features

First Steps

⚙️ Configuration System

Architecture

Setup

1. Create .env file for local development

2. Configure your environment variables

Usage Examples

Local Development (using .env file)

Staging Build (using --dart-define)

Production Build (using --dart-define)

Using Configuration in Code

Basic Usage

Network Configuration

Debug Utilities

Available Configuration Options

Environment Variables

Environment-Aware Defaults

Best Practices

Troubleshooting

Configuration not loading

Values not updating

Debug configuration

🧪 Testing

Run Tests

Test Structure

Social Login Testing

Test Coverage

🏗️ Building

Android

iOS

Web

📚 Documentation

Architecture

Guides

Migration Guides

Features

Deployment

API Documentation

🤝 Contributing

Quick Start

📝 License

🙏 Acknowledgments

📞 Support

About

1. Create `.env` file for local development

Local Development (using `.env` file)

Staging Build (using `--dart-define`)

Production Build (using `--dart-define`)

Packages