HERO2 Startup App Feature Development
Budget: $750 – $1,500 USD
A. About HERO2 & This Project
HERO2 is an award-winning startup from a UC Berkeley competition, dedicated to making sustainable transportation rewarding. We are now entering our first pilot phase and are looking for a talented developer to build the core features that will bring our vision to life.
This document outlines the requirements for implementing three key features: Profile & Onboarding, the Rewards Marketplace, and the main Dashboard.
--------------------------------------
B. Project Context & Philosophy
What Exists:The project foundation is already in place. This includes a working authentication system (signup, login, session management), a basic app skeleton with navigation (`NavBar`), a theming system, and a robust architecture on both frontend and backend. Look at the screenshots to get a first impression.
Our Goal: We are looking for a developer to build upon this foundation. The priority is creating features that are maintainable, scalable, and provide an excellent user experience. The level of quality should be higher than the provided debug screen and rather similar to the signup and logins screen. As this debug screen is only for our internal development (in the end app not visible to the user) of other parts of the app that are not part of this project, this should not represent an orientation for the UI quality.
Your Freedom & Creativity: We trust your expertise. While this brief defines the what (the required functionality), the how is open to your professional judgment. You are encouraged to improve upon the existing codebase and propose elegant UI/UX solutions that align with our "clean-tech" aesthetic. Adherence to the core architecture is key to ensuring long-term maintainability. We are technical people. Thus, please expect that we will look into your code and also expect good code quality. On the other hand, this means that we will always be ready to discuss any bad architectural/code decisions that were made on our side too and value your technical feedback as well.
--------------------------------------
C. Core Technology Stack
* Frontend: Flutter, Riverpod, Dio. The architecture that we use is portrayed in one of the images attached. If you google "Flutter App Architecture with Riverpod: An Introduction" you will find a blog by Andrea Bizzotto explaining the whole architecture.
* Backend: Node.js, Express, TypeScript, Prisma. The architecture is also attached as one of the images and should look familiar to you.
* Database: PostgreSQL
* API: RESTful
--------------------------------------
Feature 1: User Profile & Onboarding
Use Case: To establish a user's identity within the app, allow them to create a unique presence with a username and profile picture, and provide a hub to view their personal statistics.
Frontend Specification
1. Initial Profile Setup Screen (Onboarding):
* Trigger: Appears once, immediately after a new user signs up.
* Functionality:
* An input field for a `username`.
* Live validation queries the backend as the user types. If the username is taken, the UI must display alternative, available username suggestions.
* An optional "Upload Profile Picture" area.
* A "Complete Profile" button, enabled only after a valid, available username is entered. A profile picture is not required to proceed.
2. Profile Screen:
* Functionality:
* Display the user's profile picture (or a default placeholder). Tapping it allows uploading/changing the picture.
* Display the user's `username` and an "Edit Profile" button.
* A "Logout" button with a confirmation dialog.
* Statistics Section: Display key user metrics with UI toggles to switch the view between "This Week" (default), "Monthly", and "All Time".
Backend Specification
1. Image Storage (Self-Hosted):
* Requirement: The image storage solution must support local testing and be self-hostable. We suggest MinIO as it is a high-performance, S3-compatible object storage server that can be run easily via Docker. However, you are free to propose an alternative solution if it meets these core requirements.
* Implementation: The image upload flow must use pre-signed URLs. The backend will generate a secure, temporary upload URL, the client will upload the file directly to the storage service, and the backend will then save the final object key.
2. API Endpoints (`/api/profile`):
* `POST /`: Creates a user's profile.
* `GET /me?period=weekly|monthly|all-time`: Fetches the profile and stats for the authenticated user.
* `PUT /me`: Updates profile details.
* `GET /username-check?username=:username`: Checks availability and returns suggestions.
* `GET /generate-upload-url?fileName=...`: Generates a pre-signed URL for image upload.
--------------------------------------
Feature 2: Rewards Marketplace
Use Case: To provide a tangible incentive for sustainable travel by allowing users to redeem earned `Power` and `Superpower` tokens for real-world rewards.
* Important Scope Note: You are responsible for the systems that spend and display tokens. The logic for how users earn tokens is out of scope for this project.
Frontend Specification
1. Rewards Screen:
* Display `Power` and `Superpower` balances.
* A scrollable grid/list of reward cards, filterable by "All" and "Near Me".
* When filtered by "Near Me," rewards must be **sorted by the estimated walking distance**, and each card must display this estimate.
2. Reward Details & Redemption:
* Each reward card should display the logo of the merchant as well as the type of reward (either $ or % discount on a specific product of the merchant).
* The detail screen must show the merchant's location on a map. Tapping the map/address must open the user's native mapping app (Google/Apple Maps) to navigate to the destination.
* A "Lock-In Reward" button with a confirmation dialog. This feature is required to allow users to reserve limited-availability rewards.
* A "My Locked-In Rewards" section lists reserved rewards. Tapping a reward opens the Redemption Screen.
* Redemption Screen: Displays the reward details and a "Slide to Confirm Redemption" control. Activating it will call the backend and, upon success, update the UI to a final "Redeemed Successfully" state for visual confirmation by the merchant.
#### Backend Specification
1. Merchant & Reward Management: You will build a full set of secured, admin-only CRUD endpoints for managing merchants and their rewards.
2. Prisma Schema: The `Merchant` model should include `latitude` and `longitude` fields to support the "Near Me" feature. Otherwise you are free to add any other attributes that you would consider useful respectively required for the implementation.
3. API Endpoints:
* Merchants (`/api/admin/merchants`):** Full CRUD endpoints (`POST`, `GET /`, `GET /:id`, `PUT /:id`, `DELETE /:id`).
* Rewards: Endpoints for admins to manage rewards and for users to fetch available rewards. The public-facing `GET /api/rewards` endpoint must support filtering and sorting by geographic proximity when a user's location is provided. Acquiring the user location should be easily possible in the existing codebase as the users location is fetched as part of the trip_tracking feature within the frontend.
* User Interaction (`/api/user/rewards`):
* `POST /:rewardId/lock-in`: Lock in a reward.
* `GET /`: Fetch the user's rewards.
* `POST /:userRewardId/redeem`: Marks a reward as redeemed.
--------------------------------------
Feature 3: Unified Dashboard & Daily Streaks
Use Case: To provide an at-a-glance, motivating summary of a user's progress and quick access to key app functions, serving as the main landing screen.
Frontend Specification
1. Dashboard Screen (Main App Screen):
* Top of Screen: Display the user's `Power` and `Superpower` token balances.
* Primary Stat: A large, visual display of "Total COâ‚‚ Emissions Saved".
* Daily Streak Visual: Display a representation for the 7 days of the current week. Days where the goal was met should be visually distinct. A text element must state the current streak count.
* Locked-In Rewards Quick Access: If the user has locked-in rewards, display a horizontally scrollable list of small cards. Tapping a card must navigate directly to the Redemption Screen for that reward.
Backend Specification
1. Daily Goal & Streak Logic:
* Definition: A daily goal is "met" if the database contains at least one `Trip` record for the user that `startedAt` on that calendar day.
* Implementation: You will implement the backend logic to calculate a user's current streak based on this definition.
2. Aggregator API Endpoint:
* `GET /api/dashboard/summary`: This single endpoint must efficiently gather and return all data for the dashboard screen, including token balances, core stats, streak data (an array of booleans for the week and the current streak count), and a list of the user's active locked-in rewards.
HERO2 is an award-winning startup from a UC Berkeley competition, dedicated to making sustainable transportation rewarding. We are now entering our first pilot phase and are looking for a talented developer to build the core features that will bring our vision to life.
This document outlines the requirements for implementing three key features: Profile & Onboarding, the Rewards Marketplace, and the main Dashboard.
--------------------------------------
B. Project Context & Philosophy
What Exists:The project foundation is already in place. This includes a working authentication system (signup, login, session management), a basic app skeleton with navigation (`NavBar`), a theming system, and a robust architecture on both frontend and backend. Look at the screenshots to get a first impression.
Our Goal: We are looking for a developer to build upon this foundation. The priority is creating features that are maintainable, scalable, and provide an excellent user experience. The level of quality should be higher than the provided debug screen and rather similar to the signup and logins screen. As this debug screen is only for our internal development (in the end app not visible to the user) of other parts of the app that are not part of this project, this should not represent an orientation for the UI quality.
Your Freedom & Creativity: We trust your expertise. While this brief defines the what (the required functionality), the how is open to your professional judgment. You are encouraged to improve upon the existing codebase and propose elegant UI/UX solutions that align with our "clean-tech" aesthetic. Adherence to the core architecture is key to ensuring long-term maintainability. We are technical people. Thus, please expect that we will look into your code and also expect good code quality. On the other hand, this means that we will always be ready to discuss any bad architectural/code decisions that were made on our side too and value your technical feedback as well.
--------------------------------------
C. Core Technology Stack
* Frontend: Flutter, Riverpod, Dio. The architecture that we use is portrayed in one of the images attached. If you google "Flutter App Architecture with Riverpod: An Introduction" you will find a blog by Andrea Bizzotto explaining the whole architecture.
* Backend: Node.js, Express, TypeScript, Prisma. The architecture is also attached as one of the images and should look familiar to you.
* Database: PostgreSQL
* API: RESTful
--------------------------------------
Feature 1: User Profile & Onboarding
Use Case: To establish a user's identity within the app, allow them to create a unique presence with a username and profile picture, and provide a hub to view their personal statistics.
Frontend Specification
1. Initial Profile Setup Screen (Onboarding):
* Trigger: Appears once, immediately after a new user signs up.
* Functionality:
* An input field for a `username`.
* Live validation queries the backend as the user types. If the username is taken, the UI must display alternative, available username suggestions.
* An optional "Upload Profile Picture" area.
* A "Complete Profile" button, enabled only after a valid, available username is entered. A profile picture is not required to proceed.
2. Profile Screen:
* Functionality:
* Display the user's profile picture (or a default placeholder). Tapping it allows uploading/changing the picture.
* Display the user's `username` and an "Edit Profile" button.
* A "Logout" button with a confirmation dialog.
* Statistics Section: Display key user metrics with UI toggles to switch the view between "This Week" (default), "Monthly", and "All Time".
Backend Specification
1. Image Storage (Self-Hosted):
* Requirement: The image storage solution must support local testing and be self-hostable. We suggest MinIO as it is a high-performance, S3-compatible object storage server that can be run easily via Docker. However, you are free to propose an alternative solution if it meets these core requirements.
* Implementation: The image upload flow must use pre-signed URLs. The backend will generate a secure, temporary upload URL, the client will upload the file directly to the storage service, and the backend will then save the final object key.
2. API Endpoints (`/api/profile`):
* `POST /`: Creates a user's profile.
* `GET /me?period=weekly|monthly|all-time`: Fetches the profile and stats for the authenticated user.
* `PUT /me`: Updates profile details.
* `GET /username-check?username=:username`: Checks availability and returns suggestions.
* `GET /generate-upload-url?fileName=...`: Generates a pre-signed URL for image upload.
--------------------------------------
Feature 2: Rewards Marketplace
Use Case: To provide a tangible incentive for sustainable travel by allowing users to redeem earned `Power` and `Superpower` tokens for real-world rewards.
* Important Scope Note: You are responsible for the systems that spend and display tokens. The logic for how users earn tokens is out of scope for this project.
Frontend Specification
1. Rewards Screen:
* Display `Power` and `Superpower` balances.
* A scrollable grid/list of reward cards, filterable by "All" and "Near Me".
* When filtered by "Near Me," rewards must be **sorted by the estimated walking distance**, and each card must display this estimate.
2. Reward Details & Redemption:
* Each reward card should display the logo of the merchant as well as the type of reward (either $ or % discount on a specific product of the merchant).
* The detail screen must show the merchant's location on a map. Tapping the map/address must open the user's native mapping app (Google/Apple Maps) to navigate to the destination.
* A "Lock-In Reward" button with a confirmation dialog. This feature is required to allow users to reserve limited-availability rewards.
* A "My Locked-In Rewards" section lists reserved rewards. Tapping a reward opens the Redemption Screen.
* Redemption Screen: Displays the reward details and a "Slide to Confirm Redemption" control. Activating it will call the backend and, upon success, update the UI to a final "Redeemed Successfully" state for visual confirmation by the merchant.
#### Backend Specification
1. Merchant & Reward Management: You will build a full set of secured, admin-only CRUD endpoints for managing merchants and their rewards.
2. Prisma Schema: The `Merchant` model should include `latitude` and `longitude` fields to support the "Near Me" feature. Otherwise you are free to add any other attributes that you would consider useful respectively required for the implementation.
3. API Endpoints:
* Merchants (`/api/admin/merchants`):** Full CRUD endpoints (`POST`, `GET /`, `GET /:id`, `PUT /:id`, `DELETE /:id`).
* Rewards: Endpoints for admins to manage rewards and for users to fetch available rewards. The public-facing `GET /api/rewards` endpoint must support filtering and sorting by geographic proximity when a user's location is provided. Acquiring the user location should be easily possible in the existing codebase as the users location is fetched as part of the trip_tracking feature within the frontend.
* User Interaction (`/api/user/rewards`):
* `POST /:rewardId/lock-in`: Lock in a reward.
* `GET /`: Fetch the user's rewards.
* `POST /:userRewardId/redeem`: Marks a reward as redeemed.
--------------------------------------
Feature 3: Unified Dashboard & Daily Streaks
Use Case: To provide an at-a-glance, motivating summary of a user's progress and quick access to key app functions, serving as the main landing screen.
Frontend Specification
1. Dashboard Screen (Main App Screen):
* Top of Screen: Display the user's `Power` and `Superpower` token balances.
* Primary Stat: A large, visual display of "Total COâ‚‚ Emissions Saved".
* Daily Streak Visual: Display a representation for the 7 days of the current week. Days where the goal was met should be visually distinct. A text element must state the current streak count.
* Locked-In Rewards Quick Access: If the user has locked-in rewards, display a horizontally scrollable list of small cards. Tapping a card must navigate directly to the Redemption Screen for that reward.
Backend Specification
1. Daily Goal & Streak Logic:
* Definition: A daily goal is "met" if the database contains at least one `Trip` record for the user that `startedAt` on that calendar day.
* Implementation: You will implement the backend logic to calculate a user's current streak based on this definition.
2. Aggregator API Endpoint:
* `GET /api/dashboard/summary`: This single endpoint must efficiently gather and return all data for the dashboard screen, including token balances, core stats, streak data (an array of booleans for the week and the current streak count), and a list of the user's active locked-in rewards.
Related categories:
Mobile App Development
UI / User Interface
Typescript
Flutter
Relational Databases