Quran Tracker

A lightweight, extensible Spring Boot application backed by MongoDB for tracking Quran reading and memorization.
Quran Tracker enables users to record verse entries and associate them with users. The current implementation stores minimal fields for verse entries and users (see API reference below for exact shapes).

---

Key features

• Create, read and delete verse entries.
• Associate verse entries with users.
• Simple REST endpoints suitable for front-end apps, mobile clients, or personal use.
• Persists data using MongoDB.
• Small, modular codebase built with Spring Boot for rapid extension.

---

Tech stack

• Language: Java (Spring Boot)
• Database: MongoDB
• Build tool: Maven
• Lombok is used in the code for getters/setters and constructors.

---

Prerequisites

• Java 17+
• Maven 3.6+
• MongoDB 4.4+ (local or remote instance)

---

Quick start

1. Clone the repository

   git clone https://github.com/abdulwalidal/Quran-Tracker.git
   cd Quran-Tracker

2. Ensure MongoDB is running and reachable.

3. Build and run with Maven

   mvn clean package
   java -jar target/quran-tracker-<version>.jar

   Or run directly:

   mvn spring-boot:run

The application starts on the port configured in your Spring Boot configuration (default Spring Boot port 8080 if not changed).

---

Configuration

Configure MongoDB connection and other Spring Boot properties either in application.properties / application.yml or via environment variables.

Example environment variables (examples only — adjust for your environment):

export SPRING_DATA_MONGODB_URI="mongodb://localhost:27017/quran_tracker"
export SERVER_PORT=8080

Note: The repository does not include a committed application.properties with production configuration; provide your own configuration appropriate for your environment.

---

API reference

The implementation in this repository exposes the controller endpoints directly under the paths used in code (there is no global /api prefix).

Server base URL (examples): http://localhost:8080

Controllers and endpoints in the code:

• Verse endpoints are under: /verse
• User endpoints are under: /user

Exact request and response shapes are inferred from the entity classes in src/main/java/com/abdul/qurantracker/Entity.

Entity shapes (exact fields present in the code)

• VerseEntry (collection: verse_entries)

  • id: ObjectId (generated by MongoDB)
  • surah: String (required for POST)
  • verseNo: String (required for POST)
  • memorized: boolean

• User (collection: users)

  • id: ObjectId (generated by MongoDB)
  • userName: String
  • password: String
  • verseEntry: List (DBRef list of verse entries)

Important: The current code requires only the fields above. Fields such as text, notes, progress, or status do not exist in the current entity classes and therefore are not accepted by the API unless you add them to the code.

---

Verse endpoints

1. Create a new VerseEntry and attach to a user
   POST /verse/{userName}

• Description: Saves a VerseEntry and associates it to the user with the provided userName. The service validates that surah and verseNo are present (non-null, non-empty). If the userName is not found or required fields are missing, the call returns an error.
• Request body: JSON representation of VerseEntry (only fields present in the entity are used)
• Success response: 200 OK with body "Verse added Successfully"
• Error response: 400 Bad Request with error message (controller wraps RuntimeExceptions and returns 400)

Example (create not memorized):

curl -X POST "http://localhost:8080/verse/abdulwalidal" \
  -H "Content-Type: application/json" \
  -d '{
    "surah": "Al-Fatiha",
    "verseNo": "1",
    "memorized": false
  }'

Example (create memorized):

curl -X POST "http://localhost:8080/verse/abdulwalidal" \
  -H "Content-Type: application/json" \
  -d '{
    "surah": "Al-Baqarah",
    "verseNo": "255",
    "memorized": true
  }'

Notes:

• The path must use an existing userName (UserService#getUserbyUsername is used). If the userName does not exist, you will receive an error.
• Required fields checked by service: surah, verseNo.

2. List all verse entries
   GET /verse

• Description: Returns all stored VerseEntry documents (from VerseEntryRepository.findAll()).
• Example:

curl -sS http://localhost:8080/verse

3. Delete all verse entries
   DELETE /verse

• Description: Deletes all verse entries (VerseEntryRepository.deleteAll()).
• Example:

curl -X DELETE http://localhost:8080/verse

Note: There is an update service method (updateVerseEntry) in the services layer, but there is no controller mapping exposed for updating a verse by id in the current code.

---

User endpoints

1. Create a user
   POST /user

• Request body: JSON representation of User (fields in entity: userName, password)
• Example:

curl -X POST "http://localhost:8080/user" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "abdulwalidal",
    "password": "secret"
  }'

2. List all users
   GET /user

• Example:

curl -sS http://localhost:8080/user

3. Get user by id
   GET /user/{id}

• Path param: ObjectId
• Example:

curl -sS http://localhost:8080/user/615e6a2f9b1f0b001234abcd

4. Delete user by id
   DELETE /user/{id}

• Example:

curl -X DELETE http://localhost:8080/user/615e6a2f9b1f0b001234abcd

5. Update user by id
   PUT /user/{id}

• Body: partial User JSON (userName and/or password)
• Example:

curl -X PUT "http://localhost:8080/user/615e6a2f9b1f0b001234abcd" \
  -H "Content-Type: application/json" \
  -d '{
    "userName": "newname",
    "password": "newpass"
  }'

---

Validation behavior (current code)

• When creating (saving) a VerseEntry, the service checks:
  • myEntry != null
  • myEntry.getSurah() is non-null and non-empty
  • myEntry.getVerseNo() is non-null and non-empty
• If these checks fail, the service throws a RuntimeException; the controller returns a 400 with the message prefixed by "Error".
• On successful save, the verse is stored via the VerseEntryRepository and is added to the User's verseEntry list; the User is saved again.

---

Development & testing

• Run unit tests:

  mvn test

• Run directly from your IDE:

  • Open the project in IntelliJ IDEA or your preferred IDE.
  • Locate the Spring Boot main class com.abdul.qurantracker.QurantrackerApplication and run it.

---

Contributing

Contributions are welcome.

Suggested workflow:

1. Fork the repository.
2. Create a feature branch:

   git checkout -b feat/your-feature

3. Implement changes and add tests.
4. Run tests locally:

   mvn test

5. Open a Pull Request with a clear description and test coverage.

When creating issues or PRs, include:

• A concise title and summary.
• Steps to reproduce (for bugs).
• Expected vs actual behavior.
• Logs or stack traces if available.

---

Implementation notes and suggested improvements

• The VerseEntry entity currently stores only surah, verseNo and memorized. If you need fields such as text, notes, progress, or status, add them to VerseEntry.java (Lombok's @Data will provide getters/setters). After adding fields you should:
  • Update service validation and controller examples.
  • Add tests and persist existing DB documents accordingly.
• The service has an update method for VerseEntry but no controller mapping; add an endpoint (e.g., PUT /verse/{id}) if you need update from the API.
• Consider adding authentication and user lookup protections before allowing a client to add verses to a user.
• Consider adding pagination for GET /verse if entries grow large.

---

Acknowledgements

• Built with Spring Boot and MongoDB.
• Uses Lombok for boilerplate reduction.

---

Changelog

• See Git history for detailed changes. Consider adding a CHANGELOG.md for user-facing release notes.

---

To do (suggested)

• Add a Postman collection for the API.
• Add a GitHub Actions workflow to run tests automatically.
• Expand VerseEntry to support notes, text or progress fields if desired.