Skip to content

ElsayedDev/stackoverflow_users_app

Folders and files

NameName
Last commit message
Last commit date

Latest commit

ย 

History

37 Commits
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

๐Ÿ“ฑ Stack Overflow Users App

A Flutter app to browse Stack Overflow users, view their reputation history, and manage bookmarks. Built with Clean Architecture, offline caching, and responsive UI.


๐Ÿš€ Demo Links


โœจ Features

  • Browse Users: Top Stack Overflow users with infinite scroll (sorted by reputation).
  • User Profiles: Avatar, display name, reputation, badge counts (gold/silver/bronze).
  • Reputation History: Paginated timeline with direct links to Stack Overflow posts.
  • Smart Bookmarking:
    • Toggle bookmarks with optimistic UI updates
    • Confirmation dialog before removing bookmarks
    • Success/removal feedback via SnackBars
    • Dedicated "Bookmarked" tab with paginated loading (20 users/page)
    • Real-time sync across All/Bookmarked tabs
  • Offline-First: Hive caches user pages & reputation history for seamless offline browsing.
  • Responsive UI: Adaptive layouts for phones, tablets, portrait & landscape.
  • Error Handling: Empty states, retry buttons, pull-to-refresh, inline error snackbars.
  • Localization: i18n ready with English ARB (extendable to more locales).

๐Ÿ›  Architecture & Stack

Architecture

  • Clean Architecture with clear separation:
    • Data Layer: Remote/local data sources, repositories, models (Freezed), mappers
    • Domain Layer: Entities, repository contracts, use cases
    • Presentation Layer: Cubits (BLoC pattern), UI models, screens/widgets
  • Patterns:
    • PaginatedFetchMixin: Reusable pagination logic with request deduplication
    • Repository pattern with Either<Failure, T> error handling (dartz)
    • Optimistic updates for instant UI feedback

Tech Stack

  • State Management: flutter_bloc (Cubit) + get_it (dependency injection)
  • Networking: dio with custom interceptor for Stack Exchange API key
  • Caching: hive + hive_flutter for offline-first persistence
  • Code Generation:
    • freezed + json_serializable for immutable models
    • build_runner for code generation
    • flutter_gen_runner for type-safe asset references
  • UI/UX:
    • flutter_screenutil for responsive sizing
    • cached_network_image for avatar caching
    • flutter_svg for vector icons
    • html_unescape for Stack Overflow content decoding
  • Utilities:
    • dartz for functional error handling
    • rxdart for reactive streams
    • intl + flutter_localizations for i18n
    • flutter_dotenv for environment config
    • url_launcher for opening Stack Overflow posts

๐Ÿ“‚ Project Structure

lib/
  core/            # bootstrap, di, network, theme, utils, widgets
  features/
    users/         # data / domain / presentation
  generated/       # intl generated files
  l10n/            # localization arb files
  main.dart        # entry point
  my_app.dart      # app widget
test/              # unit & widget tests
integration_test/  # integration tests with Patrol
assets/            # icons, colors

โšก Setup

Prerequisites

  • Flutter 3.24+ and Dart 3.6+
  • Stack Apps API key

Installation

git clone https://github.com/ElsayedDev/stackoverflow_users_app.git
cd stackoverflow_users_app
flutter pub get

Environment

Create .env in project root:

STACK_EXCHANGE_KEY=your_stack_apps_key

๐Ÿ‘‰ For review, a demo key is included (not for production).

Run

flutter run -d <device>

Build

  • Android: flutter build apk --release
  • iOS: flutter build ipa
  • Web: flutter build web

Codegen

dart run build_runner build --delete-conflicting-outputs

๐Ÿงช Testing Strategy

This project maintains comprehensive test coverage across multiple layers to ensure reliability and maintainability.

Test Structure

test/
โ”œโ”€โ”€ features/users/
โ”‚   โ”œโ”€โ”€ data/           # Repository & data source tests
โ”‚   โ”œโ”€โ”€ domain/         # Use case tests
โ”‚   โ””โ”€โ”€ presentation/   # Cubit & widget tests
โ”œโ”€โ”€ helpers/            # Test fakes & builders
โ””โ”€โ”€ widget_test.dart    # App-level smoke test

integration_test/       # End-to-end Patrol tests

Testing Layers & Focus

๐Ÿ”ต Unit Tests

Domain Layer (test/features/users/domain/usecases_test.dart)

  • โœ… Use case delegation to repository
  • โœ… Parameter handling (GetUsers, GetReputation, ToggleBookmark)
  • โœ… Stream-based bookmark watching
  • โœ… Short-circuit logic for empty ID lists

Data Layer (test/features/users/data/users_repository_impl_test.dart)

  • โœ… Remote data fetching with caching
  • โœ… Offline fallback from Hive cache
  • โœ… Bookmark persistence & stream emission
  • โœ… getUserById with cache hits/misses

