-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #78 from Group-5/update/readme
Merge Update/readme into release/v2.0.0
- Loading branch information
Showing
1 changed file
with
284 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,284 @@ | ||
| # Help-Me-Help | ||
| # Help-Me-Help - IDATT1005 Team 5 Portfolio Project Spring 2026 :octocat: | ||
|
|
||
| **TEAM 5 STUDENT NAMES** | ||
|
|
||
| <br> | ||
| <li>Emil Fagerjord</li> | ||
| <li>Mathea Gjerde</li> | ||
| <li>Fredrik Jonathan Marjoni</li> | ||
| <li>Lucy Ciara Herud-Thomassen</li> | ||
| </br> | ||
|
|
||
| ## Project description💻 | ||
|
|
||
| Help-Me-Help (HmH) is a Java desktop application, developed using Maven, designed to help users donate money to legitimate charitable organizations and emergency relief initiatives. | ||
| The application fetches verified organization data from Innsamlingskontrollen (IK), a non-profit foundation that verifies fundraising activities. | ||
| Users can create profiles, track their donation history, and browse organizations by status (approved/pending). | ||
| The application prioritizes security, data persistence, and an intuitive user experience following Don Norman's interaction design principles. | ||
|
|
||
| ## Key Features | ||
|
|
||
| - User authentication and profile management | ||
| - Browse verified and pending organizations with descriptions and logos | ||
| - Make donations to organizations | ||
| - View donation history | ||
| - Data persistence using H2 database | ||
| - Web scraping of organization information (descriptions, logos) from external sources | ||
|
|
||
| ## Project structure 📁 | ||
|
|
||
| --- | ||
| The project follows a standard Maven layout and is organized into clearly separated packages according to responsibility-driven design (RDD). | ||
| All source files are stored under the `src` directory. | ||
|
|
||
| ### Main Package Structure (`src/main`) | ||
|
|
||
| <pre> | ||
| src/main/java/edu/group5/app/ | ||
| ├── App.java (JavaFX Application entry point) | ||
| | | ||
| ├── control/ (Controllers - business logic) | ||
| │ ├── AuthController.java (User login/signup handling) | ||
| │ ├── DonationController.java (Donation processing) | ||
| │ ├── NavigationController.java (Page navigation) | ||
| │ └── OrganizationController.java (Organization data access) | ||
| | | ||
| ├── model/ (Business entities & repositories) | ||
| │ ├── organization/ | ||
| │ │ ├── Organization.java (Organization entity) | ||
| │ │ ├── OrganizationRepository.java (Data access for organizations) | ||
| │ │ ├── OrganizationService.java (Business logic) | ||
| │ │ └── OrganizationScraper.java (Web scraping - descriptions & logos) | ||
| │ ├── user/ | ||
| │ │ ├── User.java (User base class) | ||
| │ │ ├── Customer.java (Customer implementation) | ||
| │ │ ├── UserRepository.java (Data access for users) | ||
| │ │ └── UserService.java (User authentication & registration) | ||
| │ ├── donation/ | ||
| │ │ ├── Donation.java (Donation entity) | ||
| │ │ ├── DonationRepository.java (Data access for donations) | ||
| │ │ └── DonationService.java (Donation processing) | ||
| │ ├── wrapper/ | ||
| │ │ ├── DbWrapper.java (H2 database connection & operations) | ||
| │ │ └── OrgApiWrapper.java (Innsamlingskontrollen API client) | ||
| │ ├── AppState.java (Global application state) | ||
| │ ├── Repository.java (Base repository abstract) | ||
| │ └── DBRepository.java (Database repository abstract) | ||
| | | ||
| ├── view/ (JavaFX UI components) | ||
| │ ├── loginpage/ | ||
| │ │ ├── LoginPageView.java | ||
| │ │ ├── SignUpPageView.java | ||
| │ │ ├── LoginHeader.java | ||
| │ │ └── loginpage.css | ||
| │ ├── homepage/ | ||
| │ │ └── HomePageView.java | ||
| │ ├── causespage/ | ||
| │ │ ├── CausesPageView.java | ||
| │ │ ├── OrganizationCard.java | ||
| │ │ └── causespage.css | ||
| │ ├── organizationpage/ | ||
| │ │ ├── OrganizationPageView.java | ||
| │ │ └── organizationpage.css | ||
| │ ├── donationpage/ | ||
| │ │ ├── DonationPageView.java | ||
| │ │ ├── PaymentCompletePageView.java | ||
| │ │ └── donationpage.css | ||
| │ ├── userpage/ | ||
| │ │ └── UserPageView.java | ||
| │ ├── aboutuspage/ | ||
| │ │ └── AboutUsView.java | ||
| │ └── Header.java | ||
| | | ||
| └── utils/ | ||
| └── ParameterValidator.java (Input validation utilities) | ||
|
|
||
| src/main/resources/ (Static assets - CSS, images, etc.) | ||
| ├── header/ | ||
| │ └── images/ | ||
| │ └── hmh-logo.png (Application logo) | ||
| ├── loginpage/ | ||
| │ └── loginpage.css (Login/signup page styling) | ||
| ├── homepage/ | ||
| │ └── homepage.css (Home page styling) | ||
| ├── causespage/ | ||
| │ └── causespage.css (Organization browsing styling) | ||
| ├── organizationpage/ | ||
| │ └── organizationpage.css (Organization details styling) | ||
| └── donationpage/ | ||
| └── donationpage.css (Donation flow styling) | ||
| </pre> | ||
|
|
||
| ### 📦 Package Responsibilities | ||
|
|
||
| #### Models: Business logic and data entities | ||
|
|
||
| - `Organization`: Represents a charity/relief organization with status, logo, description | ||
| - `User` & `Customer`: User profiles with authentication | ||
| - `Donation`: Records of user donations | ||
| - Services and Repositories implement the business logic and data access layers | ||
|
|
||
| #### Controller: Bridge between UI and business logic | ||
|
|
||
| - `AuthController`: Handles user login/registration with password hashing (BCrypt) | ||
| - `OrganizationController`: Manages organization data retrieval and caching | ||
| - `DonationController`: Processes donations and updates user history | ||
| - `NavigationController`: Coordinates page navigation | ||
|
|
||
| #### View: JavaFX UI components | ||
|
|
||
| - Login/signup pages with form validation | ||
| - Organization browsing with filtering (approved/pending) | ||
| - Donation flow with payment confirmation | ||
| - User profile and donation history | ||
|
|
||
| #### Utils: Helper functions | ||
|
|
||
| - `ParameterValidator`: Validates null, empty, and positive values | ||
|
|
||
| ### JUnit Tests (`src/test`) | ||
|
|
||
| The JUnit tests are stored under `src/test` and mirror the main package structure. These tests cover both positive and negative test of all classes (except `App.java` and UI classes) and their methods ensuring program reliability according to the specification given in the portofolie project descriptions | ||
| <pre> | ||
| src/test/java/edu/group5/app/ | ||
| ├── AppTest.java (Application startup tests) | ||
| ├── control/ | ||
| │ └── (Controller integration tests - to be added) | ||
| ├── model/ | ||
| │ ├── donation/ | ||
| │ │ ├── DonationRepositoryTest.java (Data access layer tests) | ||
| │ │ ├── DonationServiceTest.java (Business logic tests) | ||
| │ │ └── DonationTest.java (Entity tests) | ||
| │ ├── organization/ | ||
| │ │ ├── OrganizationRepositoryTest.java (Data access layer tests) | ||
| │ │ ├── OrganizationScraperTest.java (Web scraping tests - 86% coverage) | ||
| │ │ ├── OrganizationServiceTest.java (Business logic tests) | ||
| │ │ └── OrganizationTest.java (Entity tests) | ||
| │ ├── user/ | ||
| │ │ ├── CustomerTest.java (Customer entity tests) | ||
| │ │ ├── UserRepositoryTest.java (Data access layer tests) | ||
| │ │ └── UserServiceTest.java (Authentication & registration tests) | ||
| │ └── wrapper/ | ||
| │ ├── DbWrapperDonationsTest.java (Database wrapper tests - donations) | ||
| │ ├── DbWrapperUserTest.java (Database wrapper tests - users) | ||
| │ └── OrgApiWrapperTest.java (API client tests) | ||
| ├── utils/ | ||
| │ └── ParameterValidatorTest.java (Input validation tests) | ||
| └── view/ | ||
| └── ViewTest.java (UI component tests) | ||
| </pre> | ||
|
|
||
| ### Maven Layout | ||
|
|
||
| The project uses the standard Maven directory structure, which ensures: | ||
|
|
||
| - clean separation of source and test files | ||
| - compatibility with IDEs such as IntelliJ, VS Code, and Eclipse | ||
| - maintainability and easy future extensions (e.g., persistence or additional views) | ||
|
|
||
| ## Link to repository📚 | ||
|
|
||
| <https://git.ntnu.no/Group-5/Help-Me-Help> | ||
|
|
||
| ## How to run the project📝 | ||
|
|
||
| **Requirements:** | ||
|
|
||
| - Java JDK 25 | ||
| - Maven | ||
| - JavaFX SDK 25.0.1-- | ||
|
|
||
| **Run With Maven:** (Windows + Mac + Linux) | ||
|
|
||
| 1. **Download and Unzip Project:** | ||
| Download project zip from the repository. | ||
|
|
||
| 2. **Navigate to Project Folder:** | ||
| Navigate to project folder in the terminal. | ||
|
|
||
| ```bash | ||
| cd path/to/project/ (linux + mac) | ||
| cd path\to\project\ (windows) | ||
| ``` | ||
|
|
||
| 3. **Run the Application:** | ||
| Start the program by running the main class: | ||
|
|
||
| ```bash | ||
| mvn javafx:run | ||
| ``` | ||
|
|
||
| **Run From JAR: (Windows)** | ||
|
|
||
| 1. Download Project JAR: | ||
| Go to repository and download the JAR. | ||
|
|
||
| 2. Run the JAR in Terminal: | ||
|
|
||
| ```bash | ||
| java --module-path "path\to\javafx\sdk" --add-modules javafx.controls -jar path\to\jar.jar | ||
| - Input: User interactions (login, organization selection, donation amount) | ||
| - Output: JavaFX UI displaying organizations, user profiles, donation confirmations | ||
| 1. **Expected behavior:** | ||
| <br> | ||
| The program allows the user to: | ||
| - Login/signup with validation | ||
| - Browse approved organizations from Innsamlingskontrollen API | ||
| - View organization details (description, logo, status) | ||
| - Complete donation workflow | ||
| - View donation history in user profile | ||
| - Graceful error handling with user-friendly messages | ||
| --- | ||
| ## How to run the tests 🧪 | ||
| This project uses JUnit 5 for unit testing. | ||
| All test classes mirror the main package structure and are stored in `src/test` | ||
| - ### Open the Project | ||
| Open your IDE and select **File > Open Folder**, navigating to the root folder of the project (containing `pom.xml`). | ||
| - ### Run all tests | ||
| To execute the full test suite, run: | ||
| ```bash | ||
| mvn clean test | ||
|
|
||
| This command: | ||
|
|
||
| 1. Cleans old build files | ||
| 2. Compiles the main source code | ||
| 3. Compiles the tests | ||
| 4. Runs all JUnit tests | ||
|
|
||
| --- | ||
|
|
||
| ### Viewing test results | ||
|
|
||
| After the tests finish, Maven creates detailed reports here: | ||
| `target/surefire-reports/` | ||
|
|
||
| Each report includes: | ||
|
|
||
| 1. Test class summaries | ||
| 2. Stack traces for any failures | ||
| 3. Execution times | ||
| 4. Running tests in an IDE | ||
|
|
||
| ## References 🔗 | ||
|
|
||
| For more references and project details, kindly refer yourself to the project report and Wiki pages | ||
|
|
||
| - **GitHub Wiki**: [GitHub Wiki](https://git.ntnu.no/Group-5/Help-Me-Help/wiki) | ||
|
|
||
| - **Innsamlingskontrollen API**: [Innsamlingskontrollen](https://app.innsamlingskontrollen.no/api/public/v1/all) | ||
|
|
||
| --- |