OpenPath - Community-Driven Roadmap Tool

A web-based platform where users can collaboratively create, share, and review learning paths for various roles and experiences.

✨ Features

Core Functionality

• 🗺️ Create & Share Roadmaps: Build structured learning paths with steps and resources
• 🏷️ Community Tags: Tag roadmaps with custom tags (roles, skills, experience levels)
• 📚 Browse Roadmaps: Explore community-created learning paths
• ✏️ Edit Roadmaps: Creators can update their roadmaps anytime
• 🔍 Advanced Filtering: Filter by resource type (Free/Paid), tags, and sort by trending or newest
• 👍 Community Voting: Upvote/downvote roadmaps with spam protection
• 💬 Comments & Feedback: Engage with creators and learners through comments
• 👤 Creator Profiles: View creator information with avatars on roadmaps

Progress Tracking

• ✅ Mark Steps Complete: Track your progress through each roadmap
• 📊 Visual Progress Bars: See completion percentage at a glance
• 🎯 Completion Badge: Get congratulated when you finish a roadmap
• 💾 Persistent Tracking: Your progress is saved and syncs across devices

User Experience

• 🔐 Google Sign-In: Quick and secure authentication via Google OAuth
• 🌓 Dark Mode: Beautiful dark theme by default with automatic system detection
• 📱 Mobile Responsive: Fully optimized mobile and desktop experience
• 🎨 Modern UI: Eye-pleasing minimal design with Tailwind CSS v4
• 🔽 Collapsible Cards: Clean card-based interface with expandable resource sections
• ✨ Smooth Animations: Gradient backgrounds, micro-interactions, and smooth transitions
• 🎯 Clean Learning Path: Card-based step layout optimized for all screen sizes

Tech Stack

Frontend

• React - UI framework
• Tailwind CSS - Utility-first styling
• React Router - Client-side routing
• Vite - Build tool and dev server
• Supabase JS Client - Authentication and database client

Backend

• Node.js - Runtime environment
• Express - Web framework
• Supabase - PostgreSQL database & authentication
• CORS - Cross-origin resource sharing

Project Structure

open-path/
├── frontend/               # React frontend application
│   ├── src/
│   │   ├── components/    # Reusable UI components
│   │   ├── pages/         # Page components
│   │   ├── context/       # React context (Auth)
│   │   ├── services/      # API service layer
│   │   └── utils/         # Utility functions
│   └── package.json
├── backend/               # Express backend API
│   ├── routes/           # API route handlers
│   │   ├── roadmaps.js   # Roadmap CRUD operations
│   │   ├── votes.js      # Voting system
│   │   ├── comments.js   # Comments system
│   │   ├── tags.js       # Tags system
│   │   └── progress.js   # Progress tracking
│   ├── middleware/       # Auth middleware
│   ├── utils/            # Supabase client
│   └── package.json
└── docs/                 # Documentation
    ├── database-schema.md       # Complete database schema
    ├── API_DOCUMENTATION.md     # All API endpoints
    └── UI_UX_REVAMP_v1.1.md    # Design system & UI guidelines

Prerequisites

• Node.js (v20.18.1 or higher)
• npm (v11.5.2 or higher)
• Supabase account (free tier works)
• Google Cloud Console project (for OAuth)

Setup Instructions

1. Supabase Setup

1. Create a new project at supabase.com

2. Go to SQL Editor and run the setup scripts:

   • First: docs/supabase-setup.sql (main database schema)
   • Then: docs/progress-tracking-schema.sql (progress tracking feature)

3. Enable Google OAuth Provider:

   • Go to Authentication > Providers
   • Enable Google provider
   • Add your Google OAuth credentials (Client ID & Secret)
   • Set redirect URL: http://localhost:5173 (for development)

4. Get your Supabase credentials:

   • Go to Settings > API
   • Copy your Project URL and anon/public key

2. Install All Dependencies

# Install all dependencies (root, backend, and frontend) with one command
npm run install:all

3. Configure Environment Variables

Quick Setup (One Command!):

# Copy environment templates for both backend and frontend
npm run setup:env

This will create:

• backend/.env.development
• frontend/.env.development

Then edit both files with your Supabase credentials:

Required values:

• SUPABASE_URL - Your Supabase project URL
• SUPABASE_ANON_KEY - Your Supabase anon/public key
• Frontend variables must be prefixed with VITE_

4. Google OAuth Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Go to Credentials > Create Credentials > OAuth 2.0 Client ID
5. Add authorized redirect URIs:
   • http://localhost:5173 (development)
   • Your Supabase project's auth callback URL (from Supabase dashboard)
6. Copy Client ID and Secret to Supabase Google provider settings

Running the Application

Development Mode (Single Command!)

