Serfee is a location-based help request and task marketplace platform built for communities to request and offer assistance with daily tasks. This repository hosts the backend API, developed using Node.js and Express.js, deployed on Google Cloud App Engine, and tightly integrated with Firebase and Google Cloud Platform (GCP) services.
🔗 Live API:
📄 API Docs: Postman Documentation
Serfee empowers users to post tasks (e.g., “buy coffee,” “help with cleaning”) and allows nearby users to respond with service offers. It's designed to support flexible, ad-hoc assistance and encourage micro-entrepreneurship.
This project was built as part of a final-year capstone and reflects real-world architectural decisions including cloud integration, asynchronous file handling, geolocation filtering, and secure authentication.
The Serfee backend offers a rich set of features designed to support a marketplace for local help and services, enabling users to post tasks, offer help, chat, and provide feedback.
- User registration using Firebase Authentication
- Login with email and password
- Access token generation and validation
- Delete account functionality
- Create task requests with optional image upload to Cloud Storage
- Automatically categorize tasks using provided category names
- Retrieve user-specific active, past, and current tasks
- Cancel task functionality
- Update task details by ID
- Task search by keyword
- Fetch nearby tasks based on latitude, longitude, and radius
- Calculate real-world distance using the Haversine formula
- Allow taskers to submit offers for posted tasks
- Task posters can accept or reject offers
- Track current or past offers made by a user
- Complete tasks and update their status
- Cancel offers with automatic status fallback
- Push new chat messages to Firebase Realtime Database
- Retrieve chat history
- Update or delete messages by ID
- Submit feedback after a task is completed
- Calculate and update average ratings in real-time
- Store review history and metadata
- Upload and update user profile pictures
- Update full name, phone number, and email
- Retrieve profile info by Firebase UID
All operation methods require this step.
To run this project, you will need to install the dependencies, create the configuration file called cloud-storage.json & firebase.json and add the following environment variables to your .env file
npm install{
"type": "xxxx",
"project_id": "xxxx",
"private_key_id": "xxxx",
"private_key": "xxxx",
"client_email": "xxxx",
"client_id": "xxxx",
"auth_uri": "xxxx",
"token_uri": "xxxx",
"auth_provider_x509_cert_url": "xxxx",
"client_x509_cert_url": "xxxx",
"universe_domain": "xxxx"
}you need to create cloud-storage.json & firebase.json inside the credentials folder. to get the credentials you need to set up the Firebase and GCP project and create the credentials key.
Create a .env file in the root directory of your project. This file will hold all the environment-specific configurations for the application.
| Name | Variable |
|---|---|
| PORT | PORT |
| MySQL | DB_HOST DB_USERNAME DB_PASSWORD DB_NAME |
| Cloud Storage | CS_PROJECT_ID CS_BUCKET_NAME |
| Firebase | FIREBASE_DB_URL FIREBASE_API_KEY FIREBASE_AUTH_DOMAIN FIREBASE_PROJECT_ID |
You can use the following as a template for your .env file:
PORT=xxxx
# MySQL Database Configuration
DB_HOST=xxxx
DB_USERNAME=xxxx
DB_PASSWORD=xxxx
DB_NAME=xxxx
# Cloud Storage Configuration
CS_PROJECT_ID=xxxx
CS_BUCKET_NAME=xxxx
# Firebase Configuration
FIREBASE_DB_URL=xxxx
FIREBASE_API_KEY=xxxx
FIREBASE_AUTH_DOMAIN=xxxx
FIREBASE_PROJECT_ID=xxxx
Note: Replace the placeholder values (xxxx) with your actual configuration details. Make sure not to commit your .env file to version control to keep your credentials secure.
PORT: Set your server to listening toPORTyou specify in hereDB_HOST: set your Database IP AddressDB_USERNAME: set your database usernameDB_PASSWORD: set your database passwordDB_NAME: set your database nameCS_PROJECT_ID: set your GCP project IDCS_BUCKET_NAME: set your Cloud Storage bucket nameFIREBASE_DB_URL: set your Firebase realtime database URLFIREBASE_API_KEY: set your Firebase API key got in Account Settings in Firebase ConsoleFIREBASE_AUTH_DOMAIN: set your Firebase Auth Domain got in Account Settings in Firebase ConsoleFIREBASE_PROJECT_ID: set your Firebase or GCP Project ID
You can see the example of the .env file in the env.example file included in the root folder of the project.
After you install the dependencies and set the environment variables, you can start the server by running
npm run startThis API endpoint will create a requested task and need authorization before continuing to create a request task.
POST /api/tasks/request| name | Element | Value |
|---|---|---|
| authorization | Headers | Bearer ${token} |
| photo | body | image |
| title | body | text |
| category | body | text |
| Description | body | text |
| lat | body | task_latitude |
| lon | body | task_longitude |
Input example
curl --location 'https://serfee-project.as.r.appspot.com/tasks/request' \
--header 'Authorization: ${token}' \
--form 'photo=@"/D:/1a PRESUNIV/luf.png"' \
--form 'title="buy me"' \
--form 'category="Cleaning"' \
--form 'description="help me buy some cofeee"' \
--form 'lat="-6.216840066573826"' \
--form 'lon="107.1517113558033"'
Output example
{
"message": "Create new task success",
"creator_id": 2,
"data": {
"title": "buy me",
"category": "Cleaning",
"description": "help me buy some cofeee",
"lat": "-6.216840066573826",
"lon": "107.1517113558033"
},
"image_url": "https://storage.googleapis.com/serfee/images/task/1686911412980"
}This API endpoint will need the authorization, latitude and longitude from user location to get all near tasks by user location. radius will filters the tasks in radius km.
GET /api/tasks/response| name | Element | Value |
|---|---|---|
| authorization | Headers | Bearer ${token} |
| lat | body | user_latitude |
| lon | body | user_longitude |
| radius | body | int |
Input example
curl --location --request GET 'http://192.168.1.6:8080/tasks/response' \
--header 'Authorization: ${token}' \
--data '{
"latitude": -6.21684,
"longitude": 107.152,
"radius": 1
}'
Output example
{
"message": "GET all near tasks",
"data": [
{
"request_id": 94,
"user_id": 2,
"title": "buy me",
"category_id": 1,
"description": "help me buy some cofeee",
"price": null,
"location_latitude": -6.2168402671813965,
"location_longitude": 107.1517105102539,
"image_url": "https://storage.googleapis.com/serfee/images/task/1686911412980",
"status": "Active",
"created_at": "2023-06-16T03:30:13.000Z"
}
],
"distance": 32
}the response will give the distance between the tasker and tasks position
This app utilizes CI/CD pipelines using GitHub Actions to automate deployment to App Engine. If you want to deploy this app to App Engine, you just need pushed your changes into branch main in Github Repository. But before doing you need to set the configuration as below.
-
Ensure that your application code is ready for deployment and that you have a working GitHub repository for it.
-
Create a
deploy.yamlfile in the .github/workflows/ directory of your repository. -
The
deploy.yamlfile sets up a deployment workflow triggered by pushes to the main branch. You can modify thedeploy.yamlfile as you needed -
In your GitHub repository, navigate to
Settingsand thenSecrets. Add the required secrets:-
GCLOUD_PROJECT: Your Google Cloud project ID -
APPLICATION_CREDENTIALS: Contents of your Google Cloud service account key JSON file -
ENV_FILE: Contents of your .env file -
CLOUD_STORAGE_CONFIG: Contents related to your Cloud Storage service account key JSON file -
FIREBASE_CONFIG: Contents related to your Firebase service account key JSON file
-
-
Push your code changes to the
mainbranch and it will automate deployment process into App Engine in GCP