Developer Guide¶

Welcome to the ShopSync Developer Guide! This section provides comprehensive technical documentation for developers who want to contribute to or understand the ShopSync codebase.

Overview¶

ShopSync is built with:

• Flutter - Cross-platform UI framework
• Firebase - Backend services (Auth, Firestore)
• Provider - State management
• Material Design 3 - UI components

Quick Links¶

Getting Started¶

Prerequisites¶

• Flutter SDK (^3.6.0)
• Dart SDK (^3.0.0)
• Firebase project configured
• IDE (Android Studio or VS Code)

Setup¶

1. Clone the repository
2. Run flutter pub get
3. Configure Firebase
4. Run flutter run

See Installation Guide for detailed steps.

Architecture Overview¶

ShopSync follows clean architecture principles:

lib/
├── main.dart              # App entry point
├── screens/               # UI screens
├── widgets/              # Reusable widgets
├── services/             # Business logic
├── models/               # Data models
├── utils/                # Utilities
└── l10n/                 # Localizations

Key Concepts¶

Offline-First¶

ShopSync is designed to work offline:

• Local data persistence
• Sync queue management
• Conflict resolution
• Background synchronization

Real-time Collaboration¶

Multiple users can edit simultaneously:

• Firestore real-time listeners
• Optimistic UI updates
• Automatic conflict resolution

State Management¶

Provider pattern for state:

• ChangeNotifier for reactive state
• Consumer widgets for UI updates
• Scoped providers for feature isolation

Development Workflow¶

Branch Strategy¶

• main - Production-ready code
• develop - Integration branch
• feature/* - New features
• bugfix/* - Bug fixes
• release/* - Release preparation

Code Style¶

Follow Dart/Flutter style guidelines:

• Use flutter format
• Follow naming conventions
• Document public APIs
• Write meaningful commit messages

Testing¶

Write tests for:

• Unit tests for services
• Widget tests for UI components
• Integration tests for user flows

CI/CD¶

Automated pipelines:

• Linting and formatting checks
• Unit and widget tests
• Build verification
• Deployment to stores

Contributing¶

We welcome contributions! See:

• Contributing Guidelines
• Development Setup
• Pull Request Process

API Reference¶

Core Services¶

• SharedPrefs - Local storage wrapper
• GoogleAuth - Authentication service
• ConnectivityService - Network status
• MigrationService - Data migration
• ThemeNotifier - Theme management

See Services Documentation for details.

Firebase Services¶

• Firebase Auth - User authentication
• Cloud Firestore - Real-time database
• Firebase Storage - File storage (future)
• Cloud Functions - Server-side logic (future)

Resources¶

• Flutter Documentation
• Firebase Documentation
• Material Design 3
• Dart Language Tour

Common Tasks¶

Adding a New Screen¶

1. Create file in lib/screens/
2. Define StatefulWidget
3. Add route in main.dart
4. Implement UI
5. Add navigation

Adding a New Service¶

1. Create file in lib/services/
2. Define service class
3. Implement methods
4. Add to providers (if stateful)
5. Document API

Adding Dependencies¶

1. Add to pubspec.yaml
2. Run flutter pub get
3. Import where needed
4. Update documentation

Debugging¶

Common Issues¶

Build Failures:

• Run flutter clean
• Delete pubspec.lock
• Run flutter pub get

Firebase Issues:

• Verify configuration files
• Check security rules
• Review console logs

State Issues:

• Check provider scope
• Verify notifyListeners() calls
• Use Flutter DevTools

Next Steps¶

Ready to dive deeper?

• Architecture Details
• Project Structure
• Firebase Integration
• Contributing Guide

Questions? Open an issue on GitHub.