Mobile Application

Relevant source files

The following files were used as context for generating this wiki page:

• apps/mobile/README.md
• GEMINI.md
• scripts/check-mobile.js
• skills/flutter-expert/SKILL.md
• README.md
• conductor/workflow.md

The Tuturuuu Mobile Application is a cross-platform solution built using the Flutter framework, located within the apps/mobile/ directory of the monorepo. It serves as the mobile extension of the Tuturuuu ecosystem, providing users with access to workspace management, AI interactions, and productivity tools on iOS, Android, Web, and Windows platforms.

The application is integrated with the broader platform's backend infrastructure, primarily leveraging Supabase for authentication and data storage. It utilizes modern Dart development patterns, including BLoC/Cubit for state management and go_router for navigation, ensuring a performant and maintainable mobile experience that mirrors the functionality found in the Core Platform.

Sources: apps/mobile/README.md:1-20, GEMINI.md:278-285, README.md:27-40

Architecture and Core Technologies

The mobile application follows a structured architecture designed for scalability and cross-platform consistency. It utilizes Flutter 3.19+ and Dart 3.3+ as its primary development stack.

State Management and Navigation

The application employs a combination of BLoC (Business Logic Component) and Cubit for managing application state. This ensures a unidirectional data flow and clear separation between the UI and business logic. Navigation is handled by go_router, which supports deep linking and complex routing requirements.

Integration Layer

The mobile app interacts with the platform's backend through specific API routes hosted by the web application (e.g., /api/v1/auth/mobile/*). Authentication is managed via supabase_flutter, which handles session tokens rather than traditional cookies to accommodate mobile security patterns.

Development Workflow

The following diagram illustrates the high-level architecture and data flow between the mobile application and the platform services:

The diagram shows how the Flutter application utilizes repositories to abstract communication with the platform's web APIs and Supabase services.

Sources: GEMINI.md:278-285, skills/flutter-expert/SKILL.md:18-30, GEMINI.md:291-297

Development and Flavors

The project supports three distinct build flavors to manage different environment configurations.

Build Flavors

Flavor	Entry Point	Purpose
Development	main_development.dart	Local development and sandbox testing
Staging	main_staging.dart	Pre-production testing and QA
Production	main_production.dart	Final release for end-users

Execution Commands

To run specific flavors, the following commands are used:

# Development
flutter run --flavor development --target lib/main_development.dart

# Staging
flutter run --flavor staging --target lib/main_staging.dart

# Production
flutter run --flavor production --target lib/main_production.dart

Sources: apps/mobile/README.md:11-26, GEMINI.md:280-281

Internationalization (i18n)

The application supports multi-language capabilities, specifically targeting English (en) and Vietnamese (vi). Localization is managed through ARB (Application Resource Bundle) files located in lib/l10n/arb/.

Localization Workflow

1. Define Strings: New localizable strings are added to app_en.arb and app_vi.arb.
2. Generation: The project uses flutter_localizations. Running flutter gen-l10n creates the necessary Dart classes for typed access to strings.
3. Usage: Localized strings are accessed via the BuildContext (e.g., context.l10n.stringKey).

Sources: apps/mobile/README.md:43-98, GEMINI.md:77-80

Quality Assurance and CI/CD

Mobile code quality is enforced through strict linting rules and automated verification scripts.

Verification Suite

The project uses bun check:mobile as a unified verification command. This script executes three critical phases:

1. Formatting: Runs dart format --set-exit-if-changed to ensure code style consistency.
2. Analysis: Executes flutter analyze using the very_good_analysis ruleset to detect potential issues and anti-patterns.
3. Testing: Runs flutter test for unit and widget testing.

The CI/CD pipeline, defined in mobile.yaml, mirrors these checks to ensure that no code with linting errors or failing tests is merged.

Sources: scripts/check-mobile.js:58-120, GEMINI.md:282-290, apps/mobile/README.md:30-40

Technical Guidelines for Mobile

Specific technical constraints are applied to mobile development to ensure performance and reliability.

Core Guidelines

• Widget Optimization: Use const constructors wherever possible to reduce rebuild overhead.
• Async Safety: When using BuildContext after an await point, developers must check if (!context.mounted) return; to prevent memory leaks or crashes.
• Exception Handling: Prefer specific exception catching (e.g., on Exception catch (e)) over bare catch blocks.
• Mutation-Driven UI: For actions like approving or rejecting items, use Future<void> Function() callbacks and await them before closing UI elements like dialogs or bottom sheets.

Prohibited Practices

• State Management: Never use setState for app-wide state; rely on BLoC/Cubit.
• Heavy Computation: Do not perform heavy logic inside the build() method; use compute() for background processing if necessary.
• Error Handling: Do not return inside finally blocks.

Sources: skills/flutter-expert/SKILL.md:46-65, GEMINI.md:83-90, GEMINI.md:316-321

Conclusion

The Tuturuuu Mobile Application is a robust, localized, and strictly-typed component of the Tuturuuu platform. By leveraging Flutter's cross-platform capabilities and a rigorous verification pipeline, it provides a consistent user experience across multiple devices while maintaining high code quality standards through automated checks and expert-level development guidelines.

Sources: README.md:144-150, GEMINI.md:287-290