Outside Quest: Level Up in Real Life

🚀 Live Demo: https://outside-quest.vercel.app/

Project Description

Outside Quest is a gamified wellness application designed to help gamers and students combat screen fatigue. By integrating real-time weather data and motivational quotes, the app generates daily "real-world quests" that encourage users to step away from their screens and earn XP for physical activity and mindfulness.

Target Browsers

• Chrome (Desktop/Mobile)
• Firefox
• Safari (iOS/MacOS)

Link to Developer Manual

Jump to Developer Manual

---

Developer Manual

1. Installation

1. Clone the repository to your local machine.
2. Run npm install in the terminal to install all dependencies (Next.js, Axios, Chart.js, Supabase, Framer Motion).
3. Create a .env.local file in the root directory.
4. Add your API keys to the .env.local file (see the Configuration section below).

2. Configuration & Database Setup

Environment Variables

Your .env.local file should look like this (referencing the keys used in your API testing):

NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key
OPENWEATHER_API_KEY=your_openweather_key

Database Schema (Supabase)

If setting up a fresh database, run this SQL query in the Supabase SQL Editor to create the required table matching our data structure:

create table quests (
  id bigint generated by default as identity primary key,
  user_id text not null, -- Stores the hardcoded ID used in testing
  quest text not null,
  xp_earned int not null,
  created_at timestamp with time zone default timezone('utc'::text, now()) not null
);

3. Running the Application

Run npm run dev to start the local development server.

Open http://localhost:3000 in your browser to view the application.

4. Testing

• Manual Testing: We use standard console.log debugging and manual API testing via the browser network tab.
• API Verification: To test the API routes individually, navigate to http://localhost:3000/api/daily-quest in your browser to see the raw JSON output.

5. API Endpoints

GET /api/daily-quest

Purpose: Fetches local weather from OpenWeatherMap and a random quote from ZenQuotes. It processes this data to generate a specific "quest".

Inputs: None (uses server-side environment variables and hardcoded location).

Outputs: JSON object: { weather, temp, quote, quest, xp }.

GET /api/user-quests

Purpose: Retrieves the history of completed quests from the Supabase database for the profile visualization.

Outputs: JSON array of quest objects: [{ id, quest, xp_earned, ... }].

POST /api/complete-quest

Purpose: Writes a new completed quest to the Supabase database.

Inputs: JSON body: { quest: string, xp_earned: number }.

Outputs: Success message and the inserted data row.

6. Known Bugs & Future Roadmap

Known Bugs

• Location Hardcoding: The weather API is currently hardcoded to coordinates 39.2904, -76.6122 (Baltimore, MD) for demonstration purposes.
• API Rate Limits: Rapidly refreshing the page may cause the OpenWeatherMap or ZenQuotes API to return errors due to free tier rate limiting.

Known Limitations

• Shared User Profile: The application currently uses a hardcoded "Demo User ID" (11dcc0eb...) for all database entries. This means all visitors share the same XP history and profile graph.

Roadmap

• Geolocation: Implement the browser Geolocation API to auto-detect user position for accurate weather data.
• User Authentication: Implement Supabase Auth to allow unique user accounts and private history.