A Flutter app to browse Stack Overflow users, view their reputation history, and manage bookmarks. Built with Clean Architecture, offline caching, and responsive UI.
- Repository: GitHub Repo
- Android APK: Releases
- ๐ฅ Video Demo: Watch Demo Video
- 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).
- 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
- 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 modelsbuild_runner
for code generationflutter_gen_runner
for type-safe asset references
- UI/UX:
flutter_screenutil
for responsive sizingcached_network_image
for avatar cachingflutter_svg
for vector iconshtml_unescape
for Stack Overflow content decoding
- Utilities:
dartz
for functional error handlingrxdart
for reactive streamsintl
+flutter_localizations
for i18nflutter_dotenv
for environment configurl_launcher
for opening Stack Overflow posts
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
- Flutter 3.24+ and Dart 3.6+
- Stack Apps API key
git clone https://github.com/ElsayedDev/stackoverflow_users_app.git
cd stackoverflow_users_app
flutter pub get
Create .env
in project root:
STACK_EXCHANGE_KEY=your_stack_apps_key
๐ For review, a demo key is included (not for production).
flutter run -d <device>
- Android:
flutter build apk --release
- iOS:
flutter build ipa
- Web:
flutter build web
dart run build_runner build --delete-conflicting-outputs
This project maintains comprehensive test coverage across multiple layers to ensure reliability and maintainability.
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
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
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
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
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 |
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
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 testsFakeUsersLocalDataSource
: in-memory Hive simulationFakeUsersRemoteDataSource
: controlled API responses- Entity/model builders for test data construction
- โ 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)
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.
.env
Security: Committed only for review purposes โ must be.gitignore
d 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.
- 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