diff --git a/README.md b/README.md
index 904b920..ed31ff1 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,39 @@
# mARine – Marine Biology AR App
-
- [](https://www.gnu.org/licenses/agpl-3.0)
- [](https://github.com/Catrobat/mARine)
- [](https://unity.com/)
- [](https://summerofcode.withgoogle.com/)
+
+[](https://www.gnu.org/licenses/agpl-3.0)
+[](https://github.com/Catrobat/mARine)
+[](https://unity.com/)
+[](https://summerofcode.withgoogle.com/)
+
-Revolutionizing marine biology education through immersive AR! mARine transforms abstract marine science concepts into tangible interactive experiences, enabling educators to create custom underwater learning environments where students explore marine ecosystems and experiment with environmental variables in real-time.
+---
+
+## Overview
+
+mARine is an Augmented Reality (AR) platform designed to enhance marine biology education.
+
+It transforms abstract marine science concepts into interactive underwater experiences, enabling users to explore ecosystems, study marine life behavior, and experiment with environmental variables in real time.
+
+Built with Unity, the platform supports both educators and students in creating simulation-based learning environments.
---
## Table of Contents
-- [Features](#features)
-- [Screenshots](#screenshots)
-- [Getting Started](#getting-started)
- - [Prerequisites](#prerequisites)
- - [Installation](#installation)
-- [Contributing](#contributing)
-- [License](#license)
+- [Features](#features)
+- [Screenshots](#screenshots)
+- [Getting Started](#getting-started)
+ - [Prerequisites](#prerequisites)
+ - [Installation](#installation)
+- [Project Architecture](#project-architecture)
+- [Dependencies](#dependencies)
+- [Build & Deployment](#build--deployment)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
---
@@ -30,7 +43,7 @@ Revolutionizing marine biology education through immersive AR! mARine transforms
- **Intuitive Module Builder**: Drag-and-drop interface for educators to create custom learning scenarios without technical expertise
- **Realistic Marine Life Simulation**: Authentic 3D models with natural swimming behaviors, predator-prey interactions, and species-specific characteristics
- **Environmental Control Interface**: Real-time sliders for temperature, pH, and pollution levels with immediate visual feedback
-- **Cross-platform compatibility**: Unity-based, supporting Android with ARCore and iOS with ARKit
+- **Cross-platform Compatibility**: Unity-based, supporting Android (ARCore) and iOS (ARKit)
- **Human Pose Detection**: MediaPipe-based natural gesture interactions with AR marine environments
- **QR Code Sharing System**: Instant module distribution for classroom deployment
- **Immersive Effects**: Realistic underwater atmosphere with volumetric water rendering and dynamic lighting
@@ -40,20 +53,18 @@ Revolutionizing marine biology education through immersive AR! mARine transforms
## Screenshots
---
@@ -62,106 +73,202 @@ Revolutionizing marine biology education through immersive AR! mARine transforms
### Prerequisites
-### For Educators & Students
+#### For Educators & Students
-- **Hardware Requirements:**
- - AR-compatible mobile device (With ARCore/ARKit support)
- - Minimum 4GB RAM
- - 2GB available storage space
+- AR-compatible mobile device (ARCore / ARKit)
+- Minimum 4GB RAM
+- 2GB available storage
-### For Developers
+#### For Developers
-- **Hardware Requirements:**
- - RTX 2050 or higher
- - Minimum 8GB RAM
- - 25GB available storage space
+- GPU: RTX 2050 or higher
+- Minimum 8GB RAM
+- 25GB available storage
-### Installation
+---
+
+## Installation
### For Educators & Students
-1. **Download the App**
- - [MarineBiology_AR](https://drive.google.com/file/d/1o4Zu4FMbyJZXPOKiPRe0a28uvSHgDGBP/view?usp=sharing) for Android
+Download the application:
-2. **Get Started**
- - Download the application
- - Launch the application
- - Complete interactive tutorials
- - Navigate through different modules of the application
+- [MarineBiology_AR](https://drive.google.com/file/d/1o4Zu4FMbyJZXPOKiPRe0a28uvSHgDGBP/view?usp=sharing) for Android
+
+Steps:
+
+1. Install the application
+2. Launch the app
+3. Complete onboarding
+4. Explore modules
+
+---
### For Developers
-1. **Clone Repository**
- ```bash
- git clone https://github.com/Catrobat/mARine.git
- cd mARine
- ```
+#### Clone Repository
-2. **Open in Unity**
- ```text
- # Editor and recommended version
- Install Unity 6.0LTS (or newer).
-
- # Open the project from Unity Hub
- From Unity Hub, click Add Project and select the mARine folder.
+ git clone https://github.com/Catrobat/mARine.git
+ cd mARine
- # Unity will automatically handle packages and dependencies
- Let Unity resolve and import dependencies.
- ```
+#### Open in Unity
-3. **Dependencies**
- ```text
- # Add Vuforia Software Development Kit
- Vuforia Engine SDK – AR target recognition & tracking.
+- Install Unity 6000.1.9f1 LTS (or newer)
+- Open Unity Hub
+- Add project from disk
+- Select the mARine folder
+- Allow Unity to resolve dependencies
- # Add human pose detection with MediaPipe Unity Plugin
- MediaPipe Unity Plugin (homuler fork) for pose detection.
+---
- # Add both packages in Unity
- Ensure both are installed via Unity's Package Manager or as custom packages.
- ```
+## Project Architecture
+
+### Overview
+
+ Assets/
+ ├── Scripts/ # Core logic and gameplay systems
+ ├── Scenes/ # Main AR environments
+ ├── Prefabs/ # Reusable game objects
+ ├── Models/ # 3D marine assets
+ ├── Materials/ # Rendering materials
+ ├── Textures/ # Texture assets
+ ├── Shaders/ # Custom shaders
+ ├── Plugins/ # External integrations
+ ├── XR/ # XR configurations
+ └── XRI/ # XR Interaction Toolkit
+
+---
+
+### Detailed Structure
+
+ Assets/
+ │
+ ├── #NVJOB Boids/ # Boids simulation system
+ ├── AddressableAssetsData/ # Unity addressable asset configuration
+ ├── Animations/ # Animation assets
+ ├── Audio/ # Sound and audio files
+ ├── Custom-create/ # Custom user-created content
+ ├── Editor/ # Unity editor scripts and tools
+ ├── Icons/ # UI icons and sprites
+ ├── Input Maps/ # Input system configurations
+ ├── Joystick Pack/ # Joystick input assets
+ ├── Localization/ # Multi-language support
+ ├── Map_Layouts/ # Scene/environment layouts
+ ├── Materials/ # Rendering materials
+ ├── MediaPipeUnity/ # Pose detection integration
+ ├── MobileARTemplateAssets/ # AR template assets
+ ├── Models/ # 3D models and marine assets
+ ├── Oculus/ # Oculus/VR related assets
+ ├── Plugins/ # External plugins
+ ├── Post-Processing Profiles/ # Visual effects configurations
+ ├── Prefabs/ # Reusable game objects
+ ├── Resources/ # Runtime-loaded assets
+ ├── Samples/ # Sample/demo content
+ ├── Scanner/ # Scanning/AR detection features
+ ├── Scenes/ # Main scenes and environments
+ ├── Scripts/ # Core logic and gameplay scripts
+ ├── Settings/ # Project configuration settings
+ ├── Shaders/ # Custom shaders
+ ├── Sketchfab For Unity/ # Sketchfab asset integration
+ ├── StreamingAssets/ # Raw assets included in builds
+ ├── TextMesh Pro/ # Text rendering system
+ ├── Textures/ # Texture assets
+ ├── UIWithFog/ # UI effects with fog rendering
+ ├── UMS_LODs/ # Level of Detail system assets
+ ├── XR/ # XR core configurations
+ └── XRI/ # XR Interaction Toolkit
+
+---
+
+## Dependencies
-4. **Build Settings**
- - Go to File → Build Settings.
- - Choose Android or iOS as target platform.
- - Switch Platform.
- - Make sure ARCore/ARKit is enabled in XR Plug-in Management.
+The project relies on the following external SDKs and plugins:
-5. **Deploy to Device**
- - Connect your ARCore/ARKit compatible device.
- - Run as a development build or
- - Configure signing (keystore for Android, provisioning profile for iOS) to bundle.
- - Click Build and Run.
+### Vuforia Engine SDK
+
+AR target recognition and tracking.
+
+- Website: https://developer.vuforia.com/
+- Unity Setup Guide: https://developer.vuforia.com/library/vuforia-engine/getting-started/development-environments/getting-started-vuforia-engine-unity/
+
+---
+
+### MediaPipe Unity Plugin (homuler fork)
+
+Human pose detection and gesture interaction.
+
+- GitHub Repository: https://github.com/homuler/MediaPipeUnityPlugin
+
+---
+
+### Installation
+
+1. Open Unity Package Manager or import custom packages
+2. Add Vuforia Engine (via Unity or official package)
+3. Import MediaPipe Unity Plugin from GitHub
+4. Ensure all dependencies are resolved before running the project
+
+---
+
+## Build & Deployment
+
+- Go to File → Build Settings.
+- Choose Android or iOS as target platform.
+- Switch Platform.
+- Make sure ARCore/ARKit is enabled in XR Plug-in Management.
+- Connect your ARCore/ARKit compatible device.
+- Run as a development build or
+ - Configure signing (keystore for Android, provisioning profile for iOS) to bundle.
+- Click Build and Run.
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+| -------------- | ---------------------------- |
+| AR not working | Enable XR Plug-in Management |
+| Vuforia error | Add license key |
+| Black screen | Enable camera permissions |
+| Shader issues | Use URP pipeline |
---
## Contributing
-Contributions are welcome from educators, developers, marine biologists, and educational technology specialists! Here's how you can help:
+Contributions are welcome from educators, developers, marine biologists, and educational technology specialists! Here's how you can help.
+
+### Ways to Contribute
-**Ways to Contribute:**
- **Educational Content**: Create curriculum-aligned modules and lesson plans
- **Technical Development**: Implement features, optimize performance, fix bugs
- **Scientific Accuracy**: Validate biological behaviors and ecosystem modeling
- **Accessibility**: Improve platform accessibility for diverse learners
- **Documentation**: Enhance guides and educational resources
-**Contribution Process:**
+### Contribution Process
+
+### Contribution Process
+
+1. Fork the repository
+2. Create a new branch:
-1. **Fork** the repository
-2. Create a feature branch:
```bash
git checkout -b feature/your-enhancement
```
-3. **Develop & Test**: Follow Test-Driven Development and Clean Code principles
-4. Commit your changes with meaningful messages
-5. Push to your fork and open a **pull request**
-6. Include detailed description with educational rationale and technical notes
-Please adhere to the existing code style and ensure changes are well-tested in both Unity editor and device environments.
+3. Make your changes and test them
+4. Commit your changes:
----
+ ```bash
+ git commit -m "Add: short description of your changes"
+ ```
-## License
+5. Push to your fork:
+
+ ```bash
+ git push origin feature/your-enhancement
+ ```
-This project is licensed under the **[GNU Affero General Public License v3.0](LICENSE)**.
+6. Open a Pull Request with a clear description of your changes
+ s.