This project implements an online auction platform specialised for antiques and collectibles. The system allows users to buy and sell items through a competitive bidding process, with built-in authentication services for verifying item authenticity.
For more detailed documentation, please visit the Wiki.
You can access a live version of the application here.
- Clone the repository:
git clone https://github.com/COMP2913-24-25/comp2913-team17.git- Insert an environment variable file named
.envin the project root directory. This should be in the following format with the key values filled in:
SECRET_KEY=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
AWS_ACCESS_KEY=
AWS_SECRET_KEY=
AWS_BUCKET=
AWS_REGION=
EMAIL_USER=
EMAIL_PASSWORD=
STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=You can find more detailed documentation on how to populate your .env file here.
- Create your virtual environment (optional but recommended):
python3 -m venv myenv- Activate your virtual environment (optional but recommended):
# For Linux/MacOS
source myenv/bin/activate
# For Windows Command Prompt
myenv\Scripts\activate
# For Windows PowerShell
.\myenv\Scripts\Activate.ps1- Install dependencies:
pip install -r requirements.txt- Run the Flask application in development mode:
flask run --debugBy default, the application will use an existing SQLite database file named database.db in the main directory. If this file is empty or not present, the application will create a new database file populated with dummy data. To run the application with no initial data, use the following command:
# For Linux/MacOS
EMPTY_DB=1 flask run --debug
# For Windows Command Prompt
set EMPTY_DB=1 && flask run --debug
# For Windows PowerShell
$env:EMPTY_DB=1; flask run --debug- Set Up Stripe
To accomodate payments, you will need to install Stripe CLI, instructions can be found here. Once you have set up Stripe CLI and populated the .env file with your Stripe API keys, you will need to run the following command in a separate terminal window to forward Stripe events to your local server:
stripe listen --forward-to http://127.0.0.1:5000/item/stripe-webhook- Access the application:
- Open the browser at: http://localhost:5000
| Feature | Description |
|---|---|
| 🧑💻 Account Creation | Users can create accounts using their email and sign in with Google, allowing them to create and bid on auctions. |
| 📦 Listing Items | Sellers can list items for auction, with durations up to 5 days by default. |
| 💰 Bidding and Payment | Buyers can submit bids for a minimum of 1p above the current bid price. When a buyer wins an auction, they are instructed to complete payment by entering their card details, or choosing a saved card if this has been opted for before. |
| 🔔 Notification System | Notifications are rendered in the browser for significant events such as account creation, winning bids, and payment prompts. Some important notifications are also sent via email to keep users who are not currently browsing the site up to date. |
| 🧑🔬 Experts | "Expert" is a role for users who are able to authenticate items for given categories. These users are not able to bid on items and may only authenticate items they are assigned to. |
| ⏰ Expert Availability | Experts can mark themselves as available/unavailable for work at various dates and times. This prevents an expert from being assigned to authenticate an item when they are not available. |
| 📑 Authentication Requests | Sellers can request their items be authenticated by a designated Expert. This is supplemented by a Seller/Expert messaging system, where the seller can provide more details/photos at the expert's request. When an item is authenticated, the auction for it will feature an authenticated badge for buyer confidence. |
| 👨💼 Managers | "Manager" is a dedicated role for Vintage Vault administrators, giving them access to user roles, platform statistics, and site configuration options. |
| ⚙️ Manager Options | In the management dashboard, a manager can update the roles of users in real time. Managers are also tasked with assigning experts to auctions with pending authentication requests. This can be set manually, or auto-assigned based on a recommendation algorithm which considers the niche of the expert and their availability. |
| 📊 Platform Statistics/Configuration | Managers can view sales information for the platform over a period of up to 6 months. Visible statistics include the number of paid auctions, projected revenue, commission income, and other relevant data to help with the platform's performance monitoring. Additionally, managers may update the platform fee percentages as well as the maximum auction duration possible for future listings. |
-
jQuery - Simplifies event handling, DOM manipulation, and AJAX requests, enabling real-time updates and dynamic interactions on the frontend.
-
Bootstrap - For responsive styling and maintaining accessibility for mobile users.
-
Flask - A lightweight web application framework.
-
SQLAlchemy - An SQL toolkit and ORM for Python.
-
SQLite - A C library that provides a lightweight disk-based database.
-
PostgreSQL - An open-source relational database management system, used with the deployed application.
- pytest - Facilitates writing and running Python tests for the backend.
-
Stripe - For secure handling of payments.
-
Google OAuth - For user authentication during login.
-
Google Mail - For sending notification emails.
-
AWS S3 - For storing auction and authentication images.
- Render - A cloud platform for hosting web applications.
Testing is encouraged for all features as it allows us to maintain the integrity of the site and catch bugs early. After activating your virtual environment, enter the following commands in the root directory to run the project's unit tests:
# Run all tests
pytest
# Run a specific test file
pytest tests/test_feature.pyContributions after the final assessment deadline are welcome! To contribute, follow these steps to ensure your changes can be properly reviewed and integrated.
- Create a Fork
This can be done using the button at the top right of the project homepage. Forking allows you to experiment with the project without affecting the original repository.
- Clone Your Fork
To create a local copy of your fork, use this command:
git clone https://github.com/yourusername/repo-name- Create a Branch
git checkout -b <issueId-issueDescription>- Push Your Changes
This project follows the conventional commit structure, please see the coding style guide in the wiki for more information. Your changes may be rejected if your commit messages don't follow this structure.
# To stage all changes you've made
git add .
# To save changes locally
git commit -m "conventional commit message"
# To upload to the remote repository
git push- Create a Pull Request
The pull request should be linked to an issue where possible using "Closes #". This ensures that when your changes are merged, the PR will automatically close the issue it is linked with. Pull requests should be descriptive, with markdown headings breaking up sections. Images are always welcome, especially for UI changes so we can see a before and after.
- Await Review
Once the designated coordinator has looked over your changes and tested them, they will handle the merging process for you. After this, you have successfully contributed to the project! Thank you! 😃