PROJECT_NAME

This project aims to build a scalable and powerful architecture for production-ready Flutter applications. The architecture will be designed to handle various aspects of app development, including UI/UX, state managment, data fetching, and more. By folowing best practices and utilizing efficient design patterns, the goal is to create a robust foundation that can easily adapt to changing requirements and scale with the growth of the application.

Preview

Screenshots

Screenshots (web)

Features

• Supabase Integration
  • Authentication: User authentication with Supabase`s built-in authentication services.
  • Database: Real-time database integration for dynamic data handling.
  • Storage: Efficient file storage and retrival with Supabase`s storage solutions.
• State Management: Organized and testable state management using BLoC pattern.
• Routing: Easy and scallable routing solution.
• Localization: Simplefied localization setup supporting multiple languages and dynamic translations.
• Theming: Easily customizable light and dark themes.
• Dependency Injection: For better modularity and testability.
• Network Handling
  • Robust HTTP Client: Handling network requests and responses.
  • Connectivity Plus: Real-time network status tracking.
• Error Handling: Centralized error handling for consistent error management across the app.
• Storage Service Design: Simple key-value storage for app preferences and settings.
• Testing:
  • Unit Testing: Comprehensive unit tests for business logic.
  • Widget Testing: Thorough widget tests to ensure UI correctness.
• Linting and Formatting: Consistent code style enforcement and automatic code formatting to maintain code quality.
• CI/CD: Pre-configured workflows for automated testing, building, and deployment.
• Documentation
  • Well-documented Code: In-code documentation and comments for better understanding and maintainability.
  • README.MD: Detailed Readme file with instructions and feature descriptions.

Get Started

# Clone repo
git clone https://github.com/Nika0000/SuperFrog.git
cd SuperFrog

# Install all the required dependencies
flutter pub get

# Generate model, route, localization
flutter pub run build_runner build

Before running the application, you need to set up the environment configuration files.

Create env.prod.json for production and env.dev.json for development in the root directory of the project and add the following configuration:

{
    "SUPABASE_URL": "your-supabase-url",
    "SUPABASE_ANON_KEY": "your-annon-key",
    "SUPABASE_BUCKET_NAME": "your-bucket-name",
    "GOOGLE_WEB_CLIENT_ID": "google-oauth-web",
    "GOOGLE_IOS_CLIENT_ID": "google-oauth-ios",
    "APPLE_CLIENT_ID": "apple-client-id",
    "TURNSTILE_SITE_KEY": "cloudflare-turnstile-site-key"
}

Running

Android / IOS / Web

# Debug
flutter run --debug --dart-define-from-file env.dev.json

# Release
flutter run --release --dart-define-from-file env.prod.json

Building for Production

Android

To build a signed release APK, you need to sign your application. Follow thoes steps:

