Trackeep/Others/oauth-service/README.md

Trackeep Main Controller

The Trackeep Main Controller is a centralized service that handles authentication, user management, and learning content management for all Trackeep instances. It transforms the original OAuth service into a comprehensive learning management system with a beautiful dashboard interface.

🛠️ Tech Stack

Backend:

• Go - High-performance API server
• Gin - HTTP web framework
• JWT - Authentication tokens
• OAuth2 - GitHub integration

Frontend:

• SolidJS - Reactive UI framework
• TypeScript - Type-safe development
• TailwindCSS - Utility-first styling
• Vite - Fast build tool

Features:

• 🔐 Centralized Authentication - GitHub OAuth and email verification for all users
• 📚 Learning Management - Create and manage free courses with YouTube, ZTM, GitHub, and Fireship resources
• 🖥️ Instance Management - Register and monitor Trackeep instances
• 📊 Visual Dashboard - Beautiful Trackeep-inspired UI for management
• 🔗 Secure Connections - Automatic secure API key handling between instances

For Users:

• Free Learning - All courses are completely free (price always $0.00)
• No Instructors - Self-paced learning with curated resources
• Progress Tracking - Monitor your learning progress across courses
• Single Sign-On - One GitHub account for all Trackeep instances

For Administrators:

• Course Creation - Easy-to-use interface for creating learning paths
• Resource Management - Support for YouTube, Zero to Mastery, GitHub, Fireship links
• Instance Monitoring - Track all connected Trackeep instances
• User Analytics - Dashboard with comprehensive statistics

🚀 Quick Start

1. Setup the Main Controller

# Navigate to the main controller
cd oauth-service

# Install frontend dependencies
npm install

# Build the frontend
npm run build

# Run the service (production mode)
go run main.go

2. Development Mode

For development with hot reload:

# Use the development script (starts both backend and frontend)
./dev.sh

# Or start manually:
# Terminal 1: Backend
go run main.go

# Terminal 2: Frontend dev server
npm run dev

3. Access the Dashboard

Open your browser to:

• Dashboard: http://localhost:9090/dashboard (production) or http://localhost:5174/dashboard (development)
• Course Management: http://localhost:9090/dashboard/courses
• Instance Management: http://localhost:9090/dashboard/instances
• API Documentation: http://localhost:9090/api/v1

4. GitHub OAuth Setup (Optional)

For full authentication, set up GitHub OAuth:

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Create a new OAuth app with:
   • Application name: Trackeep Main Controller
   • Homepage URL: http://localhost:9090
   • Authorization callback URL: http://localhost:9090/auth/github/callback
3. Add credentials to .env file

📡 API Endpoints

Authentication:

• GET /auth/github - Initiate GitHub OAuth flow
• GET /auth/github/callback - Handle GitHub callback
• POST /api/v1/email/send - Send verification code
• POST /api/v1/email/verify - Verify email code

Course Management:

• GET /api/v1/courses - List all courses
• POST /api/v1/courses - Create new course
• GET /api/v1/courses/:id - Get course details
• PUT /api/v1/courses/:id - Update course
• DELETE /api/v1/courses/:id - Delete course
• GET /api/v1/courses/:id/resources - Get course resources
• POST /api/v1/courses/:id/resources - Add course resource

User Progress:

• GET /api/v1/progress/:user_id - Get user's all progress
• GET /api/v1/progress/:user_id/:course_id - Get course progress
• POST /api/v1/progress/:user_id/:course_id - Update progress

Instance Management:

• GET /api/v1/instances - List all instances
• POST /api/v1/instances - Register new instance
• GET /api/v1/instances/:id - Get instance details
• PUT /api/v1/instances/:id - Update instance
• DELETE /api/v1/instances/:id - Delete instance

Dashboard:

• GET /api/v1/dashboard/stats - Get dashboard statistics
• GET /api/v1/dashboard/courses - Get courses for dashboard
• GET /api/v1/dashboard/users - Get users for dashboard (admin only)

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Trackeep App   │    │ Main Controller  │    │   GitHub API    │
│                 │    │                  │    │                 │
│ OAuth Login ────┼───>│ /auth/github     ────>│ OAuth Flow      │
│                 │    │                  │    │                 │
│ Course API ─────┼───>│ /api/v1/courses  │    │                 │
│                 │    │                  │    │                 │
│ Progress Sync ──┼───>│ /api/v1/progress │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

