https://forgearena-8c99233e662d.herokuapp.com/

FOR: Gym-goers and fitness enthusiasts struggling with motivation
WHO: Want their progress to feel meaningful, social, and visually rewarding
FORGEARENA is a gamified fitness platform that blends avatar evolution with social competition
THAT allows you to level up your personal avatar (BodyForge) while competing in gym-based challenges, quests, and leaderboards (FitArena)
UNLIKE existing apps that focus on either solo avatar growth or passive global leaderboards
OUR PRODUCT creates immersive, local gym communities. See your avatar evolve as you earn XP, complete quests, and rise on leaderboards among peers

This is a bare-bones prototype demonstrating the core ForgeArena concepts using the FERN stack (Firebase, Express, React, Node.js). The prototype uses mock data to showcase key features with optional Firebase integration for data persistence.

• User Authentication: Email/password signup, login, logout with session persistence
• Profile Management: Unique handles, avatar uploads, profile customization
• Avatar Progression: Watch your avatar level up and gain stats as you log workouts
• Workout Logging: Simple interface to log different exercises and earn XP
• Quest System: Complete fitness challenges to earn rewards and XP
• Raid Boss: Community challenge where users collectively damage a boss
• Leaderboard: See how you rank against other players
• Gamification: XP, levels, stats, and visual progress bars
• Protected Routes: Authentication-based access control

Important Qualities for our software (layered software architecture project): Our software focuses on building a strong fitness community and keeping members engaged through gamification and friendly competition. Users can earn XP by completing daily, weekly, and monthly quests, turning workouts into rewarding challenges. A leaderboard system tracks progress among individual members and gym clubs, encouraging consistent participation and healthy rivalry. All user data, progress, and quest history are securely stored in a database, ensuring that performance is tracked accurately and users can monitor their long-term achievements while staying motivated through community-driven competition.

• Node.js (v14 or higher)
• npm

1. Clone the repository

   git clone <your-repo-url>
   cd forge-arena

2. Install dependencies

   npm run install-deps

3. Run the application

   npm run dev

   This will start:

   • Backend server on http://localhost:5000
   • React frontend on http://localhost:3000

• Run server API tests (Express/Jest):

  npm run test:server

  Windows PowerShell: if execution policy blocks npm, use npm.cmd run test:server.

• Run shared logic tests (Jest):

  npm run test:shared

• Run client tests (Create React App):

  npm run test:client

• Run all tests:

  npm test

ForgeArena uses Winston for comprehensive logging with Sumo Logic for real-time log monitoring:

• 5 Log Levels: error, warn, info, http, debug
• 35+ Log Statements across all granularities
• Real-Time Monitoring: Logs stream to Sumo Logic in production
• CI Logging: Debug level for test diagnostics (not sent to Sumo Logic)

Setup Guide: See LOGGING_MONITORING_SETUP.md for complete documentation
Quick Setup: See SUMO_LOGIC_QUICK_SETUP.md for 5-minute setup

• This repo includes a Jenkinsfile that:
  • Installs dependencies at the root, client, and server
  • Runs shared tests with Jest and client tests via CRA
  • Archives coverage if available
• After creating a Jenkins pipeline for this repo named ForgeArena, update the badge URL above to your Jenkins domain if needed.

Heroku Deployment (Current)

The app is configured for deployment on Heroku with automated CD via GitHub Actions.

Automated Deployment (Recommended):

• Every push to main branch automatically deploys to Heroku
• Tests run first - deployment only happens if tests pass
• Setup guide: See GITHUB_ACTIONS_HEROKU_SETUP.md

Manual Deployment:

heroku create your-app-name
heroku config:set NODE_ENV=production
git push heroku main
heroku open

Deployment Guides:

• GitHub Actions Setup: GITHUB_ACTIONS_HEROKU_SETUP.md (automated CD)
• Quick Start: HEROKU_QUICK_START.md (5-step manual deployment)
• Full Guide: HEROKU_DEPLOYMENT_GUIDE.md (comprehensive instructions)

Previous Deployment (Vercel)

• The app was previously configured for Vercel deployment
• Vercel configuration files remain in the repo for backwards compatibility
• See DEPLOYMENT_SETUP.md for Vercel-specific instructions

1. Start the backend server

   cd server
   npm install
   npm run dev

2. In a new terminal, start the frontend

   cd client
   npm install
   npm start

For persistent data storage, you can set up Firebase:

1. Create a Firebase project at Firebase Console

2. Enable Firestore Database in your Firebase project

3. Set up environment variables

   cp firebase.env.example client/.env

   Fill in your Firebase configuration values in client/.env

4. Apply Firestore security rules

   • Copy the rules from firestore.rules
   • Paste them in Firebase Console → Firestore Database → Rules

5. Initialize your database

   • See FIRESTORE_SETUP.md for detailed database structure
   • The app will automatically fall back to mock data if Firebase is not configured

6. Set up Authentication (Recommended)

   • Follow the guide in AUTHENTICATION_SETUP.md
   • Enable Email/Password authentication in Firebase Console
   • Users can now create accounts and have persistent data

7. Set up Profile Management (Optional)

   • Follow the guide in PROFILE_SETUP.md
   • Enable Firebase Storage for avatar uploads
   • Users can customize profiles with unique handles and avatars

1. Create Your Account: Sign up with email and password to get started

2. Customize Your Profile: Go to the Profile tab to upload an avatar and set a unique handle

3. View Your Avatar: See your current level, XP, and stats (Strength, Endurance, Agility)

