Voda 🌊

Voda is a community-driven goal achievement app that helps users reach their objectives together through shared goals called "lakes".

What is Voda?

An app designed to help you reach your goals as a community. Whether you want to build habits, learn new skills, or accomplish projects, Voda provides a collaborative environment where you can track progress, support others, and stay motivated.

Features

• Create Lakes: Define goals (called "lakes") that can be private or public
• Invite & Collaborate: Share invitation links to bring others into your lakes
• Discover: Explore and join public lakes created by other users
• Track Progress: Complete milestones and monitor your personal development
• Real-time Chat: Communicate with lake members via WebSocket-based chat
• Privacy: App generated usernames and avatars
• Push Notifications: Stay updated with Firebase Cloud Messaging

Tech Stack

Frontend

• Framework: Flutter 3.9.2+
• State Management: Provider (for service injection), StatefulWidget with setState
• Local Storage: SQLite (sqflite_common_ffi), flutter_secure_storage
• Real-time Communication: WebSocket
• Notifications: Firebase Cloud Messaging, flutter_local_notifications
• UI Libraries: Lottie animations, flutter_svg

Backend

• Framework: FastAPI (Python)
• API Base URL: https://voda-app.duckdns.org

Project Structure

lib/
├── components/          # Reusable UI components
├── main.dart            # App entry point
├── models/              # Data structures
│   ├── lake_model.dart
│   ├── message_model.dart
│   ├── notification_model.dart
│   └── user_model.dart
├── pages/               # Main screen widgets
│   ├── achievements_page.dart
│   ├── add_lake_page.dart
│   ├── chat_inside.dart
│   ├── chats_page.dart
│   ├── home_page.dart
│   ├── lake_created.dart
│   ├── lake_details_page.dart
│   ├── lake_details_page_announcement.dart
│   ├── lake_details_page_members.dart
│   ├── lake_details_page_milestone.dart
│   ├── lake_details_page_overview.dart
│   ├── lake_drafts_page.dart
│   ├── lakes_page.dart
│   ├── login.dart
│   ├── profile_page.dart
│   ├── saved_draft.dart
│   ├── share_to_chats_page.dart
│   ├── sign_up.dart
│   └── welcome_page.dart
├── services/            # API clients and business logic
│   ├── achievements_service.dart
│   ├── auth.dart
│   ├── auth_interceptor.dart
│   ├── chat_service.dart
│   ├── chat_socket_service.dart
│   ├── chat_storage_service.dart
│   ├── deep_link_service.dart
│   ├── draft_service.dart
│   ├── lake_service.dart
│   ├── loading_state_service.dart
│   ├── local_notification_service.dart
│   ├── native_share_service.dart
│   ├── notification_state_service.dart
│   ├── token.dart
│   ├── user_service.dart
│   └── user_storage.dart
├── utils/               # Helper functions and configurations
│   ├── api_config.dart
│   └── username_generator.dart
└── widgets/             # Custom widget components

test/
├── e2e/                 # End-to-end tests
│   ├── auth_e2e_test.dart
│   ├── chat_e2e_test.dart
│   ├── lake_management_e2e_test.dart
│   ├── lakes_discovery_e2e_test.dart
│   └── profiles_e2e_test.dart
├── services_unit/       # Unit tests for services
│   ├── achievements_service_test.dart
│   ├── auth_interceptor_test.dart
│   ├── auth_service_test.dart
│   ├── chat_service_test.dart
│   ├── chat_socket_service_test.dart
│   ├── chat_storage_service_test.dart
│   ├── deep_link_service_test.dart
│   ├── draft_service_test.dart
│   ├── lake_core_test.dart
│   ├── loading_state_service_test.dart
│   ├── local_data_test.dart
│   ├── notification_state_service_test.dart
│   └── user_and_token_test.dart
└── utils/               # Helpers

Folder Descriptions

lib/