From the root directory, run both frontend and backend with one command:

npm run dev

This will start:

• Backend API on http://localhost:5000
• Frontend app on http://localhost:5173

Both will run concurrently in the same terminal with colored output.

Alternative: Run Separately

If you prefer to run them in separate terminals:

Terminal 1 - Backend:

npm run dev:backend
# or: cd backend && npm run dev

Terminal 2 - Frontend:

npm run dev:frontend
# or: cd frontend && npm run dev

Deployment

Deploying to Vercel (Recommended)

Deploy both frontend and backend to Vercel with serverless functions:

Quick Deploy:

1. Push your code to GitHub/GitLab/Bitbucket
2. Import project to Vercel
3. Set environment variables in Vercel dashboard (see VERCEL_DEPLOYMENT.md)
4. Update Google OAuth and Supabase redirect URLs
5. Deploy! ✨

📚 Complete Guide: See VERCEL_DEPLOYMENT.md

Why Vercel:

• ✅ Single deployment for frontend + backend
• ✅ 100K serverless invocations/day (vs Netlify's 125K/month)
• ✅ Global edge network with low latency
• ✅ Automatic HTTPS and Git integration
• ✅ Free tier perfect for this app
• ✅ Auto-configured via vercel.json

Other Deployment Options

Frontend:

• Vercel, Cloudflare Pages, GitHub Pages
• Any static hosting service

Backend:

• Railway, Render, Heroku
• Any Node.js hosting service

Production Build (Local Testing)

Frontend:

cd frontend
npm run build
npm run preview

Backend:

cd backend
npm start

API Endpoints

Roadmaps

• GET /api/roadmaps - Get all roadmaps (with filters)
• GET /api/roadmaps/:id - Get roadmap by ID
• POST /api/roadmaps - Create roadmap (auth required)
• PUT /api/roadmaps/:id - Update roadmap (creator only)
• DELETE /api/roadmaps/:id - Delete roadmap (creator only)

Votes

• GET /api/votes/roadmap/:roadmapId - Get user's vote (auth required)
• POST /api/votes - Cast/update vote (auth required)
• DELETE /api/votes/:roadmapId - Remove vote (auth required)

Comments

• GET /api/comments/roadmap/:roadmapId - Get all comments for roadmap
• POST /api/comments - Create comment (auth required)
• PUT /api/comments/:id - Update comment (author only)
• DELETE /api/comments/:id - Delete comment (author only)

Progress

• GET /api/progress/roadmap/:roadmapId - Get user's progress (auth required)
• GET /api/progress/summary/:roadmapId - Get progress summary (auth required)
• POST /api/progress/toggle - Toggle step completion (auth required)

Documentation

📚 Available Documentation

• API Documentation - Complete API reference with all endpoints
• Database Schema - Database structure and relationships
• UI/UX Design System - Design principles and component guide
• Deployment Guide - Deploy to Vercel (recommended)

Database Tables

• roadmaps - Main roadmap data with voting
• learning_steps - Ordered steps within roadmaps
• resources - Learning resources (Free/Paid, Video/Article/etc)
• tags - Custom tags for categorization
• votes - User votes on roadmaps (spam-protected)
• comments - User comments with moderation
• user_progress - Track completion of steps

Features & Permissions

Public Users (Not Logged In)

• ✅ Browse all roadmaps
• ✅ View roadmap details
• ✅ Apply filters and sorting
• ✅ Read comments
• ❌ Cannot create roadmaps
• ❌ Cannot vote
• ❌ Cannot comment

Authenticated Users (Logged In)

• ✅ All public user features
• ✅ Create new roadmaps
• ✅ Edit/delete own roadmaps
• ✅ Upvote/downvote roadmaps (with spam protection)
• ✅ Post comments
• ✅ Edit/delete own comments
• ✅ Track progress on roadmaps
• ✅ View personal progress statistics

Environment Variables

Backend (.env)

SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
PORT=5000
NODE_ENV=development
FRONTEND_URL=http://localhost:5173

Frontend (.env)

VITE_SUPABASE_URL=your_supabase_project_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_API_URL=http://localhost:5000

Troubleshooting

Common Issues

1. CORS errors: Make sure FRONTEND_URL in backend .env matches your frontend URL

2. Authentication not working:

   • Verify Google OAuth credentials in Supabase
   • Check redirect URLs are correctly configured
   • Clear browser cache and cookies

3. Database errors:

   • Ensure all SQL scripts from docs/supabase-setup.sql were executed
   • Check RLS policies are enabled

4. Cannot create roadmap:

   • Make sure you're signed in
   • Check browser console for errors
   • Verify backend server is running

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

ISC

Support

For issues and questions, please open an issue on the GitHub repository.