4. Log Workouts:

   • Select an exercise type (Squats, Push-ups, Pull-ups, Running)
   • Enter the number of reps
   • Click "Log Workout" to earn XP and potentially level up

5. Complete Quests: Click "Complete Quest" on any active quest to earn bonus XP

6. Attack Raid Boss: Log squat exercises to damage the community raid boss "The Titan Squat"

7. Check Leaderboard: See how your level and XP compare to other players

Backend (Express + Node.js)

• Simple REST API with mock data fallback
• Optional Firebase Firestore integration for data persistence
• Endpoints for user data, workouts, quests, raids, and leaderboards

Frontend (React + TypeScript)

• Modern, responsive UI with gamified styling
• Real-time updates when logging workouts or completing quests
• Visual progress bars and level-up animations

Database (Firebase Firestore)

• NoSQL document database for flexible data storage
• Real-time synchronization capabilities
• Scalable cloud infrastructure
• User profiles with avatar storage

Storage (Firebase Storage)

• Secure file uploads for user avatars
• Automatic image compression and optimization
• CDN-backed delivery for fast loading

• Advanced avatar customization and equipment system
• Full Firebase Firestore integration for all game data
• Real-time multiplayer raid mechanics
• Gym-specific leaderboards and communities
• Push notifications for quest reminders (Firebase Cloud Messaging)
• Social features (friend system, sharing achievements)
• Mobile app version
• Party system with team challenges

• This is a proof of concept - some data may reset when the server restarts
• User accounts and profiles persist across sessions with Firebase
• Avatar uploads and handles are stored permanently
• Raid boss HP decreases only with squat exercises
• Quest completion is simulated (just click the button)
• Designed to demonstrate core gamification concepts and modern web app features

FOR: Gym-goers and fitness enthusiasts struggling with motivation
WHO: Want their progress to feel meaningful, social, and visually rewarding

FORGEARENA is a gamified fitness platform that blends avatar evolution with social competition — allowing you to level up your personal avatar (BodyForge) while competing in gym-based challenges, quests, and leaderboards (FitArena).

Unlike existing apps that focus on either solo avatar growth or passive global leaderboards, our product creates immersive, local gym communities. See your avatar evolve as you earn XP, complete quests, and rise on leaderboards among peers.

• Avatar-Based Progression: Your avatar grows, levels up, and earns gear.
• Avatar Customization: Earn cosmetic gear or upgrades (armor, badges, etc.) that reflect real-world milestones.
• Duel Mode: Friendly competitions to see who logs more reps, steps, or streaks in a set time.
• Gym Quests: “Attend 3 group classes this week” or “Beat your leg press record.”
• Local Social Competition: Weekly gym quests, buddy duels, and club leaderboards (with custom clubs per gym).
• Social & Personal Incentives: Visual rewards and recognition amplify motivation.
• Social Feed & Support: Share avatar changes, celebrate PRs, and cheer peers in-app.
• Seasonal Boss Challenges: Conquer a “Giant Squat” boss by cumulative gym visits or lifting achievements.
• RPG Elements + Real Results: Storytelling meets tangible fitness metrics for emotional engagement.

Core Idea:
Each raid boss represents a massive community fitness goal.

ForgeArena focuses on building a strong fitness community through gamification and friendly competition.
Users can earn XP by completing quests, tracked securely in a database with leaderboards and detailed user stats.

1. Presentation Layer (UI)
   • React web client with interactive dashboards, leaderboards, and quest tracking
2. Application Layer (API & Request Handling)
   • RESTful Express.js endpoints for workouts, quests, raids, and leaderboards
3. Business Logic Layer
   • Gamification engine: XP, quests, avatar progression, and raid mechanics
4. Data Access Layer
   • Repository pattern managing Firestore collections for users, quests, raids, and gyms
5. Infrastructure Layer
   • Firebase authentication, storage, caching, and monitoring

• Authentication – Login, registration, password recovery
• Dashboard – Avatar display, progress, quick stats
• Workout Arena – Log workouts, view history
• Quest Chamber – View and complete quests
• Raid Portal – Participate in community boss events
• Social Hub – Leaderboards and activity feeds
• Profile Forge – Avatar customization and achievements

• Controllers:
  /api/auth, /api/users, /api/workouts, /api/quests, /api/raid, /api/leaderboard
• Middleware: Authentication, rate limiting, session management

• User Service – Profile & avatar management
• Gamification Engine – XP, level progression, stat mechanics
• Quest Service – Quest validation, rewards, and cycling
• Raid Service – Boss health, damage, and event scheduling
• Leaderboard Service – Ranking logic & caching

1. Architecture Type: Modular Monolith
   • Simpler for current scale; can evolve to microservices later.
2. Real-time Updates: Polling first → WebSockets later
   • Easier MVP rollout; scalable for live raid events.
3. Data Consistency: Eventual Consistency
   • Minor leaderboard delays tolerated for better performance.

• Database sharding (user-based)
• Split microservices: Gamification / Social / Analytics
• CDN expansion for global delivery

1. Responsive web app (current)
2. React Native app (shared logic)
3. Native features: push notifications, HealthKit/Google Fit integration

Phase 1: Core Architecture (Current)

• Layered backend, gamification engine, Firebase integration, React client

Phase 2: Scaling Preparation

• Add caching, rate limiting, and monitoring

Phase 3: Advanced Features

• Real-time events, mobile app, gym management tools

ForgeArena transforms workouts into quests, progress into XP, and gym communities into adventure parties.
It’s fitness reimagined as an RPG with real-world rewards — one rep, one quest, one victory at a time.

Built for CS 40500 - Software Engineering