1. Generate a Keystore:

   If you don`t have a keystore, generate one by running the following command in your terminal:

   keytool -genkey -v -keystore <your-key-name>.jks -keyalg RSA \
           -keysize 2048 -validity 10000 -alias <your-key-alias>

2. Reference the Keystore:

   Create a file named key.propertis in the android directory and add the following:

   storePassword=<your-store-password>
   keyPassword=<your-key-password>
   keyAlias=<your-key-alias>
   storeFile=<path-to-your-keystore>
   

3. Build the Release APK:

   flutter build apk --release --dart-define-from-file env.prod.json

iOS

Prepare for iOS Release

To build and distribute your iOS app, follow thoes steps:

1. Update Project Settings:

   Open the ios folder of your Flutter project in Xcode:

   open ios/Runner.xcworkspace

2. Configure App Information:

   In Xcode, select the Runner project in the Project Navigator. Under the General tab, configure the following:

   • Display Name
   • Bundle Identifer
   • Team (select your Apple Developer account)
   • Version and Build number

3. Configure Signing & Capabilities:

   Under the Signing & Capabilities tab, ensure that Automatically manage signing is checked. Select your Development Team.

4. Build the iOSS App:

   Run the following command to build the iOS app:

   flutter build ios --release --dart-define-from-file env.prod.json

5. Archive the App:

   In Xcode, select Product > Archive to create an archive of your app.

6. Distribute the App:

   After the archive is created, the Xcode Organizer window will appear. Select your archive and click Distribute App. Follow the prompts to upload your app to the App Store or export it for Ad Hoc distribution.

Web

To build and deploy your Flutter web app, follow thoes steps:

1. Build the Web App:

   Run the following command to create a release build for the web:

   flutter build web --web-renderer canvaskit --dart-define-from-file env.prod.json

2. Deploy the Web App:

   Upload the contents of the build/web directory to your web server or hosing provider.

Project Structure

The project structure is organized into logical modules and directories, each serving a specific purpose in the application's architecture. Here's a brief overview of the main directories and their contents:

    src
     ├── assets/    # Contains all the non-Dart resources used in the app, such as images and localization files.
     │    ├── images/  # Stores image assets.
     │    │     ├── logo_dark.svg  # The dark version of the app logo.
     │    │     └── logo_light.svg # The light version of the app logo.
     │    │
     │    └── locales/  # Contains localization files for different languages
     │          ├── en_US.json  # Localization file for US English.
     │          └── ka_GE.json  # Localization file for Georgian.
     └── lib  # Contains the main Dart code for the application.
          ├── app/  # Contains the main app structure.
          │    ├── pages/  # Directory for different pages/screens of the app.
          │    ├── widgets/  # Directory for reusable widgets.
          │    └── app_view.dart  # Main view of the application.
          ├── config/  # Contains configuration files for the app.
          │    ├── app_config.dart  # General configuration settings for the app.
          │    ├── theme_config.dart  # Configuration related to theming and appearance.
          │    └── preference_config.dart  # Configuration related user preferences and settings
          ├── data/  # Manages data-related components.
          │    ├── blocs/  # Contains BLoC (Business Logic Component) classes for state management.
          │    ├── model/  # Contains data models.
          │    └── services/  # Contains service classes for making API calls or handling data.
          ├── routes/  # Manages app navigation.
          │    └── app_routes.dart  # Defines the routes for navigating between different pages.
          ├── utils/  # Contains utility functions and helpers used throughout the app.
          │    └── ...
          └── main.dart  # The entry point of the application.

Theming and appearance

This project uses the Moon.io design system for its UI components and design patterns.

Configure Supabase

Email Templates

Confirm signup

<h2>Confirm your signup</h2>

<p>Follow this link to confirm your usesr:</p>
<p><a href="{{ .ConfirmationURL }}">Confirm your mail</a></p>

Invite user

    <h2>You have been invited</h2>

    <p>You have been invited to create a user on {{ .SiteURL }}. Follow this link to accept the invite:</p>
    <p><a href="{{ .ConfirmationURL }}">Accept the invite</a></p>

Magic Link

    <h2>Magic Link</h2>

    <p>Follow this link to login:</p>
    <p><a href="{{ .SiteURL }}auth/callback/verify?token={{ .TokenHash }}&type=magiclink">Log in</a></p>

Change Email Address

    <h2>Confirm Change of Email</h2>

    <p>Follow this link to confirm the update of your email from {{ .Email }} to {{ .NewEmail }}:</p>
    <p><a href="{{ .ConfirmationURL }}">Change Email</a></p>

Reset Password

    <h2>Reset Password</h2>

    <p>Follow this link to reset the password for your user:</p>
    <p>OTP: {{.Token }}</p>
    <p><a href="{{ .SiteURL }}auth/callback/verify?token={{ .TokenHash }}&type=recovery">Reset Password</a></p>

URL Configuration

To ensure functionalities like password recovery, magic links, email change work correctly, configure the Site URL in Supabase Dashborad.

1. Go to Autentication -> URL Configuration
2. Set the Site Url
   • In the "Site URL" field, enter the URL where your Flutter app is hosted. If you`re in development, this might be something like http://localhost:8000/callback/verify
3. Configure Redirect URLs for Deep linking

   • In the "Redirect URLs" section, add the URLs that your auth providers are permitted to redirect to post-authentication. You can use wildcards if necessary. For example:

     • com.example.demoapp://auth/callback/verify
     • http://localhost:8080/auth/callback/verify

Enable Captcha protection

To enhance the security of your authentication process, you can enable Cloudflare Turnstile CAPTCHA in your Supabase project. Follow these steps:

1. Create a Cloudflare Turnstile Account
   • In the Cloudflare Turnstile dashboard, create a new Turnstile widget (invisible)
2. Go to Project Settings -> Authentication
   • Enable Captcha protection
   • Choose Captcha Provider to Turnstile by Cloudflare
   • Enter Secret key in "Captcha secret" field and save.

Additional Configuration

Deep Linking

Note

Before you start Configure Your Domain: ensure that you have a domain to use for deep linking. For Android and iOS, you will need to host configuration file. Android Hosting assetlinks.json file Ios Host apple-app-site-association JSON file

Android

1. Open AndroidManifest.xml located at android/app/src/main/AndroidManifest.xml

2. Inside the <activity> tag for your main activity. Replace www.yourdomain.com with your actual domain.

   <activity
   android:name=".MainActivity"
   android:launchMode="singleTask"
   android:theme="@style/LaunchTheme"
   android:configChanges="keyboard|keyboardHidden|orientation|screenSize|smallestScreenSize|screenLayout|density|uiMode"
   android:hardwareAccelerated="true"
   android:windowSoftInputMode="adjustResize">
   
       <!-- Deeplink -->
       <meta-data android:name="flutter_deeplinking_enabled" android:value="true" />
       <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="http" android:host="www.yourdomain.com" />
           <data android:scheme="https" />
       </intent-filter>
   
   <!-- Existing configurations -->
   </activity>

iOS

1. Open Info.plist located at ios/Runner/Info.plist.

2. Add a new entry for URL types. Replace your_scheme with your actual URL scheme and yourdomain.com with your actual domain.

       <dict>
           <key>CFBundleURLTypes</key>
      	    <!-- Deep linking -->
           <array>
               <dict>
                   <key>CFBundleURLSchemes</key>
                   <array>
                       <string>your_scheme</string>
                   </array>
                   <key>CFBundleURLName</key>
                   <string>www.yourdomain.com</string>
               </dict>
           </array>
   	    <!--End of the Deep linking-->
       </dict>

Contribution

Contributions are welcome! If you have any ideas, suggestions, or improvements for the architecture, feel free to open an issue or submit a pull request. Please ensure that your contributions align with the project's goals and guidelines.

License

This project is licensed under the MIT License. Feel free to use, modify, and distribute the code for your own projects.