• components/: Reusable UI pieces extracted from pages for better readability and reusability
• models/: Data structures used across the app (User, Lake, Message, Notification)
• pages/: Main application screens and views
  • Authentication: welcome_page, login, sign_up
  • Home & Navigation: home_page
  • Lakes: lakes_page, lake_details_page (with tabs: overview, milestone, members, announcement), add_lake_page, lake_created, lake_drafts_page, saved_draft
  • Chat: chats_page, chat_inside, share_to_chats_page
  • User: profile_page, achievements_page
• services/: Business logic, API clients, storage management, and state services
  • Authentication and authorization (auth, auth_interceptor, token)
  • Chat functionality (chat_service, chat_socket_service, chat_storage_service)
  • Lake management (lake_service, achievements_service, draft_service)
  • User management (user_service, user_storage)
  • Notifications (local_notification_service, notification_state_service)
  • UI state (loading_state_service)
  • Other utilities (deep_link_service, native_share_service)
• utils/: Configuration files, constants, and utility functions
• widgets/: Custom Flutter widgets

test/

• e2e/: End-to-end tests that interact with real backend services
• services_unit/: Isolated unit tests for individual services
• utils/: Utility functions for testing

Getting Started

Prerequisites

• Flutter SDK 3.9.2 or higher
• Dart SDK 3.9.2 or higher
• Android Studio / Xcode (for mobile development)
• A device or emulator for testing

Installation

1. Clone the repository

   git clone https://github.com/i-m-teapot/frontend.git
   cd frontend

2. Install dependencies

   flutter pub get

3. Run the app

   Debug mode:

   flutter run

   Release mode:

   flutter run --release

Building

Android APK:

flutter build apk

Output: build/app/outputs/flutter-apk/app-release.apk

Testing

The project includes comprehensive test coverage with unit, integration, and E2E tests.

Run all tests:

flutter test

Run unit tests:

flutter test test/services_unit

Run E2E tests:

E2E tests interact with the real backend and require environment variables to be enabled.

All E2E tests:

flutter test test/e2e --dart-define=E2E_RUN=true

Authentication:

flutter test test/e2e/auth_e2e_test.dart --dart-define=E2E_RUN=true

Chat (requires valid test user credentials):

flutter test test/e2e/chat_e2e_test.dart --dart-define=E2E_RUN_CHAT=true

Lake Management:

flutter test test/e2e/lake_management_e2e_test.dart --dart-define=E2E_RUN=true

Lakes Discovery:

flutter test test/e2e/lakes_discovery_e2e_test.dart --dart-define=E2E_RUN_LAKES=true

User Profiles:

flutter test test/e2e/profiles_e2e_test.dart --dart-define=E2E_RUN_PROFILES=true

Run tests with coverage:

flutter test --coverage

Test Types:

• Unit Tests (test/services_unit/): Isolated tests for individual service methods with mocked dependencies
• Integration Tests (test/integration/): Tests for component interactions
• E2E Tests (test/e2e/): End-to-end tests against real backend services

Key Features Implementation

Real-time Chat

• WebSocket Protocol: Automatically selects wss:// for HTTPS or ws:// for HTTP
• Message Retry Logic: 5 retry attempts with 2-second intervals
• Offline Support: Messages persist in SQLite and sync when online
• Singleton Pattern: ChatSocket ensures single connection instance

Database Resilience

• Retry Mechanism: Exponential backoff for SQLite lock handling (100ms → 200ms → 400ms)
• Concurrent Access: Handles multiple read/write operations gracefully

Authentication

• Secure Storage: Tokens stored using flutter_secure_storage
• Auto Logout: Clears tokens, notifications, and FCM subscriptions

Configuration

API Configuration

Edit lib/utils/api_config.dart:

class ApiConfig {
  static const String baseUrl = 'https://voda-app.duckdns.org';
}

Known Issues

• Firebase errors in tests (harmless): [core/no-app] No Firebase App '[DEFAULT]' has been created
• Chat E2E tests require valid backend credentials
• The app requires internet connection
• Several features do not function as expected for Android devices that do not have Google Play Services