🏃‍♂️ RunHub: Race Registration Platform

📖 Project Overview

RunHub is a full-stack, two-sided marketplace that connects Race Organizers with Runners. It provides a seamless platform for event companies to create, manage, and promote races, while allowing runners to discover local events, register, and process entry fee payments securely.

This project was built to demonstrate advanced full-stack capabilities, including:

• Building a stateless, RESTful API using Ruby on Rails 7.
• Implementing custom JWT (JSON Web Token) authentication from scratch.
• Designing a complex relational database schema in PostgreSQL to handle strict user roles.
• Consuming the API with a modern, fast React.js (Vite) frontend.
• Integrating third-party payment processing via Stripe.

---

✨ Features

🏢 For Organizers (Business/Enterprise)

• Dedicated Profiles: Manage enterprise details (Company Name, Website, Description).
• Race Management: Create upcoming races with specific details (Date, Location, Distance, Capacity, Price).
• Participant Tracking: View a dashboard of registered runners for specific events to manage capacity.

👟 For Runners (Individuals)

• Race Discovery: Browse a feed of upcoming races.
• Registration & Checkout: Book a spot in a race and securely pay the entry fee via Stripe.
• Runner Dashboard: Track upcoming and past races in a personalized dashboard.

---

🛠 Tech Stack & Architecture

Frontend (Client)

• Framework: React.js (Bootstrapped with Vite for optimized builds).
• Routing: React Router.
• State Management: (TBD - e.g., Redux or React Context).

Backend (API)

• Framework: Ruby on Rails 7 (API-only mode).
• Authentication: Custom JWT stateless authentication using jwt and bcrypt (No Devise).
• Database: PostgreSQL.
• Payments: Stripe API.

🚀 Local Setup & Installation

(Note: This section will be updated as the frontend is initialized)

Prerequisites

• Ruby 3.x+
• Node.js & npm/yarn
• PostgreSQL
• Redis
• Stripe test credentials

Backend Setup

1. Clone the repository: git clone <your-repo-url>
2. Navigate to the API directory: cd run_hub_api
3. Create local environment variables: cp .env.example .env
4. Install Ruby gems: bundle install
5. Setup the database: rails db:create db:migrate db:seed
6. Start the Rails server: rails s (Runs on http://localhost:3000)

🔐 Production Environment Checklist

Before deploying, configure these environment variables or deployment secrets. Do not commit real values to git.

Required secrets

• RAILS_MASTER_KEY - decrypts Rails credentials.
• JWT_SECRET - signs authentication tokens. Use a long random value and keep it separate from RAILS_MASTER_KEY.
• DATABASE_NAME - production database name.
• DATABASE_HOST - production database host.
• DATABASE_USERNAME - production database user.
• DATABASE_PASSWORD - production database password.
• STRIPE_SECRET_KEY - Stripe server-side API key.
• STRIPE_PUBLISHABLE_KEY - Stripe publishable key returned to clients.
• STRIPE_WEBHOOK_SECRET - Stripe webhook signing secret.

Required production settings

• APP_HOST - canonical app host used for generated URLs.
• ALLOWED_HOSTS - comma-separated host allowlist, usually including APP_HOST.

Optional settings

• DATABASE_PORT - defaults to 5432.
• REDIS_URL - defaults to redis://localhost:6379/0.
• RAILS_LOG_LEVEL - defaults to info.
• STRIPE_API_VERSION - defaults to 2025-02-24.acacia.
• SIDEKIQ_CONCURRENCY, JOB_CONCURRENCY, RAILS_MAX_THREADS, and PORT tune runtime behavior.

---

🗺️ Roadmap & Future Features

• Integrate Stripe Webhooks for asynchronous payment status updates.
• Add an Admin role for platform-wide moderation.
• Implement email notifications for successful race registrations.
• Add filtering and search capabilities for the Runner race feed.