A Discord bot for collaborative productivity tracking with Strava-style social features. Track study/work sessions, earn XP and achievements, compete on leaderboards, and build study groups.
- Session Tracking - Start, pause, and complete sessions with live timers
- XP & Leveling - Earn 10 XP per hour, level up, unlock 50+ achievements
- Leaderboards - Compete daily, weekly, monthly, and all-time
- Study Groups - Team up (max 5 members) for XP bonuses up to 50%
- Social Feed - Share sessions with auto-generated images and reactions
- Goals & Events - Set daily goals and create collaborative study sessions
- Rich Visualizations - Beautiful stats, profiles, and leaderboards
# 1. Install dependencies
npm install
# 2. Configure environment (.env file)
cp .env.example .env
# Add: DISCORD_BOT_TOKEN, DISCORD_CLIENT_ID, FIREBASE_PROJECT_ID
# Place: firebase-service-account.json in project root
# 3. Test Puppeteer (especially on Windows)
npm run test:puppeteer
# 4. Run the bot
npm run devWindows users: If you encounter Puppeteer issues, see WINDOWS_SETUP.md for detailed setup instructions.
Deploy to Railway in minutes:
# Push to GitHub
git push origin main
# Connect to Railway (railway.app)
# Set environment variables
# Auto-deploy on push!See Deployment Guide for detailed instructions.
| Command | Description |
|---|---|
/start |
Start a productivity session |
/stop |
Complete session and post to feed |
/time |
Check session status |
/stats |
View your statistics |
/me |
View your profile |
/leaderboard |
Server rankings |
/creategroup |
Create a study group |
/group |
View group overview |
50+ total commands - See Commands Reference for complete list.
- Setup Guide - Installation and configuration
- Commands Reference - All available commands explained
- Architecture - System design and data flow
- API Documentation - Service layer reference
- Deployment Guide - Production deployment
- Contributing - How to contribute
- TypeScript - Type-safe development
- Discord.js v14 - Discord API framework
- Firebase Firestore - Real-time database
- Puppeteer + React - Image generation
- Railway - Deployment platform
src/
├── bot.ts # Main entry point, command handlers
├── types.ts # TypeScript interfaces
├── services/ # Business logic (Session, Stats, XP, etc.)
├── components/ # React components for images
├── data/ # Static data (achievements, badges)
└── utils/ # Utility functions
docs/ # Complete documentation
├── README.md # Documentation hub
├── SETUP.md # Installation guide
├── COMMANDS.md # Command reference
├── ARCHITECTURE.md # System architecture
├── API.md # Developer API
├── DEPLOYMENT.md # Deploy to production
└── CONTRIBUTING.md # Contribution guide
User runs /start
↓
SessionService creates active session
↓
User runs /stop
↓
SessionService completes session
↓
XPService calculates XP (10/hour + bonuses)
↓
StatsService updates stats & streaks
↓
AchievementService checks unlocks
↓
PostService creates feed post with image
✓
User earns XP, levels up, unlocks achievements!
See Architecture Documentation for detailed flow diagrams.
Base XP: 10 XP per hour
Bonuses:
- Group membership: +1% per group level (max 50%)
- Streak milestones: +50-250 XP
- Achievement unlocks: +50-1000 XP
Leveling: Exponential curve
- Level 1 → 2: 100 XP
- Level 10 → 11: 3,162 XP
- Level 20 → 21: 8,944 XP
Create teams of up to 5 members:
- Group XP: All member sessions contribute
- Group Levels: Same progression as users
- XP Bonus: 1% per group level for all members
- Public/Private: Control discoverability
- Group Leaderboard: Compete with other groups
Example: Level 25 group = 25% XP bonus for all members!
Firebase Firestore collections:
discord-data/
├── activeSessions/sessions/{userId} # One active session per user
├── sessions/completed/{sessionId} # All completed sessions
├── userStats/stats/{userId} # Stats, XP, achievements
├── groups/active/{groupId} # Study groups
├── groupMembers/memberships/{userId} # User group memberships
├── sessionPosts/posts/{messageId} # Feed posts
├── dailyGoals/goals/{userId} # User goals
├── events/scheduled/{eventId} # Study events
└── serverConfig/configs/{serverId} # Server settings
npm run dev # Development mode (auto-reload)
npm run build # Compile TypeScript
npm start # Production modeSee Contributing Guide for development workflow.
/start activity: Learning React hooks
→ ✅ Session started! 0h 0m elapsed
/time
→ 📊 Active session: Learning React hooks
Elapsed: 1h 23m | Status: Active
/stop
→ (Modal appears)
Title: React Practice
Description: Built a todo app with useState and useEffect
→ ✅ Session completed! +83 XP | Posted to feed
/creategroup name: Study Warriors public: true
→ ✅ Group Created! Study Warriors (GP-A1B2)
Share: /joingroup GP-A1B2
/group
→ (Image shows group stats)
Study Warriors | Level 10 (+10% XP)
5/5 members | 245 total hours
50+ unlockable achievements:
- Milestones: First session, 100 sessions
- Time: 10h, 100h, 1000h studied
- Streaks: 7 days, 30 days, 100 days
- Schedule: Early Bird, Night Owl, Weekend Warrior
- Social: Reactions, kudos given/received
- Meta: All achievements unlocked
Each achievement awards bonus XP (50-1000 XP)!
| Variable | Required | Description |
|---|---|---|
DISCORD_BOT_TOKEN |
Yes | Bot token from Discord Developer Portal |
DISCORD_CLIENT_ID |
Yes | Application ID from Discord |
FIREBASE_PROJECT_ID |
Yes | Firebase project ID |
FIREBASE_SERVICE_ACCOUNT |
Production | Service account JSON (for Railway) |
Local: Use .env file + firebase-service-account.json
Production: Use Railway environment variables
- Push to GitHub
- Connect repository to Railway
- Set environment variables
- Deploy automatically!
Cost: Free tier available, ~$5-10/month for production
See Deployment Guide for complete instructions.
- Documentation: docs/
- Issues: GitHub Issues
- Questions: Check Setup Guide and Commands Reference
We welcome contributions! See Contributing Guide for:
- Code style guidelines
- Development workflow
- Pull request process
- Issue reporting
ISC
Ready to get started?
- Setup Guide - Install the bot
- Commands Reference - Learn all commands
- Deployment Guide - Deploy to production