{"id":51383715,"url":"https://github.com/koniz-dev/grex","last_synced_at":"2026-07-03T18:11:20.604Z","repository":{"id":328123225,"uuid":"1112413758","full_name":"koniz-dev/grex","owner":"koniz-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-21T16:07:18.000Z","size":14468,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-21T23:48:27.447Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/koniz-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/data_privacy_measures.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-08T15:37:26.000Z","updated_at":"2026-05-21T16:07:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/koniz-dev/grex","commit_stats":null,"previous_names":["koniz-dev/grex"],"tags_count":0,"template":false,"template_full_name":"koniz-dev/flutter-starter","purl":"pkg:github/koniz-dev/grex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koniz-dev%2Fgrex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koniz-dev%2Fgrex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koniz-dev%2Fgrex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koniz-dev%2Fgrex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/koniz-dev","download_url":"https://codeload.github.com/koniz-dev/grex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/koniz-dev%2Fgrex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35096188,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-03T18:11:20.002Z","updated_at":"2026-07-03T18:11:20.581Z","avatar_url":"https://github.com/koniz-dev.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 Grex\n\nA production-ready Grex project with **Clean Architecture**, enterprise-grade configuration management, and comprehensive developer tooling.\n\n[![Flutter](https://img.shields.io/badge/Flutter-3.0+-02569B?logo=flutter)](https://flutter.dev)\n[![Dart](https://img.shields.io/badge/Dart-3.0+-0175C2?logo=dart)](https://dart.dev)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Tests](https://img.shields.io/badge/tests-66%20files-success)](test/)\n[![Architecture](https://img.shields.io/badge/architecture-Clean%20Architecture-blue)](docs/architecture/)\n[![codecov](https://codecov.io/gh/koniz-dev/grex/graph/badge.svg?token=WJ4JJ4D20V)](https://codecov.io/gh/koniz-dev/grex)\n\n## ✨ Features\n\n### 🏗️ Architecture \u0026 Code Quality\n- ✅ **Clean Architecture** - Separation of concerns with Domain, Data, and Presentation layers\n- ✅ **State Management** - BLoC pattern for reactive state management\n- ✅ **Code Generation** - Freezed for immutable classes and JSON serialization\n- ✅ **Linting** - Very Good Analysis for comprehensive code quality checks\n- ✅ **Testing** - Comprehensive test coverage with 87 property-based tests (100+ iterations each)\n\n### ⚙️ Configuration \u0026 Environment\n- ✅ **Multi-Environment Support** - Development, Staging, Production\n- ✅ **Flexible Configuration** - `.env` files for local dev, `--dart-define` for CI/CD\n- ✅ **Feature Flags** - Local and remote (Firebase Remote Config) feature flags\n- ✅ **Environment-Aware Defaults** - Smart defaults based on environment\n- ✅ **Type-Safe Configuration** - Typed getters with fallback chain\n\n### 🌐 Internationalization\n- ✅ **Multi-Language Support** - English, Vietnamese, Spanish, Arabic\n- ✅ **RTL Support** - Right-to-left language support for Arabic\n- ✅ **Locale Persistence** - Save and restore user language preference\n- ✅ **Standardized Localization** - Context extension for easy access (`context.l10n`)\n\n### 🔐 Security \u0026 Storage\n- ✅ **Secure Storage** - Flutter Secure Storage for sensitive data\n- ✅ **Shared Preferences** - Simple key-value storage for non-sensitive data\n- ✅ **Storage Migration** - Version-based storage migration system\n- ✅ **Error Handling** - Comprehensive error handling with custom exceptions\n\n### 🔐 Authentication \u0026 Social Login\n- ✅ **Email/Password Authentication** - Complete auth system with email verification\n- ✅ **Social Login** - Google OAuth and Apple Sign In integration (98% complete)\n- ✅ **Account Linking** - Link social providers to existing accounts\n- ✅ **Profile Setup** - Guided profile completion for new social users\n- ✅ **Deep Link Handling** - OAuth callback processing with performance optimization\n- ✅ **Session Management** - Persistent sessions across app restarts\n- ✅ **Security Compliance** - HTTPS-only, minimal scopes, secure token storage\n\n### 💰 Expense Sharing Features\n- ✅ **Group Management** - Create and manage expense groups with role-based permissions\n- ✅ **Expense Tracking** - Record expenses with 4 split methods (equal, percentage, exact, shares)\n- ✅ **Payment Recording** - Track payments between group members\n- ✅ **Balance Calculation** - Real-time balance calculations with settlement plan generation\n- ✅ **Data Export** - Export group data in CSV/PDF formats\n- ✅ **Search \u0026 Filter** - Advanced search and filtering across expenses\n\n### 🌐 Network Layer\n- ✅ **HTTP Client** - Dio with interceptors support\n- ✅ **Configurable Timeouts** - Environment-based timeout configuration\n- ✅ **Request/Response Logging** - Debug-friendly HTTP logging\n- ✅ **Error Interceptors** - Automatic error handling and conversion\n- ✅ **Auth Interceptors** - Automatic token injection and refresh\n\n### 🎨 UI \u0026 UX\n- ✅ **Material Design** - Material 3 theme support\n- ✅ **Dark Mode** - Built-in dark theme support\n- ✅ **Accessibility** - Semantic labels and accessibility support\n- ✅ **Responsive Design** - Adaptive layouts for different screen sizes\n\n### 🧭 Routing \u0026 Navigation\n- ✅ **Type-Safe Routing** - GoRouter with type-safe route definitions\n- ✅ **Deep Linking** - Support for deep links and URL navigation\n- ✅ **Auth-Based Routing** - Protected routes with authentication redirects\n- ✅ **Navigation Logging** - Automatic route tracking and logging\n\n### 📊 Logging \u0026 Monitoring\n- ✅ **Comprehensive Logging** - Multi-level logging with file and console output\n- ✅ **Log Rotation** - Automatic log file rotation\n- ✅ **Structured Logging** - JSON formatting for production\n- ✅ **Performance Monitoring** - Firebase Performance integration\n- ✅ **Screen Tracking** - Automatic screen load time tracking\n\n### 🚀 Deployment \u0026 CI/CD\n- ✅ **Multi-Platform** - Android, iOS, Web, Linux, macOS, Windows support\n- ✅ **CI/CD Ready** - GitHub Actions workflows included (disabled by default, uncomment triggers to enable)\n- ✅ **Version Management** - Automated version bumping scripts\n- ✅ **Fastlane Integration** - iOS and Android deployment automation\n\n### 📚 Documentation\n- ✅ **Comprehensive Docs** - Architecture, guides, API documentation\n- ✅ **Migration Guides** - From MVC, GetX, Bloc, and other architectures\n- ✅ **Best Practices** - Code examples and patterns\n- ✅ **API Documentation** - Complete API reference\n- ✅ **Example Features** - Complete features demonstrating Clean Architecture (Auth, Groups, Expenses, Balances, etc.)\n\n### 🧪 Testing\n- ✅ **66 Test Files** - Comprehensive test coverage\n- ✅ **Unit Tests** - Domain and data layer testing\n- ✅ **Widget Tests** - UI component testing\n- ✅ **Integration Tests** - End-to-end flow testing\n- ✅ **Test Helpers** - Reusable test utilities and fixtures\n\n## 🛠️ Tech Stack\n\n### Core Dependencies\n- **Flutter** - UI framework\n- **Riverpod** - State management\n- **Dio** - HTTP client\n- **Freezed** - Code generation for immutable classes\n- **Equatable** - Value equality comparison\n\n### Firebase\n- **Firebase Core** - Firebase initialization\n- **Firebase Remote Config** - Remote feature flags\n- **Firebase Performance** - Performance monitoring and tracking\n\n### Storage\n- **flutter_secure_storage** - Secure storage for sensitive data\n- **shared_preferences** - Simple key-value storage\n\n### Localization\n- **flutter_localizations** - Flutter localization support\n- **intl** - Internationalization utilities\n\n### Routing \u0026 Navigation\n- **go_router** - Declarative routing with deep linking\n\n### Logging \u0026 Monitoring\n- **logger** - Comprehensive logging solution\n- **path_provider** - File system access for log files\n\n### Development Tools\n- **build_runner** - Code generation runner\n- **very_good_analysis** - Linting rules\n- **mocktail** - Testing and mocking\n\n## 📁 Project Structure\n\n```\nlib/\n├── core/                    # Core infrastructure\n│   ├── config/             # Configuration system\n│   ├── constants/          # App constants\n│   ├── di/                 # Dependency injection (Riverpod providers)\n│   ├── errors/             # Error handling\n│   ├── feature_flags/      # Feature flags infrastructure\n│   ├── localization/       # Localization service\n│   ├── logging/            # Logging service\n│   ├── network/            # Network layer (Dio setup)\n│   ├── performance/        # Performance monitoring\n│   ├── routing/            # Routing system (go_router)\n│   ├── storage/            # Storage services (with migration)\n│   └── utils/              # Utility functions\n│\n├── features/                # Feature modules (Clean Architecture)\n│   ├── auth/               # Authentication feature with social login\n│   │   ├── data/          # Data layer (models, data sources, repositories)\n│   │   │   ├── handlers/  # OAuth deep link handlers\n│   │   │   ├── models/    # User, profile, social auth models\n│   │   │   └── repositories/ # Social auth and user repositories\n│   │   ├── domain/        # Domain layer (entities, use cases, repository interfaces)\n│   │   │   ├── entities/  # User, SocialAuthProvider, ProfileSetupData\n│   │   │   └── repositories/ # SocialAuthRepository interface\n│   │   └── presentation/  # Presentation layer (screens, widgets, providers)\n│   │       ├── pages/     # Login, register, profile setup pages\n│   │       └── widgets/   # Social login buttons, dialogs, error widgets\n│   ├── feature_flags/      # Feature flags feature\n│   │   └── presentation/   # Feature flags UI\n│   ├── groups/             # Group management\n│   ├── expenses/           # Expense tracking\n│   ├── payments/           # Built-in payments tracking\n│   ├── balances/           # Balance calculation engine\n│   └── export/             # Data export utilities\n│\n├── shared/                  # Shared resources\n│   ├── accessibility/      # Accessibility utilities\n│   ├── extensions/         # Dart extensions\n│   ├── theme/              # App theme configuration\n│   └── widgets/            # Reusable widgets\n│\n├── l10n/                   # Localization files (generated)\n└── main.dart               # App entry point\n```\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Flutter SDK (\u003e=3.0.0)\n- Dart SDK (\u003e=3.0.0)\n- Android Studio / VS Code with Flutter extensions\n- Xcode (for iOS development on macOS)\n\n### Local Development with Supabase\n\nFor fully offline development using a local Supabase instance:\n\n1. **Install Supabase CLI**\n   ```bash\n   npm install -g supabase\n   ```\n\n2. **Start local Supabase**\n   ```bash\n   supabase start\n   ```\n   The CLI will print the API URL and anon key once running.\n\n3. **Configure `.env` for local**\n   ```env\n   ENVIRONMENT=development\n   SUPABASE_URL=http://localhost:54321\n   SUPABASE_ANON_KEY=\u003canon key from supabase start output\u003e\n   ```\n   \u003e The default anon key is already available in `.env.example` under `SUPABASE_LOCAL_ANON_KEY`.\n\n4. **Apply migrations (if any)**\n   ```bash\n   supabase db reset\n   ```\n\n5. **Run the app**\n   ```bash\n   flutter run\n   ```\n\n6. **Stop local Supabase when done**\n   ```bash\n   supabase stop\n   ```\n\n\u003e **Note**: When using Android Emulator, replace `localhost` with `10.0.2.2`:\n\u003e ```env\n\u003e SUPABASE_URL=http://10.0.2.2:54321\n\u003e ```\n\n---\n\n### Installation\n\n1. **Create repository from template** (if using GitHub template)\n   - Click \"Use this template\" button on GitHub\n   - Create a new repository from this template\n   - Clone your new repository:\n   ```bash\n   git clone \u003cyour-repository-url\u003e\n   cd \u003cyour-project-name\u003e\n   ```\n\n   **OR clone directly** (if not using template):\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd grex\n   ```\n\n2. **Install dependencies**\n   ```bash\n   flutter pub get\n   ```\n\n3. **Generate code** (Freezed, JSON serialization)\n   ```bash\n   flutter pub run build_runner build --delete-conflicting-outputs\n   ```\n\n4. **Set up environment configuration**\n   ```bash\n   # Copy the example environment file\n   cp .env.example .env\n   \n   # Edit .env with your configuration\n   # See Configuration System section below\n   ```\n\n5. **Set up Git hooks** (optional but recommended)\n   \n   **Linux/macOS:**\n   ```bash\n   ./scripts/linux/development/setup-git-hooks.sh\n   ```\n   \n   **Windows:**\n   ```powershell\n   .\\scripts\\windows\\development\\setup-git-hooks.ps1\n   ```\n   This will install Git hooks for:\n   - Code formatting checks (pre-commit)\n   - Commit message validation (commit-msg)\n   - Test execution (pre-push)\n\n6. **Run the app**\n   ```bash\n   flutter run\n   ```\n\n### Social Login Setup\n\nThe app includes comprehensive social login integration with Google OAuth and Apple Sign In.\n\n#### OAuth Provider Configuration\n\n1. **Google OAuth Setup**:\n   - Create OAuth 2.0 Client ID in [Google Cloud Console](https://console.cloud.google.com/)\n   - Add authorized redirect URIs: `https://[project-id].supabase.co/auth/v1/callback`\n   - Configure in Supabase Dashboard → Authentication → Providers\n\n2. **Apple Sign In Setup**:\n   - Create Services ID in [Apple Developer Portal](https://developer.apple.com/)\n   - Configure Sign In with Apple\n   - Generate private key (.p8 file)\n   - Configure in Supabase Dashboard → Authentication → Providers\n\n#### Deep Link Configuration\n\n**Android** (`android/app/src/main/AndroidManifest.xml`):\n```xml\n\u003cintent-filter android:autoVerify=\"true\"\u003e\n    \u003caction android:name=\"android.intent.action.VIEW\" /\u003e\n    \u003ccategory android:name=\"android.intent.category.DEFAULT\" /\u003e\n    \u003ccategory android:name=\"android.intent.category.BROWSABLE\" /\u003e\n    \u003cdata android:scheme=\"io.supabase.grex\"\n          android:host=\"login-callback\" /\u003e\n\u003c/intent-filter\u003e\n```\n\n**iOS** (`ios/Runner/Info.plist`):\n```xml\n\u003ckey\u003eCFBundleURLTypes\u003c/key\u003e\n\u003carray\u003e\n    \u003cdict\u003e\n        \u003ckey\u003eCFBundleURLName\u003c/key\u003e\n        \u003cstring\u003eio.supabase.grex\u003c/string\u003e\n        \u003ckey\u003eCFBundleURLSchemes\u003c/key\u003e\n        \u003carray\u003e\n            \u003cstring\u003eio.supabase.grex\u003c/string\u003e\n        \u003c/array\u003e\n    \u003c/dict\u003e\n\u003c/array\u003e\n```\n\n#### Features\n\n- **OAuth Integration**: Google and Apple OAuth with external browser launch\n- **Account Linking**: Link social providers to existing email accounts\n- **Profile Setup**: Guided profile completion for new social users\n- **Deep Link Handling**: Fast OAuth callback processing (\u003c 1 second)\n- **Session Management**: Persistent sessions with automatic refresh\n- **Error Handling**: User-friendly error messages with retry options\n- **Localization**: Multi-language support for all social login UI\n- **Security**: HTTPS-only, minimal scopes, secure token storage\n- **Performance**: OAuth flow completion \u003c 5 seconds after authorization\n\nFor detailed implementation guide, see [Social Login Developer Guide](docs/social-login-developer-guide.md).\n\n### First Steps\n\n1. **Rename the project** (if needed) - Update package name from `grex` to your project name\n2. **Configure your environment** - See [Configuration System](#-configuration-system) below\n3. **Set up Firebase** (optional) - For remote feature flags and performance monitoring\n   - Add `google-services.json` (Android) and `GoogleService-Info.plist` (iOS)\n   - Initialize Firebase in your app\n4. **Customize the theme** - Edit `lib/shared/theme/app_theme.dart`\n5. **Explore example features** - Check out `lib/features/` for examples:\n   - **Auth** - Authentication flow with social login\n   - **Groups \u0026 Expenses** - Core expense sharing implementation\n   - **Feature Flags** - Conditional UI rendering based on flags\n6. **Add your first feature** - Follow the pattern in example features\n7. **Read the documentation** - Check out `docs/` folder for detailed guides\n\n## ⚙️ Configuration System\n\nThis project includes a production-ready, multi-environment configuration system that supports:\n\n- **Local Development**: `.env` files for easy local configuration\n- **CI/CD**: `--dart-define` flags for build-time configuration\n- **Fallback Chain**: `.env` → `--dart-define` → defaults\n- **Environment-Aware Defaults**: Different configurations per environment\n- **Feature Flags**: Enable/disable features per environment\n- **Network Configuration**: Timeout settings for API calls\n- **Debug Utilities**: Tools for inspecting configuration\n\n### Architecture\n\nThe configuration system consists of two main classes:\n\n1. **`EnvConfig`** (`lib/core/config/env_config.dart`): Low-level environment variable loader\n   - Loads from `.env` files using `flutter_dotenv`\n   - Reads from `--dart-define` flags\n   - Provides fallback chain: `.env` → `--dart-define` → defaults\n\n2. **`AppConfig`** (`lib/core/config/app_config.dart`): High-level application configuration\n   - Uses `EnvConfig` to get values\n   - Provides typed getters (String, bool, int)\n   - Environment-aware defaults\n   - Feature flags\n   - Network timeout configuration\n   - Debug utilities\n\n### Setup\n\n#### 1. Create `.env` file for local development\n\n```bash\n# Copy the example file\ncp .env.example .env\n\n# Edit .env with your values\n# The .env file is gitignored and won't be committed\n```\n\n#### 2. Configure your environment variables\n\nEdit `.env` with your configuration:\n\n```env\nENVIRONMENT=development\nBASE_URL=http://localhost:3000\nENABLE_LOGGING=true\nENABLE_ANALYTICS=false\n```\n\n### Usage Examples\n\n#### Local Development (using `.env` file)\n\n1. Create `.env` file from `.env.example`\n2. Fill in your values\n3. Run the app normally:\n\n```bash\nflutter run\n```\n\nThe app will automatically load values from `.env`.\n\n#### Staging Build (using `--dart-define`)\n\nFor CI/CD or when you don't want to use `.env` files:\n\n```bash\nflutter run \\\n  --dart-define=ENVIRONMENT=staging \\\n  --dart-define=BASE_URL=https://api-staging.example.com \\\n  --dart-define=ENABLE_ANALYTICS=true\n```\n\n#### Production Build (using `--dart-define`)\n\n```bash\nflutter build apk \\\n  --dart-define=ENVIRONMENT=production \\\n  --dart-define=BASE_URL=https://api.example.com \\\n  --dart-define=ENABLE_ANALYTICS=true \\\n  --dart-define=ENABLE_CRASH_REPORTING=true\n```\n\n### Using Configuration in Code\n\n#### Basic Usage\n\n```dart\nimport 'package:grex/core/config/app_config.dart';\n\n// Get environment\nfinal env = AppConfig.environment; // 'development', 'staging', or 'production'\n\n// Check environment\nif (AppConfig.isDevelopment) {\n  // Development-specific code\n}\n\n// Get API base URL\nfinal baseUrl = AppConfig.baseUrl;\n\n// Check feature flags\nif (AppConfig.enableLogging) {\n  logger.info('App started');\n}\n\nif (AppConfig.enableAnalytics) {\n  analytics.trackEvent('app_opened');\n}\n```\n\n#### Network Configuration\n\n```dart\nimport 'package:grex/core/config/app_config.dart';\nimport 'package:dio/dio.dart';\n\nfinal dio = Dio(\n  BaseOptions(\n    baseUrl: AppConfig.baseUrl,\n    connectTimeout: Duration(seconds: AppConfig.apiConnectTimeout),\n    receiveTimeout: Duration(seconds: AppConfig.apiReceiveTimeout),\n    sendTimeout: Duration(seconds: AppConfig.apiSendTimeout),\n  ),\n);\n```\n\n#### Debug Utilities\n\n```dart\nimport 'package:grex/core/config/app_config.dart';\n\n// Print configuration to console (only in debug mode)\nAppConfig.printConfig();\n\n// Get configuration as a map\nfinal config = AppConfig.getDebugInfo();\nprint(config);\n```\n\n### Available Configuration Options\n\n#### Environment Variables\n\n| Variable | Type | Default | Description |\n|----------|------|---------|-------------|\n| `ENVIRONMENT` | String | `development` | Environment name: `development`, `staging`, or `production` |\n| `BASE_URL` | String | Environment-aware | API base URL (see defaults below) |\n| `API_TIMEOUT` | int | `30` | API timeout in seconds |\n| `API_CONNECT_TIMEOUT` | int | `10` | API connect timeout in seconds |\n| `API_RECEIVE_TIMEOUT` | int | `30` | API receive timeout in seconds |\n| `API_SEND_TIMEOUT` | int | `30` | API send timeout in seconds |\n| `ENABLE_LOGGING` | bool | Environment-aware | Enable logging (default: true in dev/staging) |\n| `ENABLE_ANALYTICS` | bool | Environment-aware | Enable analytics (default: true in staging/prod) |\n| `ENABLE_CRASH_REPORTING` | bool | Environment-aware | Enable crash reporting (default: true in staging/prod) |\n| `ENABLE_PERFORMANCE_MONITORING` | bool | Environment-aware | Enable performance monitoring (default: true in staging/prod) |\n| `ENABLE_DEBUG_FEATURES` | bool | Environment-aware | Enable debug features (default: true in dev) |\n| `ENABLE_HTTP_LOGGING` | bool | Environment-aware | Enable HTTP request/response logging (default: true in dev) |\n| `APP_VERSION` | String | `0.0.1` | App version |\n| `APP_BUILD_NUMBER` | String | `1` | App build number |\n\n#### Environment-Aware Defaults\n\n**BASE_URL defaults:**\n- Development: `http://localhost:3000`\n- Staging: `https://api-staging.example.com`\n- Production: `https://api.example.com`\n\n**Feature Flag defaults:**\n- Logging: Enabled in `development` and `staging`\n- Analytics: Enabled in `staging` and `production`\n- Crash Reporting: Enabled in `staging` and `production`\n- Performance Monitoring: Enabled in `staging` and `production`\n- Debug Features: Enabled in `development` only\n- HTTP Logging: Enabled in `development` only\n\n### Best Practices\n\n1. **Never commit `.env` files**: They contain sensitive information and are gitignored\n2. **Use `.env.example` as a template**: Commit this file with placeholder values\n3. **Use `.env` for local development**: Easy to change values without rebuilding\n4. **Use `--dart-define` for CI/CD**: More secure and doesn't require file management\n5. **Set environment-specific defaults**: Let the system handle defaults based on environment\n6. **Use feature flags**: Enable/disable features per environment without code changes\n\n### Troubleshooting\n\n#### Configuration not loading\n\n1. Ensure `EnvConfig.load()` is called in `main()` before `runApp()`\n2. Check that `.env` file exists in the project root\n3. Verify `pubspec.yaml` includes `.env` in assets\n4. Run `flutter pub get` after adding `flutter_dotenv`\n\n#### Values not updating\n\n1. Hot reload doesn't reload environment variables - do a full restart\n2. For `--dart-define` values, rebuild the app\n3. Check that you're using the correct variable name (case-sensitive)\n\n#### Debug configuration\n\nUse `AppConfig.printConfig()` in debug mode to see all configuration values:\n\n```dart\nif (AppConfig.isDebugMode) {\n  AppConfig.printConfig();\n}\n```\n\nThis will print all configuration values to the console, helping you verify what values are being used.\n\n## 🧪 Testing\n\n### Run Tests\n\n```bash\n# Run all tests\nflutter test\n\n# Run tests with coverage\nflutter test --coverage\n\n# Run specific test file\nflutter test test/features/auth/domain/usecases/login_test.dart\n```\n\n### Test Structure\n\nTests follow the same structure as the source code:\n- **66 test files** with comprehensive coverage\n- Unit tests for use cases and utilities\n- Widget tests for UI components\n- Integration tests for end-to-end flows\n- **Property-based tests** for social login (35 properties with 100+ iterations each)\n- Test helpers and fixtures for reusable test utilities\n\n#### Social Login Testing\n\nThe social login feature includes extensive testing:\n\n```bash\n# Run social login tests specifically\nflutter test test/features/auth/data/repositories/social_auth_repository_test.dart\nflutter test test/features/auth/presentation/widgets/social_login_button_test.dart\n\n# Run property-based tests (100+ iterations each)\nflutter test test/features/auth/property_tests/\n```\n\n**Property Tests Include**:\n- OAuth flow completion within performance requirements\n- Profile setup data preservation\n- Account linking detection and handling\n- Session persistence across app restarts\n- Error handling for all failure scenarios\n\n### Test Coverage\n\nThe project includes:\n- ✅ Domain layer tests (use cases, entities)\n- ✅ Data layer tests (repositories, data sources, models)\n- ✅ Presentation layer tests (screens, widgets, providers)\n- ✅ Core infrastructure tests (config, network, storage, logging, performance)\n- ✅ Integration tests for complete flows\n\n## 🏗️ Building\n\n### Android\n\n```bash\n# Debug APK\nflutter build apk --debug\n\n# Release APK\nflutter build apk --release\n\n# App Bundle (for Play Store)\nflutter build appbundle --release\n```\n\n### iOS\n\n```bash\n# Debug\nflutter build ios --debug\n\n# Release\nflutter build ios --release\n```\n\n### Web\n\n```bash\n# Debug\nflutter build web --debug\n\n# Release\nflutter build web --release\n```\n\n## 📚 Documentation\n\n### Architecture\n\n- **[Architecture Documentation](docs/architecture/README.md)** - Complete architecture documentation index\n- **[Architecture Overview](docs/architecture/overview.md)** - Why Clean Architecture, benefits, trade-offs, and learning resources\n- **[Design Decisions](docs/architecture/design-decisions.md)** - Detailed rationale for routing, state management, error handling, logging, storage, and HTTP client choices\n\n### Guides\n\n- **[Getting Started](docs/guides/getting-started.md)** - Step-by-step setup guide\n- **[Understanding the Codebase](docs/guides/understanding-codebase.md)** - Architecture and patterns\n- **[Common Tasks](docs/guides/common-tasks.md)** - Frequently performed tasks\n- **[Routing Guide](docs/guides/routing.md)** - GoRouter navigation and deep linking\n- **[Git Hooks Setup](docs/guides/git-hooks-setup.md)** - Setup Git hooks for code quality (similar to Husky)\n- **[Adding Features](docs/api/examples/adding-features.md)** - How to add new features\n\n### Migration Guides\n\n- **[From MVC to Clean Architecture](docs/guides/migration/from-mvc-to-clean-architecture.md)**\n- **[From GetX to This Setup](docs/guides/migration/from-getx-to-this-setup.md)**\n- **[Customization Guide](docs/guides/migration/customization-guide.md)**\n\n### Features\n\n- **[Social Login](docs/social-login-developer-guide.md)** - Complete social login implementation guide\n- **[Feature Flags](docs/features/feature-flags.md)** - Feature flags system documentation\n- **[Expense Sharing Engine]** - Core sharing models\n  - **[Groups](docs/features/groups.md)** - Group management\n  - **[Expenses](docs/features/expenses.md)** - Expense tracking\n  - **[Balances](docs/features/balances.md)** - Real-time calculation engine\n  - **[Payments](docs/features/payments.md)** - P2P payment tracking\n  - **[Export](docs/features/export.md)** - Data export utilities\n- **[Localization](docs/guides/internationalization-guide.md)** - i18n setup and usage\n- **[Logging](docs/guides/README.md)** - Logging system documentation\n- **[Performance](docs/guides/performance/README.md)** - Performance monitoring guides\n- **[Routing](docs/guides/routing.md)** - Routing and navigation guide\n\n### Deployment\n\n- **[Deployment Guide](docs/deployment/deployment.md)** - Complete deployment documentation\n- **[Quick Start](docs/deployment/quick-start.md)** - Get started in 5 minutes\n- **[Android Deployment](docs/deployment/android-deployment.md)** - Android-specific guide\n- **[iOS Deployment](docs/deployment/ios-deployment.md)** - iOS-specific guide\n- **[Web Deployment](docs/deployment/web-deployment.md)** - Web-specific guide\n- **[Release Process](docs/deployment/release-process.md)** - Version management and releases\n- **[Monitoring \u0026 Analytics](docs/deployment/monitoring-analytics.md)** - Crashlytics and analytics setup\n\n### API Documentation\n\n- **[API Overview](docs/api/README.md)** - API documentation index\n- **[Examples](docs/api/examples/)** - Code examples and patterns\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- How to report bugs\n- How to suggest enhancements\n- Development setup and workflow\n- Coding standards and guidelines\n- Testing requirements\n- Commit message conventions\n\n### Quick Start\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes following our [coding standards](CONTRIBUTING.md#coding-standards)\n4. Write or update tests\n5. Commit your changes using [conventional commits](CONTRIBUTING.md#commit-message-guidelines)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nFor detailed guidelines, please read [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## 📝 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Flutter](https://flutter.dev) - The framework\n- [Riverpod](https://riverpod.dev) - State management\n- [Very Good Ventures](https://verygood.ventures) - Linting rules and best practices\n- [Freezed](https://pub.dev/packages/freezed) - Code generation\n\n## 📞 Support\n\nFor questions, issues, or contributions, please open an issue on GitHub.\n\n---\n\n**Made with ❤️ using Flutter**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoniz-dev%2Fgrex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkoniz-dev%2Fgrex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkoniz-dev%2Fgrex/lists"}