FindMyRoomie

FindMyRoomie is a Web Application that provides a platform for lonely wolves (NC State students) to find roommates of their preference. The stakes are high when it comes to finding your best roommate because this relationship starts with a living relationship 😅. We understand how stressful this can be, especially if you are moving to a new city or country. FindMyRoomie is a one-stop solution to your roommate finding needs. Our software has functionalities that allow you to filter and choose your ideal roommate. But if that is too much work for you, we also provide roommate suggestions based on your preferences! Any NC State student could sign up with their NC State Email address from any corner of the world on our website and begin searching for roommates.

_{GIF from Tenor.}

The software is free for use by anyone, and we also welcome any contributions to improve our software. Please read our CONTRIBUTING.md file for more details). If you would like to cite our repository, please check our CITATION.cff file.

Features of our software

1. Homepage:

The homepage contains the 'Sign in' and 'Sign up' buttons, along with the number of users that have registered.

2. SignUp:

Allows new users to register to our roommate finding portal. The 'Sign up' page asks to enter an NCSU email id and a suitable password which should be strong enogugh.

3. Email Confirmation:

After entering the credentials for signup, a confirmation email is sent to the registered mail id, asking to confirm the resgistration. Upon clicking the link provided in the mail, the account gets confirmed and the user is directly redirected to the welcome page.

4. SignIn:

Allows existing users to login to our website using their credentials.

3. Resetting your password:

In case the user forgets the password, they can enter their registered email id in the 'Forgot your passoword?' tab. An email with a link to set a new password will be sent to the email. Clicking the link will redirect the user to reset their password, and, tada! Password reset!!!

3. Welcome page:

A page with happy Mr. and Mrs. Wolf enjoying each other's company in the background, just like you and your roommates would be ❤️‍🔥.

4. My Profile:

Allows you to introduce whom you are to your future roommate! You are given the opportunity to tell others a little bit about yourself and your preferences. The "Visibility" checkbox in your profile allows you to choose whether you want to be visible to others. If you are looking for roommates, you can toggle it on, and if you have found one (Congratulations 🥳 🥳), you can toggle it off. It's that easy!

5. Find people:

Lists the people looking for roommates just like you. Our "Wolf Filter" lets you filter candidates based on your preferences 🐺. Be choosy!!

6. My room:

Lists your roommates (feature not available yet) and provides roommate suggestions based on your preferences. The similarity scores with other roommate seekers are calculated based on Manhattan Distance, and the people with the top scores are shown as suggestions.

7. About

Elaborates about the project and provides details about the contributors along with a link to our documentation.

The website flow is depicted in the below video:

Sign up:

signup.mp4

Functionalities post sign up:

Resetting password:

3.mp4

Steps to set up the project on your local machine

1. Clone the repository:

git clone https://github.com/rohitgeddam/FindMyRoomie.git

2. Setup the virtual environment:

`python -m venv venv`

3. Activate the virtual environment:

* On Mac/Linux:    

  `source venv/bin/activate`
  
* On Windows:    

  `venv\Scripts\activate`

3. Install required modules and libraries:

`pip install -r requirements.txt`

4. Create .env file at ./src/config/

To setup Gmail to send emails to users, first create a new Gmail account. Under 'Manage your Google Account', enable 2-Step Verification and select suitable app and device under 'App passwords'. Copy the key that is generated and paste it under tha EMAIL_HOST_PASSWORD. Enter the email in EMAIL_HOST_USER.

Paste this in the .env file.

