OneHaven - Caregiver Dashboard

A production-ready Flutter application demonstrating the OneHaven Caregiver dashboard experience. This app showcases solid architecture, state management with Riverpod, offline-first data strategy, and modern UI/UX practices.

Features

• ✅ Mock Authentication - Email/password login with validation
• ✅ Protected Members Dashboard - View list of protected members with pull-to-refresh
• ✅ Screen Time Controls - Toggle screen time settings with optimistic updates
• ✅ Member Details - Detailed view of member information
• ✅ Offline Support - Local caching with Hive, works without internet
• ✅ Background Sync - Pending changes sync when device comes online
• ✅ Skeletal Loaders - Shimmer loading states for better UX
• ✅ Error Handling - Graceful error states with retry functionality
• ✅ Network Monitoring - Real-time connectivity status
• ✅ Multi-Flavor Support - Development, Staging, and Production environments
• ✅ Dark Mode Support - Full light and dark theme implementation
• ✅ Theme Switcher - User can toggle between light, dark, and system themes
• ✅ Responsive Typography - ScreenUtil integration for scalable text across devices
• ✅ Widget & Unit Tests - Comprehensive tests for core widgets and providers
• ✅ Sync Status Indicator - Visual indicator showing pending changes and sync status
• ✅ Accessibility Support - Screen reader labels and semantic hints for better accessibility

Architecture

This project follows Clean Architecture principles with clear separation of concerns:

lib/
├── core/                          # Core utilities and shared components
│   ├── config/                    # App initialization
│   ├── constants/                 # Colors, texts, box names
│   ├── network/                   # API client, endpoints, network checker
│   ├── storage/                   # Hive & SharedPreferences managers
│   ├── theme/                     # App theme, text styles, spacing
│   └── widgets/                   # Reusable widgets (loaders, errors)
│
├── features/                      # Feature modules
│   ├── auth/                      # Authentication feature
│   │   ├── data/                  # Auth repository
│   │   ├── domain/                # Auth service
│   │   ├── presentation/          # Login screen & widgets
│   │   └── providers/             # Riverpod auth providers
│   │
│   └── members/                   # Members feature
│       ├── data/                  # Models, datasources, repository
│       ├── domain/                # Services, sync manager
│       ├── presentation/          # Screens & widgets
│       └── providers/             # Riverpod member providers
│
└── routes/                        # App routing

Layers

1. Presentation Layer - UI components, screens, and widgets
2. Domain Layer - Business logic, services, use cases
3. Data Layer - Repositories, data sources (local & remote), models

Patterns

• Repository Pattern - Abstracts data sources (local/remote)
• Provider Pattern - Dependency injection via Riverpod
• State Management - Riverpod StateNotifier for reactive state
• Offline-First - Local cache with background sync

Getting Started

Prerequisites

• Flutter SDK: 3.9.2 or higher
• Dart SDK: 3.9.0 or higher
• Node.js (for mock server): 14.x or higher

Installation

1. Clone the repository

   git clone <repository-url>
   cd onehaven

2. Install Flutter dependencies

   flutter pub get

3. Generate Hive adapters (if needed)

   flutter pub run build_runner build --delete-conflicting-outputs

the Mock Server

The app uses a local mock server for API simulation.

1. Navigate to mock server directory

   cd mock_server

2. Initialize npm (first time only)

   npm init -y

3. Start the server

   node server.js

   Or using npm:

   npm start

   The server will run at http://localhost:3000 with the following endpoints:

   • POST /api/auth/login - Authenticate user (email + password)
   • POST /api/auth/refresh - Refresh access token using refresh token
   • GET /api/members - Fetch all protected members
   • PATCH /api/members/:id - Update member (e.g., screen time toggle)
   • POST /api/members/sync - Sync pending changes

the App

The app supports three flavors (environments): development, staging, and production.

Start (Development Flavor)

1. Ensure mock server is running (see above)

2. Run the development flavor

   macOS/Linux:

   make dev

   Windows (PowerShell):

   .\run.ps1 dev

   Windows (Command Prompt):

   run.bat dev

   Or using Flutter directly:

   flutter run --flavor development -t lib/main_development.dart

Available Flavors

macOS/Linux:

make dev        # Development (uses localhost:3000)
make staging    # Staging (uses staging API)
make prod       # Production (uses production API)

Windows (PowerShell):

.\run.ps1 dev       # Development
.\run.ps1 staging   # Staging
.\run.ps1 prod      # Production

Windows (Command Prompt):

run.bat dev       # Development
run.bat staging   # Staging
run.bat prod      # Production

VSCode

1. Open Run and Debug panel (Cmd/Ctrl + Shift + D)
2. Select flavor from dropdown (Development, Staging, or Production)
3. Press F5 to run

Credentials