📚 Course Structure

Supported Resource Types:

• 🎥 YouTube - Video tutorials and playlists
• 🎓 Zero to Mastery - ZTM courses and content
• 🐙 GitHub - Repositories, projects, and code examples
• 🔥 Fireship - Fast-paced tutorials and courses
• 🔗 Links - Any other web resources

Course Example:

{
  "title": "Complete Web Development Bootcamp",
  "description": "Learn modern web development from scratch",
  "category": "web-development",
  "difficulty": "beginner",
  "duration": 40,
  "price": 0.0,
  "tags": ["javascript", "react", "nodejs"],
  "resources": [
    {
      "title": "Introduction to Web Development",
      "type": "youtube",
      "url": "https://www.youtube.com/watch?v=RW-sB6GeA_Q",
      "duration": 45,
      "is_required": true
    }
  ]
}

🔒 Security Features

• 🔐 JWT Authentication - Secure token-based authentication
• 🛡️ API Key Management - Automatic secure key generation for instances
• 🔗 CORS Support - Configurable allowed origins
• ✅ CSRF Protection - State parameter validation
• 📊 Rate Limiting - GitHub API rate limit awareness

🎨 Dashboard Features

Main Dashboard:

• 📊 Real-time statistics
• 📚 Recent courses overview
• 🖥️ Active instances monitoring
• 📈 User progress analytics

Course Management:

• ➕ Easy course creation wizard
• ✏️ Visual course editing
• 🏷️ Tag-based organization
• 📱 Responsive design

Instance Management:

• 🔗 Secure instance registration
• 📊 Connection status monitoring
• 🔑 API key management
• 📈 Instance analytics

🔧 Configuration

Environment Variables:

# Service Configuration
PORT=9090
JWT_SECRET=your-super-secret-jwt-key

# GitHub OAuth (Optional)
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_REDIRECT_URL=http://localhost:9090/auth/github/callback

# Email Verification (Optional)
SMTP_HOST=smtp.purelymail.com
SMTP_PORT=587
SMTP_USERNAME=your_purelymail_username
SMTP_PASSWORD=your_purelymail_password

# CORS
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:8080

🚀 Production Deployment

Docker Deployment:

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY . .
RUN go mod download && go build -o trackeep-controller

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/trackeep-controller .
COPY .env .
COPY templates/ ./templates/
EXPOSE 9090
CMD ["./trackeep-controller"]

Docker Compose:

version: '3.8'
services:
  trackeep-controller:
    build: ./oauth-service
    ports:
      - "9090:9090"
    environment:
      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
      - JWT_SECRET=${JWT_SECRET}
    restart: unless-stopped

📝 Benefits

For Learners:

• ✅ Completely Free - All courses are $0.00
• ✅ Self-Paced - Learn at your own speed
• ✅ Quality Content - Curated YouTube, ZTM, GitHub, Fireship resources
• ✅ Progress Tracking - Monitor your learning journey
• ✅ Single Sign-On - One account for all Trackeep instances

For Administrators:

• ✅ Easy Management - Beautiful dashboard interface
• ✅ Secure Connections - Automatic API key handling
• ✅ Scalable - Serve unlimited instances
• ✅ Analytics - Comprehensive usage statistics
• ✅ Zero Setup - Works out of the box with sample data

For Developers:

• ✅ RESTful API - Clean, well-documented endpoints
• ✅ Flexible Resources - Support for multiple content types
• ✅ Secure by Default - Built-in authentication and authorization
• ✅ Easy Integration - Simple API key-based connections

🎯 Use Cases

• 🎓 Educational Platforms - Free learning management system
• 👥 Developer Communities - Share learning resources
• 🏢 Corporate Training - Internal skill development
• 📚 Course Aggregators - Curate learning content
• 🚀 Startup Education - Onboarding and training programs

🔄 Multi-Instance Support

The Main Controller can serve multiple Trackeep instances:

// Instance 1
fetch('http://localhost:9090/api/v1/courses', {
  headers: { 'Authorization': 'Bearer instance1_api_key' }
});

// Instance 2  
fetch('http://localhost:9090/api/v1/courses', {
  headers: { 'Authorization': 'Bearer instance2_api_key' }
});

Each instance gets its own API key and can securely access the centralized course catalog and user management.

---

Trackeep Main Controller - Complete learning management system with beautiful dashboard and secure multi-instance support. 🚀