A local-first mobile application for tracking halaqa (Islamic study circle) progress, designed to work offline with seamless synchronization to a backend API.

Zamzam Application enables users to manage organizations, halaqat, and track daily learning progress. The app prioritizes offline functionality, storing data locally on the device and syncing changes when connectivity is available. This ensures uninterrupted usage in areas with poor internet access.

The application consists of two main components:

• Framework: Spring Boot 3.5.6 with Java 21
• Database: PostgreSQL with JPA/Hibernate
• Security: JWT-based authentication
• Features: RESTful API for user management, organizations, halaqat, and progress tracking
• Sync: Incremental sync endpoint for data synchronization

• Framework: Flutter with Dart 3.9+
• Database: SQLite for local storage
• State Management: Provider pattern
• Features: Offline-first UI with automatic sync
• Connectivity: Checks network status for sync operations

• User Authentication: Secure login/logout with JWT tokens
• Organization Management: Create and join organizations
• Halaqa System: Manage study circles with member assignments
• Progress Tracking: Record daily learning progress (hifz, revision, remarks)
• Offline Support: Full functionality without internet connection
• Automatic Sync: Background synchronization when online
• Cross-Platform: iOS and Android support

• Spring Boot 3.5.6
• Java 21
• PostgreSQL
• Spring Security
• Maven
• Docker

• Flutter 3.9+
• Dart
• SQLite (sqflite)
• Provider
• HTTP client
• Connectivity checking

• Backend:

  • Java 21 or higher
  • Maven 3.6+
  • Docker and Docker Compose
  • PostgreSQL (or use Docker)

• Frontend:

  • Flutter SDK 3.9+
  • Android Studio or Xcode for mobile development
  • Android/iOS device or emulator

git clone <repository-url>
cd zamzamapplication

Navigate to the backend directory:

cd zamzam-api

docker-compose up --build

This will start PostgreSQL and the Spring Boot API.

1. Install PostgreSQL and create a database:

   CREATE DATABASE zamzam_db;
   CREATE USER zamzam_user WITH PASSWORD 'zamzam_password';
   GRANT ALL PRIVILEGES ON DATABASE zamzam_db TO zamzam_user;

2. Configure Database: Update src/main/resources/application.properties if needed (default is set for Docker).

3. Run the Application:

   mvn clean install
   mvn spring-boot:run

The API will be available at http://localhost:8080.

Navigate to the frontend directory:

cd ../zamzam-flutter

1. Install Dependencies:

   flutter pub get

2. Run the Application:

   flutter run

This will launch the app on connected device/emulator.

• Swagger UI: Available at http://localhost:8080/swagger-ui.html when backend is running
• Postman Collection: Import zamzam-api/zamzam-api.postman_collection.json
• Sync Endpoint: GET /api/sync?since=<timestamp> for incremental data sync

zamzamapplication/
├── zamzam-api/              # Spring Boot backend
│   ├── src/main/java/com/zamzam/zamzamapi/
│   │   ├── controller/      # REST endpoints
│   │   ├── entity/          # JPA entities
│   │   ├── repository/      # Data access
│   │   ├── service/         # Business logic
│   │   └── dto/            # Data transfer objects
│   ├── src/main/resources/
│   │   └── application.properties
│   ├── pom.xml
│   ├── docker-compose.yml
│   └── README.md
├── zamzam-flutter/          # Flutter frontend
│   ├── lib/
│   │   ├── models/          # Data models
│   │   ├── pages/           # UI screens
│   │   ├── services/        # API and sync services
│   │   ├── providers/       # State management
│   │   └── database/        # Local DB helper
│   ├── pubspec.yaml
│   └── README.md (if exists)
└── README.md                # This file

cd zamzam-api
mvn test

cd zamzam-flutter
flutter test

cd zamzam-flutter
flutter analyze

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow existing code style
• Write tests for new features
• Update documentation as needed
• Ensure offline functionality works

• Add CI/CD pipeline
• Write comprehensive tests
• Move JWT secret to environment variables
• Fix sync POST endpoint

• Implement forget password functionality
• Add logout in burger menu
• Complete organization and halaqa pages
• Finalize API integration and storage

This project is licensed under the MIT License - see the LICENSE file for details.

For questions or support, please open an issue in the repository.