diff --git a/README.md b/README.md
index f186dda..ac54a61 100644
--- a/README.md
+++ b/README.md
@@ -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)
+
+---