State Management (test/features/users/presentation/cubits_test.dart)

  • โœ… UsersCubit: first page load, pagination, bookmark stream integration
  • โœ… BookmarksCubit: bookmark stream reactions, paginated user loading by IDs
  • โœ… ReputationCubit: user profile fetch, reputation history pagination

๐ŸŸข Widget Tests

Views (test/features/users/presentation/views/)

  • โœ… HomeView: renders header, tabs, handles tab switching
  • โœ… UsersTab: displays user list, handles empty/error states
  • โœ… BookmarkedUsersTab: shows bookmarked users, empty state messaging
  • โœ… UserReputationPage: profile header, reputation list rendering

Focus Areas:

  • UI element presence (titles, lists, empty states)
  • Tab navigation and filter switching
  • Pull-to-refresh interactions
  • Error/loading state rendering

๐ŸŸฃ Integration Tests (Patrol)

End-to-End Flows (integration_test/)

  • โœ… Home View: full app navigation, tab switching, data loading
  • โœ… Users Tab: scroll, bookmark toggle, visual feedback
  • โœ… Bookmarked Tab: add/remove flow, confirmation dialogs, snackbars
  • โœ… Reputation View: profile display, reputation history, post links

What's Tested:

  • Real navigation flows between screens
  • User interactions (tap, scroll, pull-to-refresh)
  • Bookmark confirmation dialogs & success messages
  • Responsive layout switching (portrait/landscape)
  • Offline-first behavior with mock repository

Test Packages & Tools

Package Purpose Used In
flutter_test Core testing framework All test layers
bloc_test Cubit/Bloc testing utilities State management tests
mocktail Mock objects for dependencies Repository & use case tests
patrol Native integration testing with real gestures End-to-end flows

Running Tests

All Tests:

flutter test

Specific Test File:

flutter test test/features/users/presentation/cubits_test.dart

Integration Tests (requires device/emulator):

# All Patrol tests
dart run patrol test

# Single integration test
dart run patrol test integration_test/home_view_it_test.dart

With Coverage:

flutter test --coverage
genhtml coverage/lcov.info -o coverage/html
open coverage/html/index.html

Test Helpers

Mock Repository (test/features/users/data/mock_users_repository.dart)

  • Deterministic fake data (120 users, reputation history)
  • In-memory bookmark storage
  • Configurable delays for async testing

Test Fakes (test/helpers/fakes.dart)

  • StubUsersRepository: minimal stub for quick tests
  • FakeUsersLocalDataSource: in-memory Hive simulation
  • FakeUsersRemoteDataSource: controlled API responses
  • Entity/model builders for test data construction

Coverage Goals

  • โœ… Use Cases: 100% (all delegate correctly)
  • โœ… Repository: Core flows covered (fetch, cache, bookmarks)
  • โœ… Cubits: State transitions & pagination logic
  • โœ… Views: Key user journeys & error states
  • โœ… Integration: Critical paths (browse โ†’ bookmark โ†’ reputation)

CI/CD Integration

Ready for automated testing pipeline:

# Example GitHub Actions workflow
- flutter analyze          # Lint & static analysis
- flutter test --coverage  # Unit & widget tests with coverage
- dart run patrol test     # Integration tests (on tagged releases)

Note: CI workflow not yet configured. See .github/workflows/ for setup templates.


๐Ÿ“Œ Notes

  • .env Security: Committed only for review purposes โ†’ must be .gitignored in production.
  • Offline-First: Hive stores user pages & reputation history; app works seamlessly offline after initial data load.
  • Error Handling: Comprehensive UX with snackbars, empty states, retry buttons, and pull-to-refresh.
  • Bookmark UX: Confirmation dialog before un-bookmarking; success/removal feedback via SnackBars.
  • Responsive Design: Adaptive layouts for portrait and landscape on phones & tablets.
  • Optimistic Updates: Bookmark toggles update UI immediately, rolling back only on failure.
  • Stream Synchronization: Real-time bookmark state synced across All/Bookmarked tabs via RxDart streams.

๐Ÿ”ฎ Future Improvements

  • Testing & CI:
    • Set up GitHub Actions workflow for automated testing
    • Add unit tests for widget-level bookmark feedback
    • Expand integration test coverage for error scenarios
  • UI/UX Enhancements:
    • Dark theme support with theme switcher
    • Skeleton loaders during initial fetch
    • Enhanced accessibility (screen readers, semantic labels)
    • Advanced filters (location, badges, reputation range)
    • Connectivity awareness: show โ€œNo internetโ€ banner and gracefully fallback to cached data
  • Localization:
    • Add more locales (Arabic, Spanish, etc.)
    • Runtime language switching without restart
  • Performance:
    • Smarter cache invalidation strategies
    • Image optimization and progressive loading
    • Background sync for bookmarks
  • DevOps:
    • Automated release pipelines (APK/TestFlight/Web)
    • Crashlytics/Firebase Analytics integration
    • A/B testing infrastructure

๐Ÿ‘ค Author

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Packages

No packages published