By Gareth Llewelyn
Virtual Shelter is an app where animal rescue shelters can upload profiles of their animals for users to virtually foster them and contribute to their care.
Creator's goals...
- to create an additional income stream for animal shelters
User's goals...
- to be able to support a shelter that's important to them
- to enjoy the challenge of fostering a virtual animal in an emotionally engaging way
| User Story ID | As A(n) | I want to be able to | so that I can |
|---|---|---|---|
| Viewing and Navigation | |||
| 1a | Visitor | Understand the purpose of the site immediately | Decide whether I want to engage with it. |
| 1b | User | Navigate and interact with the site on all viewports | Engage with the site on any device. |
| 1c | User | View information about the site | Understand how to use it. |
| User Authentication and Profiles | |||
| 2a | Visitor | Create an account | Access the features of the web app. |
| 2b | User | Log in | Access my profile and interact with the app. |
| 2c | User | Log out | Secure my account after use. |
| 2d | User | Reset my password if I forget it | Regain access to my account. |
| 2e | User | Update my profile details | Keep my information current. |
| 2f | User | Delete my account | Delete information related to me if I so wish. |
| 2g | Shelter admin | Register as a shelter admin | List my shelter and animals on the site. |
| 2h | Admin | Manage user accounts and shelter profiles | Maintain the integrity of the platform. |
| Animal Shelter Management | |||
| 3a | Shelter admin | Update shelter profile | Keep my shelter's details current. |
| 3b | Shelter admin | Add animal profiles to the shelter's profile | Facilitate their virtual fostering. |
| 3c | Shelter admin | Update animal profiles | Keep information about them accurate and current. |
| 3d | Shelter admin | Delete animal profiles | Remove animals that are adopted. |
| 3e | Shelter admin | Send updates about the animals to their fosterers | Keep them connected and informed. |
| Virtual Fostering | |||
| 4a | User | Browse animals available for virtual fostering | Choose one to support. |
| 4b | User | Virtually foster an animal | Support it through the platform. |
| 4c | User | Interact with a virtual animal | Simulate taking care of it. |
| 4d | User | Receive updates on the real animal I am fostering | Be informed about its well-being. |
| Payments and Sponsorship | |||
| 5a | User | Make secure payments | Support the shelter. |
- Users can navigate through the site easily
- Users get feedback and confirmation for their actions
- Users can use site on a range of device sizes
- Users can register, login, logout and edit profile
- Users can request to be made a Shelter Admin
- Shelter Admins can manage a shelter's profile
- Shelter Admins can upload and manage animal profiles
- Shelter Admins can provide updates on animal profiles
- Users can browse animal profiles to choose which to virtually foster
- Users can customize their own virtual animal from a choice of breeds and colours
- Users can view fostered animals
- Users can take care of fostered animals
- Users can assess animal stats
- Dashboard should update 'live'
- Users can purchase tokens securely via Stripe
- Users can spend tokens on their fostered animals
- Users can upload pictures for profiles
- A variety of sprite sheets for different animals and colours
- Sprites will have multiple states to boost interactivity
- Users can interact with sprite via button(s)
- Sprite stats will be shown and updated live
Logged in users will have the following navbar links: Virtual Shelter(Home), Dashboard, Profile/My Shelter, Shelters, Animals, Log Out. This will enable users to care for their fostered animals, manage their personal information and browse shelters and animals in need of support.
As the dashboard needs to update itself 'live' and when accessed after extended periods of disuse, this project requires the use of AJAX to connect the front end to the backend.
Drawn with Lucid Chart
I asked GPT-4 to create the logo. The then used a favicon generator to create the favicon images and link tags.
This is the colour palette I chose.
The fonts are from Google Fonts. The logo text and home page title use Rock Salt, and the rest is Open Sans.
Bootstrap provides elements such as the navbar, grid layouts and carousels, and also manages screen size responsiveness.
Account management is enabled by the django-allauth package. This handles registration, confirmation emails, login, logout and forgotten password, verification.
When a User is created, a signal is sent to create a Profile for that user. Profiles hold information such as role (User or Shelter Admin) and token count.
The user can view, update and delete their profile. On the Profile page, there is a link to 'Register Shelter'. This provides a form to collect information about the charity. Upon submission, a signal triggers an email to the Superuser informing them of the request. The Superuser can then navigate to the site admin interface, review the request information and decide whether to approve or reject it. If approved, the user's profile role will be updated to that of Shelter Admin.
A Shelter Admin will see a navbar option of 'My Shelter' in place of 'Profile'.
The Shelter Admin can 'Edit Profile', 'Delete Profile' and 'Add Animal' to the shelter profile.
An animal profile can be added to a shelter, and collect information such as a picture upload, name, species, breed, age, description and adoption status. Animal profiles can be edited and deleted. The Shelter Admin can also 'Add Update' about the dog to its profile.
Users can choose to 'Foster' the animal.
If the user chooses to foster an animal, they will be taken to a sprite creation page. Here a the user will be able to select the breed and colour of the animal from the available options.
The user can delete the sprite or 'return to shelter'.
For each animal, the user will see some details of the real animal, including a picture, the animated sprite canvas, an interact button, and a dynamic chart canvas that tracks the sprite's activity.
The dashboard will update 'live' (once per minute, this might vary more on deployed site) without having to refresh the page.
The sprite's state will change depending on its satiation level. (Below 50 => standing, else running).
The user can feed the sprite if enough tokens are available.
Tokens can be bought via a link to a Stripe hosted checkout page. Upon successful 'payment', the user will be redirected to the dashboard with a toast message informing the user of the outcome.
A webhook will update the number of tokens associated with a user's profile.
Users will be able to browse through shelter and animals profiles on these pages.
The respective spritesheets accomodate a range of possible states which could be added to make the game more complex, less predictable and more responsive in a way that may mimick an actual pet. Such states could include Walking, Sitting, Barking, Sleeping, Jumping, Biting, Headbutt and Dying.
The state change handler function could depend on additional stats such as 'happiness', 'health', 'BMI', 'obedience'.
The game could include more specific behaviour probability stats such as 'sit probability' that would increase with training so that a better trained dog would be more likely to sit after the first command.
Additional activities could include training games and then using your dog to complete challenges, such as guiding a dog through a course or sheep herding, where a more obedient and happy dog will be more likely to follow the user's commands.
Another idea could be to be able to 'throw a ball' and have the sprite run after it and maybe bring it back, maybe not, allowing the user to 'reward' upon good behaviour that will increase the 'fetch probability' stat.
Such additional activities would allow for competition and leader boards.
This would require spritesheets of a similar style for other animals such as cats, which are available from the same artist as the dog sprites. The main challenge with this would be to have a separate state change handler that would specifically mimick the behaviour of cats. Different species would also require different additional activities to engage with.
This would prevent an unnecessary income bottleneck that's directly proportional to the number of animals the shelter can accommodate.
One idea to address this was to make it cheaper to take care of smaller animals as each meal would require less food.
Such a dashboard could allow shelter admins to view stats such as income and engagement. Based on such information, a shelter may be able to reward top performers.
- VSCode - Development environment
- Google Chrome Dev Tools - Debugging and analysis
- GitHub - Code repository and version control
- Windows PowerShell - Terminal
- Virtual environment
- GPT-4 - Debugging, guidance
- HTML5
- CSS3
- Bootstrap 5 - Styling and layout framework
- FontAwesome - Icons
- Google Fonts - Fonts
- Coolors.co - To consider different colour palettes
- Python 3.12.1 - Programming language
- Django 5.1 - Framework for rapid development
- Django-allauth - Authentication
- Stripe - Payment service
- Pillow - Image tool
- Boto3 - AWS management
- django-storages - works with Boto3
- gunicorn - WSGI HTTP server
- Psycopg2 - Postgres DB adapter for Python
- crispy-bootstrap5 - Enhances Django forms
See requirements.txt for full dependency list.
- W3C HTML Markup Validator
- W3C Jigsaw CSS Validator
- JSHint - JS validator
- CI Python Linter - Python validator
- W.A.V.E - Accessibility
- Lighthouse - Performance, accessibility, SEO, best practices
- Font Awesome - Icons
- ImageResizer.com - Image compressor
- favicon.io - png to favicon generator
- Figma - To compile individual state sprites into one spritesheet
- PosteSQL - Relational database
- Lucid Chart - Database schema
See TESTING.md for testing documentation.
This project was deployed to Heroku via the following steps...
- Sign in to your Heroku account, having created one.
- Click 'Create new app'.
- Enter app name and region.
- Click 'Create app'.
- In the 'Deploy' tab, in the 'Deployment method' section, select the 'GitHub' option.
- In the 'Connect to GitHub' section below, search for the relevant code repository and click 'Connect'.
Automatic deployment was enabled such that whenever the GitHub repository is updated, the new code would automatically update the Heroku app. This was set up as follows...
- Still on the Deploy tab, in the 'Automatic deploys' section, click 'Enable Automatic Deploys'.
These environment variables must be set on Heroku for the app to work.
- On the Settings tab, in the 'Config Vars' section, click 'Reveal Config Vars'.
- Enter the following variables:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- These keys can be obtained by creating an S3 Bucket on AWS.
- DATABASE_URL
- This was obtained from a PostgreSQL data base provided by Code Institute.
- EMAIL_HOST_PASS
- EMAIL_HOST_USER
- The email address and password for an email account.
- SECRET_KEY
- For cryptographic purposes in Django.
- STRIPE_PUBLIC_KEY
- STRIPE_SECRET_KEY
- STRIPE_WH_SECRET
- These keys can be obtained by creating a Stripe account.
- In the dashboard, click 'Developers'.
- Under 'API keys', you will find your Public and Secret keys.
- Under 'Webhooks', click 'Add endpoint'.
- For the URL, put DOMAIN + 'profiles/stripe-webhook/'
- Under 'Select events to listen to', click '+ Select events'.
- Tick 'Select all events' then press 'Add events'.
- Set the STRIPE_WH_SECRET as the Signing Secret generated as a result.
- USE_AWS
- Set as True.
- Open the Heroku Terminal and run the following command to migrate the database schema.
heroku run python manage.py migrate
- Go to the project's GitHub repository.
- Click the 'Code' dropdown and copy the HTTPS link.
- Create a local directory to keep the repository.
- In the terminal of your IDE, ensure your IDE supports git, such as by running
git init.
- In the terminal, use the copied link in the following command
git clone https://github.com/LlewBach/virtual-shelter.git
- Create a Python Virtual Environment and activate it.
- To install the required packages, run
pip3 install requirements.txt
- To migrate the database, run
python manage.py migrate
- Open the directory in your IDE.
- Create a file called 'env.py' in the 'virtual_shelter' folder.
- In this file, provide the local environment variables. Here is a template.
import os
os.environ.setdefault("SECRET_KEY", "your own value")
os.environ.setdefault("DEVELOPMENT", 'True')
os.environ.setdefault("EMAIL_HOST_PASS", "your own value")
os.environ.setdefault("EMAIL_HOST_USER", "your own value")
os.environ.setdefault("STRIPE_PUBLIC_KEY", 'your own value')
os.environ.setdefault("STRIPE_SECRET_KEY", 'your own value')
os.environ.setdefault("STRIPE_WH_SECRET", 'your own value')- Ben Kavanagh - I referred to the README of my mentor, Ben Kavanagh, to structure my own.
- GirlyPixels - The creator of the purchased spritesheets.
- GPT-4
Helped with / taught me about the following:
- Debugging errors
- How to use Django signals and forms
- How to go implement AJAX fetch requests
- Formatting the Chart.js pie chart
- Setting up the Stripe webhook view
- Testing
- Writing docstrings
-
Web Dev Creative - How To Make Responsive Navbar with Bootstrap 5 | Step by Step Tutorial
-
Lun Dev Code - How To Make Toast Notification In Javascript
- This is how I made my toasts, with only small changes by myself.
I would like to thank my mentor Ben Kavanagh for his guidance and support with this project and my year on this Web Application Development diploma with Code Institute. I will treasure his words of encouragement for the rest of my days.
"Sometimes you just need your finger pulling out of your arse."
Ben Kavanagh
I would also like to thank Oisín from Code Institute's tech support for helping me set up AWS.
This website is for educational purposes only. The Stripe account will therefore remain in Test Mode. The animal profiles are fictitious.