GDTracker is a web application designed to help osu! mappers organize, track, and showcase their guest difficulties using live data from the official osu! API.
For beatmap creators and guest difficulty mappers across the osu! ecosystem, keeping track of spread contributions across multiple hosts, beatmapsets, and ranking statuses can become challenging over time. GDTracker streamlines this process by linking local and cloud-saved beatmap references with real-time metadata from osu! API v2. It provides creators with a centralized dashboard to monitor map statuses, analyze personal mapping statistics, and curate an organized portfolio.
- osu! OAuth2 Authentication: Secure login flow using official osu! account credentials without exposing sensitive tokens to the browser.
- Guest Difficulty Management: Organize and track personal guest difficulties across active, qualified, loved, and ranked beatmapsets.
- Live Beatmap Metadata: Real-time hydration of beatmap titles, artists, star ratings, tempo, length, and mapping host details directly from osu! API v2.
- Real-Time Analytics: Interactive charts and data visualizations detailing star rating distributions, beatmap lengths, host collaborations, and historical timeline trends.
- Cloud Synchronization: Persistent, cross-device portfolio storage backed by Supabase with automatic local storage fallback.
- Responsive Dashboard: Fluid layouts crafted for desktops, tablets, and mobile devices with fast tab transitions and clean visual indicators.
- Portfolio Showcase: Dedicated views to display completed and ongoing mapping contributions clearly and professionally.
- Search and Filtering: Instant filtering by mapping host, status, difficulty level, and keywords.
- Vercel Deployment: Serverless architecture optimized for zero-configuration deployments on Vercel.
- Supabase Database Integration: Scalable PostgreSQL persistence handling user sessions, profile notes, and custom metadata safely.
| Category | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite |
| Backend | Vercel Serverless Functions (Node.js runtime) |
| Database | Supabase (PostgreSQL) |
| Authentication | osu! OAuth 2.0 via Serverless API routes |
| Deployment | Vercel |
| Styling | Tailwind CSS, Framer Motion, Lucide React |
| Charts | Recharts |
| State Management | TanStack React Query, React Context |
| API | osu! API v2 |
git clone https://github.com/MonoGutsy/GDTracker.git
cd GDTrackernpm installCopy the template environment file and fill in your OAuth and database credentials:
cp .env.example .envnpm run devThe application will be available at http://localhost:5173. Ensure that your registered osu! OAuth callback matches your exact development origin (http://localhost:5173/api/auth/callback).
npm run build
npm run startConfigure the following variables before running the application:
OSU_CLIENT_ID=
OSU_CLIENT_SECRET=
OSU_REDIRECT_URI=
SESSION_SECRET=
SUPABASE_URL=
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=All secret keys (OSU_CLIENT_SECRET, SESSION_SECRET, and SUPABASE_SERVICE_ROLE_KEY) are utilized exclusively within server-side environments and must never be exposed to the browser.
GDTracker is engineered to run seamlessly on Vercel using Serverless Functions and Supabase.
Import the GitHub repository into your Vercel dashboard.
Add the required environment variables (OSU_CLIENT_ID, OSU_CLIENT_SECRET, OSU_REDIRECT_URI, SESSION_SECRET, SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY) under your project's environment settings. Ensure that OSU_REDIRECT_URI points to your production Vercel domain (for example: https://your-project.vercel.app/api/auth/callback).
Trigger the deployment. Vercel automatically builds the frontend static bundle and compiles the api/ directory into serverless endpoints.
Browser
↓
React + Vite
↓
Vercel Serverless Functions
↓
Supabase
↓
osu! API v2
- Server-Side Credentials: All sensitive OAuth secrets (
OSU_CLIENT_SECRET) and API keys remain strictly on the server side inside Vercel Serverless Functions. - Protected Client State: Browser sessions are managed via encrypted,
HttpOnly,SameSite=Laxcookies. The client bundle never receives or stores raw osu! access or refresh tokens. - Environment Isolation: Production secrets and database configuration are injected securely via Vercel Environment Variables at runtime.
- Public portfolios
- Collaboration insights
- Collections
- Advanced analytics
- Achievement system
- Portfolio sharing
- Additional statistics
- Fork the repository
- Create your feature branch (
git checkout -b feature/improvement) - Commit your changes (
git commit -m 'Add new tracking feature') - Open a Pull Request
This project is licensed under the MIT License.
- osu! for maintaining the rhythm game platform and community.
- osu! API v2 for providing reliable access to beatmap metadata and user profiles.
- The open-source community and library maintainers powering this stack.