Nimble Survey App

A cross-platform mobile survey application built with Flutter that integrates with Nimble's API to provide a seamless survey experience.

Features

Authentication

• OAuth 2.0 authentication flow
• Secure login with email and password
• Password reset functionality
• Secure token storage with encryption

Survey Management

• Browse surveys with pagination
• Local caching for offline access
• Pull-to-refresh functionality
• Dynamic survey data population
• Multiple question types support:
  • Net Promoter Score (NPS)
  • Star Rating
  • Single Choice
  • Multiple Choice (Checkbox)
  • Dropdown Selection
  • Text Input
  • Text Area
  • Smiley Ratings

Platform Support

• Android: API 21+ (Android 5.0 Lollipop and above)
• iOS: iOS 12.0 and above
• Push notifications (iOS)

CI/CD

• Automated builds via GitHub Actions
• Firebase App Distribution integration
• Multi-environment deployment (dev, staging, prod)

Tech Stack

• Framework: Flutter 3.7.2+
• Language: Dart 3.7.2+
• State Management: Riverpod 3.0
• Navigation: go_router
• Networking: Dio + Retrofit
• Local Database: Drift (SQLite)
• Secure Storage: flutter_secure_storage
• Architecture: Clean Architecture with Repository Pattern

For a complete list of dependencies, see pubspec.yaml.

Quick Start

Prerequisites

• Flutter SDK 3.7.2 or higher (Install Flutter)
• Dart SDK 3.7.2 or higher
• Android Studio or VS Code with Flutter extensions
• For iOS: Xcode 14.0+ and CocoaPods
• For Android: JDK 17

Installation

1. Clone the repository

   git clone <repository-url>
   cd SurveyApp

2. Install dependencies

   flutter pub get

3. Set up environment variables

   Create .env.dev, .env.staging, and .env.prod files in the project root:

   # .env.dev
   API_ENDPOINT=https://your-dev-api.com
   CLIENT_ID=your_client_id
   CLIENT_SECRET=your_client_secret

   See .env.sample for the complete template.

4. Generate code

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

5. Run the app

   # Development
   flutter run --flavor dev --dart-define=FLAVOR=dev
   
   # Staging
   flutter run --flavor staging --dart-define=FLAVOR=staging
   
   # Production
   flutter run --flavor prod --dart-define=FLAVOR=prod

Project Structure

lib/
├── core/                      # Core functionality
│   ├── constants/            # App constants
│   ├── local/               # Local storage (Drift)
│   ├── model/               # Data models
│   ├── network/             # API services & interceptors
│   ├── provider/            # Riverpod providers
│   ├── repository/          # Repository implementations
│   ├── ui/                  # Shared UI components
│   └── utils/               # Utility functions
├── features/                 # Feature modules
│   ├── auth/               # Authentication (login, password reset)
│   ├── home/               # Home screen with survey list
│   ├── splash/             # Splash screen
│   └── surveydetails/      # Survey details and questions
├── l10n/                    # Localization
├── main/                    # App initialization
└── main.dart               # Entry point

Documentation

Comprehensive documentation is available in the GitHub Wiki:

• Home - Overview and quick links
• Architecture - Application architecture and design patterns
• Setup and Installation - Detailed setup guide
• CI/CD Pipeline - Continuous integration and deployment
• Testing - Testing strategy and guidelines
• API Integration - Nimble API integration details

Development

Running Tests

# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run integration tests
flutter test integration_test

Code Generation

When you modify models, services, or providers:

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

Linting

# Analyze code
flutter analyze

# Format code
dart format .

Build

# Android APK (Development)
flutter build apk --flavor dev --dart-define=FLAVOR=dev

# Android App Bundle (Production)
flutter build appbundle --flavor prod --dart-define=FLAVOR=prod

# iOS (Production)
flutter build ios --flavor prod --dart-define=FLAVOR=prod

CI/CD Pipeline

The project uses GitHub Actions for automated builds and deployments:

• Pull Request Review: Runs tests and linting on PRs
• Development Deployment: Auto-deploys to Firebase on push to develop
• Staging Deployment: Auto-deploys to Firebase on push to staging
• Production Deployment: Auto-deploys to Firebase on push to main

Builds are distributed via Firebase App Distribution.

See CI/CD Pipeline documentation for details.

Environment Configuration

The app supports three environments:

Environment	Branch	Purpose
Development	develop	Development and testing
Staging	staging	Pre-production testing
Production	main	Production-ready releases

Each environment has its own:

• API endpoint
• OAuth credentials
• Firebase project
• Build flavor

Contributing

We welcome contributions! Please read our Contributing Guide to get started.

Development Workflow

1. Create a branch from develop
2. Make your changes with tests
3. Run tests and linting
4. Create a pull request
5. Wait for review and approval

See the Contributing Guide for detailed guidelines.

Testing

The project includes:

• Unit tests for business logic
• Widget tests for UI components
• Integration tests for user flows

Test coverage target: 70%+

See Testing Guide for more information.

Architecture

The app follows Clean Architecture principles:

• Presentation Layer: UI, ViewModels, UI Models
• Domain Layer: Business logic (embedded in repositories/viewmodels)
• Data Layer: Repositories, API Services, Local Storage

Key patterns:

• Repository Pattern for data access
• State Management with Riverpod
• Dependency Injection via providers
• Freezed for immutable models

See Architecture Guide for detailed documentation.

Troubleshooting

Common Issues

Build errors after pulling latest code:

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

iOS pod installation issues:

cd ios
rm -rf Pods Podfile.lock
pod deintegrate
pod install
cd ..

Environment variables not loading:

• Verify .env.* files exist in project root
• Check file naming (.env.dev, .env.staging, .env.prod)
• Ensure no extra spaces in variable assignments

For more troubleshooting tips, see Setup Guide.

Support

For questions or issues:

• Check the GitHub Wiki
• Search existing issues
• Create a new issue

---