SECRET_KEY=@dr11(7h4n=#@8juk63y(-#bqicdl$9f2okpr@#564=a+-f&*8
DEBUG=True
EMAIL_BACKEND="django.core.mail.backends.smtp.EmailBackend"
EMAIL_HOST=smtp.gmail.com
EMAIL_USE_TLS=True
EMAIL_PORT=587
EMAIL_HOST_USER=
EMAIL_HOST_PASSWORD=

Fill the above field and save.

5. Run the application:

cd src 
python manage.py migrate
python manage.py runserver

After adding another field to Model

Django's way of propagating changes you make to your models (adding a field, deleting a model, etc.) into your database schema.

python manage.py makemigrations
python manage.py migrate

Populate fake data for testing

python manage.py seed_users <number of fake instances>

# creates ten fake users
python manage.py seed_users 10

Automatic tools - GitHub Actions

We use GitHub actions to automate tasks of linting, code coverage, build, tests, and security checks. The codes that perform these actions are stored as .yml files in the .github/workflows directory. The GitHub actions are triggered whenever something is pushed (or pulled) into the remote repository. The results of these automated tasks are shown as badges at the top of this README.md file.

Unit tests:

Unit test are performed everytime there is a push or pull into the repository. For more information about Unit test visit Test README

How to build docs

sphinx-build -b html docs/ docs/build

Code Coverage:

Code Coverage is an important metric that allows us to understand how much of the codebase is tested. Code_Cov.yml performs this task. For more information about Code Coverage, please visit this link.

Flake8 - Code Linting:

We are using Flake8 for linting and syntax checking, and it is performed by Linting.yml. For more information about Flake8, please visit this link. Use flake8 before you push code to GitHub.
Config file present in setup.cfg.

flake8 <directory>

Black - Code Formatter

We are using the Black code formatter to format our code before pushing it to GitHub. For more information about Black, please visit this link.

Run the line below everytime you push to GitHub.
Config file present in pyproject.toml

black --line-length 120 <filename>

If you prefer using Black in VSCode, you can add the below settings in your vscode settings:

{
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": ["--line-length", "120"],
    "python.linting.enabled": true
}

Pre Commit Hooks for Black Code formatting and Flake8 Linting

• run pre-commit install
• Now everytime you commit, Black and Flake8 will run automatically and will not allow you to push if the code standards are not met.

_{Image from Ji Miranda.}

CodeQL

CodeQL.yml performs automated security checks on the codebase and scans it for any vulnerabilities and bugs. For more information about CodeQL, please visit this link.

Privacy Notice

1. What personal details of yours would you be sharing with us and why?

To aid you in your roommate search, to help others find you, and also to provide you with relevant roommate suggestions, you will be asked to share your "Name", "Email", "Date of Birth", "Gender", "Diet", "Hometown", "Degree and Course", "Country of Origin". You are free to include anything in your bio (which could include your Instagram ID and other social media handles).

2. Will we be storing your details, and how will we use them?

Yes, we will be storing them in our database. We will ONLY use this to match you with potential roommates and improve our software.

3. Will we share it with any third-party institutions?

NO. Your data is safe with us 🙂. We will not share/lend/rent your data to any outside institutions/personnel.

4. How long will you store my data?

We retain your information as long as needed to provide you with our services.

5. How to remove my data from the website?

Our current release does not provide you with a mechanism to remove your data directly from our website. You are always free to turn off your visibility. If you still feel the need to remove your data from our website, kindly email one of the contributors from your registered Email ID, and we will take care of the rest!

Technology Used

• Python 3.7+
• Django 4.1.2
• HTML5
• CSS3
• BootStrap v5.2

Roadmap

3 months milestone:

1. Include apartment details in the profile section. The details could include (but are not restricted to) the address of the apartment, the apartment BHK and size, and rent. Users who have already secured a property and are looking for roommates to occupy them could use this functionality.
2. Provide an update for the 'My Room' page, giving users the option to include and display their finalized roommates.
3. Create a platform within the website that allows homeowners to lease or sublease their apartments.
4. Suggest properties based on user filters by scraping it from the web and update the matching algorithm.
5. Implement a chat room that allows users to chat with one another in-webapp.

6 months milestone:

6. Create a mobile application and publish it on App Store and Google Play Store
7. Implement a subleasing option.
8. Improve the matching algorithm.

9 months milestone:

8. Partner with local property agents like Wilson Properties, Trinity Properties, etc. to list their properties on our website.

Contact us:

Rohit Geddam: sgeddam2@ncsu.edu
Arun Kumar Ramesh - arames25@ncsu.edu
Kiron Jayesh - kjayesh@ncsu.edu
Sai Krishna Teja Varma - smanthe@ncsu.edu
Shandler Mason - samason4@ncsu.edu

License:

Distributed under the MIT License. See LICENSE for more information

_{GIF from Tenor.}

Support:

Questions about the software? Kindly contact us through one of the following routes. We are happy to answer all your questions regarding the software.

Feel free to reach out to us in case you encounter issues in the software, for example, issues in signing up, logging in, or any othe features.