• Email: Any valid email format (e.g., test@example.com)
• Password: Any password with 6+ characters (e.g., password123)

for Release

macOS/Linux:

# Android APK
make build-dev        # Development APK
make build-staging    # Staging APK  
make build-prod       # Production APK

# Android App Bundle (for Play Store)
make bundle-prod

# iOS
make build-prod-ios

Windows (PowerShell):

# Android APK
.\run.ps1 build-dev        # Development APK
.\run.ps1 build-staging    # Staging APK
.\run.ps1 build-prod       # Production APK

# Android App Bundle
.\run.ps1 bundle-prod

Windows (Command Prompt):

REM Android APK
run.bat build-dev        # Development APK
run.bat build-staging    # Staging APK
run.bat build-prod       # Production APK

REM Android App Bundle
run.bat bundle-prod

Configuration

Each flavor has different settings in lib/core/config/environment.dart:

Flavor	App Name	Bundle ID	API URL	Features
Development	OneHaven Dev	com.example.onehaven.dev	http://localhost:3000/api	Debug banner, logging enabled
Staging	OneHaven Staging	com.example.onehaven.staging	https://staging-api.onehaven.com/api	Debug banner, logging, analytics
Production	OneHaven	com.example.onehaven	https://api.onehaven.com/api	No debug banner, analytics only

All three flavors can be installed simultaneously on the same device.

Dependencies

Dependencies

• flutter_riverpod ^2.5.1 - State management
• hive ^2.2.3 & hive_flutter ^1.1.0 - Local database for complex objects
• shared_preferences ^2.2.3 - Simple key-value storage for primitives
• dio ^5.7.0 - HTTP client with interceptors and better error handling
• connectivity_plus ^6.0.3 - Network connectivity monitoring
• shimmer ^3.0.0 - Skeletal loading animations
• cached_network_image ^3.3.1 - Image caching
• flutter_screenutil ^5.9.3 - Responsive UI sizing and scaling
• path_provider ^2.1.3 - File system paths
• intl ^0.19.0 - Internationalization

Dependencies

• hive_generator ^2.0.1 - Code generation for Hive
• build_runner ^2.4.9 - Build system
• flutter_lints ^5.0.0 - Linting rules

Testing

Tests

Run all tests:

flutter test

Run specific test file:

flutter test test/widgets/shimmer_loader_test.dart
flutter test test/widgets/member_list_item_test.dart
flutter test test/providers/member_provider_test.dart

Run tests with coverage:

flutter test --coverage

View coverage report (macOS/Linux):

# Generate HTML coverage report
genhtml coverage/lcov.info -o coverage/html

# Open in browser
open coverage/html/index.html

Results

All 13 tests passing ✅

Coverage

• ✅ Widget Tests (11 tests)

  • test/widgets/shimmer_loader_test.dart - 5 tests
    • Default properties rendering
    • Custom dimensions and border radius
    • Light and dark theme adaptation
  • test/widgets/member_list_item_test.dart - 6 tests
    • Member name, relationship, and age display
    • Active/Inactive status badge display
    • Tap interactions
    • UI component rendering

• ✅ Provider Tests (2 tests)

  • test/providers/member_provider_test.dart
    • Provider type validation
    • State structure verification

Structure

test/
├── widgets/
│   ├── shimmer_loader_test.dart      # Loading widget tests
│   └── member_list_item_test.dart    # Member list item tests
└── providers/
    └── member_provider_test.dart     # Riverpod provider tests

New Tests

Tests are organized by feature and type. To add new tests:

1. Create test file in appropriate directory
2. Initialize environment in setUpAll():

   setUpAll(() {
     EnvironmentConfig.initialize(Environment.development);
   });

3. Use testWidgets() for widget tests
4. Use test() for unit tests

Mock Data

Sample JSON structure for members:

{
  "id": "m001",
  "firstName": "Emma",
  "lastName": "Johnson",
  "birthYear": 2010,
  "relationship": "Daughter",
  "avatar": "https://i.pravatar.cc/150?img=1",
  "status": "active",
  "screenTimeEnabled": true
}

The mock server includes 5 sample members with realistic data.

UI/UX Features

• Modern Design - Clean, intuitive interface with Material Design 3
• Dark Mode - Full light and dark theme support with smooth transitions
• Theme Persistence - User's theme preference saved across app restarts
• Responsive Layout - Works on phones and tablets (portrait mode)
• Responsive Typography - ScreenUtil-powered text scaling for all screen sizes
• Loading States - Shimmer skeletal loaders for better perceived performance
• Error States - User-friendly error messages with retry actions
• Empty States - Helpful messages when no data is available
• Pull-to-Refresh - Intuitive gesture to refresh member list with theme-aware colors
• Optimistic Updates - Instant UI feedback for toggle actions
• Bottom Sheets - Modern bottom sheet UI for options and confirmations
• Protected Members Badge - Visual indicator with member count
• Sync Status Indicator - Shows pending changes count and syncing state
• Accessibility Features - Semantic labels for screen readers, descriptive hints for actions
• Status Badges - Visual active/inactive status indicators on member list items

