1356/lifetimer

LifeTimer Flutter Project

Overview

LifeTimer is a gamified life countdown app where users create a bucket list (up to 20 entries) and start a 1356-day countdown once they finalize their goals. The countdown cannot be stopped, paused, or extended.

Status: Phase 4 (Polish and Release) - Preparing for v1.0.0 launch

Project Structure

This Flutter project follows a clean architecture with feature-based organization:

lib/
├── main.dart                    # App entry point
├── bootstrap/                   # Initialization
│   ├── bootstrap.dart
│   ├── env.dart
│   └── supabase_client.dart
├── core/                        # Cross-cutting concerns
│   ├── theme/
│   │   └── app_theme.dart
│   ├── routing/
│   │   └── app_router.dart
│   ├── widgets/
│   │   ├── primary_button.dart
│   │   ├── app_scaffold.dart
│   │   ├── loading_indicator.dart
│   │   └── empty_state.dart
│   ├── errors/
│   │   ├── failure.dart
│   │   └── error_mapper.dart
│   ├── utils/
│   │   ├── date_time_utils.dart
│   │   └── validators.dart
│   └── services/
│       ├── analytics_service.dart
│       ├── notification_service.dart
│       └── image_cache_service.dart
├── data/                        # Data layer
│   ├── models/
│   │   ├── user_model.dart
│   │   ├── goal_model.dart
│   │   ├── goal_step_model.dart
│   │   ├── activity_model.dart
│   │   └── achievement_model.dart
│   ├── repositories/
│   │   ├── auth_repository.dart
│   │   ├── user_repository.dart
│   │   ├── goals_repository.dart
│   │   ├── countdown_repository.dart
│   │   ├── social_repository.dart
│   │   ├── notifications_repository.dart
│   │   └── achievements_repository.dart
│   └── services/
│       ├── image_search_service.dart
│       ├── pexels_image_search_service.dart
│       └── offline_cache_service.dart
└── features/                    # Feature modules
    ├── auth/
    │   ├── presentation/
    │   │   ├── auth_gate.dart
    │   │   ├── sign_in_screen.dart
    │   │   ├── sign_up_screen.dart
    │   │   └── auth_loading_screen.dart
    │   └── application/
    │       └── auth_controller.dart
    ├── onboarding/
    │   ├── presentation/
    │   │   ├── onboarding_intro_screen.dart
    │   │   ├── onboarding_how_it_works_screen.dart
    │   │   └── onboarding_motivation_screen.dart
    │   └── application/
    │       └── onboarding_controller.dart
    ├── goals/
    │   ├── presentation/
    │   │   ├── goals_list_screen.dart
    │   │   ├── goal_edit_screen.dart
    │   │   └── goal_detail_screen.dart
    │   └── application/
    │       ├── goals_controller.dart
    │       └── goal_detail_controller.dart
    ├── countdown/
    │   ├── presentation/
    │   │   ├── home_countdown_screen.dart
    │   │   ├── bucket_list_confirmation_screen.dart
    │   │   └── countdown_summary_screen.dart
    │   └── application/
    │       └── countdown_controller.dart
    ├── social/
    │   ├── presentation/
    │   │   ├── social_feed_screen.dart
    │   │   ├── leaderboards_screen.dart
    │   │   └── public_profile_screen.dart
    │   └── application/
    │       └── social_controller.dart
    ├── profile/
    │   ├── presentation/
    │   │   ├── profile_screen.dart
    │   │   └── profile_edit_screen.dart
    │   └── application/
    │       └── profile_controller.dart
    ├── settings/
    │   ├── presentation/
    │   │   ├── settings_home_screen.dart
    │   │   ├── appearance_settings_screen.dart
    │   │   ├── notification_settings_screen.dart
    │   │   ├── privacy_settings_screen.dart
    │   │   └── about_challenge_screen.dart
    │   └── application/
    │       └── settings_controller.dart
    ├── analytics/
    │   ├── presentation/
    │   │   └── insights_screen.dart
    │   └── application/
    │       └── insights_controller.dart
    └── achievements/
        ├── presentation/
        │   └── achievements_screen.dart
        └── application/
            └── achievements_controller.dart

Tech Stack

• Framework: Flutter 3.10+
• Language: Dart 3.0+
• State Management: Riverpod
• Backend: Supabase (Auth, Database, Storage, Realtime)
• Navigation: Go Router
• Local Storage: Hive
• Maps: Google Maps Flutter, OpenStreetMap
• Notifications: Flutter Local Notifications
• Charts: fl_chart
• Images: Unsplash API, Pexels API, cached_network_image
• OAuth: google_sign_in, sign_in_with_apple
• Location: geolocator

Getting Started

Prerequisites

1. Flutter SDK (>=3.10.0)
2. Dart SDK (>=3.0.0)
3. Supabase project
4. Google Maps API key (optional)
5. Unsplash API key (optional)
6. Pexels API key (optional)

Setup

1. Clone this repository

2. Install dependencies:

   flutter pub get
   

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your credentials
   

4. Run the app:

   flutter run
   

Key Features

Phase 1 (MVP) ✅

• User authentication (email, Google, Apple)
• Bucket list creation (up to 20 goals)
• 1356-day countdown timer
• Goal progress tracking
• Profile management
• Notifications (daily, weekly, milestones)
• Analytics tracking

Phase 2 (Social) ✅

• Public/private profiles
• Social feed
• Leaderboards
• Following system
• Achievements system

Phase 3 (Advanced) ✅

• Charts and analytics
• Image API integration (Unsplash, Pexels)
• Map integration for location-based goals (Google Maps, OSM)
• Offline support with caching
• Appearance settings (theme, time format)

Phase 4 (Polish and Release) 🚧

• Accessibility improvements
• Performance optimizations
• App store documentation
• Beta testing plan
• Security audit checklist
• Code review checklist
• Release notes
• User guide and FAQ
• Developer documentation
• Beta testing execution
• App store submission

Database Schema

The app uses Supabase PostgreSQL with the following main tables:

• users - User profiles and countdown data
• goals - Bucket list items
• goal_steps - Granular goal milestones
• followers - Social relationships
• activities - Timeline events
• notifications - Notification history
• achievements - User achievements

Architecture Patterns

• MVVM/Clean Architecture with clear separation of concerns
• Repository Pattern for data access
• Riverpod StateNotifier for state management
• Feature-based organization for scalability
• Dependency Injection via providers

Documentation

• Release Notes
• User Guide
• FAQ
• Developer Guide
• App Store Assets
  • Release Preparation Checklist
  • Beta Testing Plan
  • Security Audit Checklist
  • Code Review Checklist
  • App Icon Guidelines
  • Screenshot Guidelines
  • Post-Launch Planning

Testing

The project includes comprehensive test coverage:

• Unit Tests: Core utilities, models, repositories
• Widget Tests: Screen components and interactions
• Integration Tests: End-to-end user flows

Run tests:

flutter test

Development Status

Current Version: 1.0.0 (Pre-release)

The project is in Phase 4 (Polish and Release) with all core features implemented. The app is ready for beta testing and app store submission.

Contributing

Please see DEVELOPER_GUIDE.md for contribution guidelines.

License

This project is licensed under the MIT License.

Support

• Email: support@lifetimer.app
• Twitter: @LifeTimerApp
• Discord: https://discord.gg/lifetimer
• Website: https://lifetimer.app