Local Storage Strategy

This app uses both Hive and SharedPreferences for different purposes:

Two Storage Solutions?

- Complex Object Storage

• Use Case: Storing structured data (Member objects, lists, nested data)
• Benefits:
  • Type-safe with code generation
  • Fast read/write for complex objects
  • Supports custom adapters
  • NoSQL-like document storage
• What We Store:
  • Member list (List<MemberModel>)
  • Screen time toggle states
  • Pending sync queue

- Simple Key-Value Storage

• Use Case: Storing primitive values (strings, bools, ints)
• Benefits:
  • Lightweight and fast
  • Native platform support (NSUserDefaults on iOS, SharedPreferences on Android)
  • Perfect for app settings and auth tokens
  • No code generation needed
• What We Store:
  • Auth token
  • User email
  • Login status (boolean)
  • Last sync timestamp

Decision Matrix

Data Type	Storage	Reason
Member objects	Hive	Complex structured data with relationships
Auth token	SharedPreferences	Simple string, frequently accessed
Toggle states	Hive	Associated with member IDs, needs querying
Login status	SharedPreferences	Simple boolean flag
Pending sync queue	Hive	List of complex change objects
Last sync time	SharedPreferences	Simple timestamp string

This hybrid approach follows the "right tool for the right job" principle, optimizing for both performance and developer experience.

Offline Support & Sync

It Works

1. Initial Load - Fetches data from API and caches locally (Hive)
2. Offline Mode - Displays cached data when no connection
3. Optimistic Updates - UI updates immediately, syncs in background
4. Pending Queue - Failed updates stored in Hive for later sync
5. Auto Sync - Syncs pending changes when connection restored

Flow

User Action → Update Local Cache (Hive) → Update UI → Sync to API
                                                ↓
                                          (If offline)
                                                ↓
                                    Add to Pending Queue (Hive)
                                                ↓
                                          Sync when online

Code Quality

• Type Safety - Full null safety support
• Documentation - Comprehensive dartdoc comments
• Error Handling - Try-catch blocks with custom exceptions
• Linting - Follows Flutter recommended lints
• Formatting - Consistent code style with dart format

AI Usage Summary

This project was developed with AI assistance (Cascade/Claude) for:

AI Was Used For:

1. Architecture Design - Clean architecture structure and folder organization
2. Boilerplate Generation - Models, repositories, providers, and data sources
3. State Management - Riverpod provider setup and StateNotifier patterns
4. Mock Server - Node.js server implementation with REST endpoints
5. Documentation - README, CHANGELOG, and code comments
6. Best Practices - Error handling patterns, offline-first strategy

Understanding:

All AI-generated code has been reviewed and understood. The developer can explain:

• How Riverpod state management works in this app
• The offline-first data strategy and sync mechanism
• Repository pattern and dependency injection
• Hive database operations and type adapters
• Network error handling and retry logic

Ownership:

While AI assisted with code generation, the developer:

• Understands the architecture and can extend it
• Can debug and fix issues independently
• Made architectural decisions (e.g., Riverpod over Bloc)
• Reviewed and validated all generated code

Deliverables

• ✅ GitHub repository with clean commit history
• ✅ Daily commits with descriptive messages
• ✅ README with setup instructions and architecture notes
• ✅ CHANGELOG with daily progress bullets
• ✅ Mock backend with sample data
• ✅ AI Usage Summary (this section)
• ⏳ APK build (optional, pending)
• ⏳ Demo video (optional, pending)

Development Progress

See CHANGELOG.md for detailed daily progress.

Status: Full Implementation Complete ✅

• Project setup and dependencies
• Core infrastructure (storage, network, widgets)
• Data layer (models, repositories, datasources)
• Domain layer (services, business logic)
• State management (Riverpod providers)
• Mock backend and sample data
• UI screens (splash, onboarding, login, dashboard, details)
• Navigation and routing
• Theme system (light/dark mode with persistence)
• Responsive typography with ScreenUtil
• Reusable bottom sheets and widgets
• Widget and provider tests
• Sync status indicator
• Accessibility improvements
• Status badges on member list
• APK build
• Demo video

Contact

For questions or issues, please contact the development team.

AI Usage

This project was developed with AI assistance. For a detailed summary of AI usage, architecture decisions, and development process, see the AI Usage Summary in CHANGELOG.md.

License

This project is part of the OneHaven Flutter Developer Challenge.

---

Built with ❤️ using Flutter & Riverpod