SOBIE Conference API Documentation

Bug Reporting System with GitHub Integration

Overview

The SOBIE Conference Bug Reporting System provides a comprehensive solution for users to report bugs in the application, which automatically creates GitHub issues in the sobieNode repository. This system integrates with the existing communication system to notify administrators and keep users informed about bug resolution progress.

Features

🐛 Bug Reporting

🔗 GitHub Integration

📊 Admin Dashboard

🔔 Communication Integration

API Endpoints

User Endpoints

Submit Bug Report

POST /api/bug-reports

Request Body:

{
  "title": "Login button not working on mobile",
  "description": "When I tap the login button on my phone, nothing happens. The page doesn't respond.",
  "category": "mobile",
  "severity": "medium",
  "priority": "normal",
  "stepsToReproduce": [
    "Open the app on mobile browser",
    "Navigate to login page", 
    "Enter credentials",
    "Tap login button"
  ],
  "expectedBehavior": "Should log in and redirect to dashboard",
  "actualBehavior": "Button doesn't respond to taps",
  "additionalContext": "Issue only occurs on mobile devices",
  "environment": {
    "browser": "Safari",
    "browserVersion": "17.0",
    "operatingSystem": "iOS 17.1",
    "screenResolution": "390x844",
    "url": "https://sobie.example.com/login"
  },
  "userCanContact": true,
  "contactPreference": "in_app",
  "createGithubIssue": true
}

Response:

{
  "success": true,
  "message": "Bug report submitted successfully",
  "data": {
    "bugReport": {
      "id": "65f8b12c45d6e7f8a9b0c1d2",
      "title": "Login button not working on mobile",
      "category": "mobile",
      "severity": "medium",
      "status": "submitted",
      "githubIssue": {
        "issueNumber": 42,
        "issueUrl": "https://github.com/thesobie/sobieNode/issues/42",
        "status": "created"
      },
      "createdAt": "2024-03-15T10:30:00Z"
    }
  }
}

Get My Bug Reports

GET /api/bug-reports/my-reports?status=submitted&page=1&limit=10

Get Bug Report Details

GET /api/bug-reports/{reportId}

Admin Endpoints

Get All Bug Reports

GET /api/bug-reports/admin/all?status=submitted&severity=high&page=1

Update Bug Status

PUT /api/bug-reports/{reportId}/status

Request Body:

{
  "status": "resolved",
  "resolution": "Fixed in version 1.2.0 - login button touch events now properly handled on mobile devices",
  "assignedTo": "dev_user_id"
}

Get Bug Statistics

GET /api/bug-reports/admin/statistics?timeframe=30d

Response:

{
  "success": true,
  "data": {
    "current": {
      "totalBugs": 15,
      "byStatus": {
        "submitted": 5,
        "in_progress": 7,
        "resolved": 3
      },
      "byCategory": {
        "functionality": 8,
        "ui_ux": 4,
        "mobile": 3
      },
      "bySeverity": {
        "low": 2,
        "medium": 10,
        "high": 3
      },
      "avgTimeToResolve": 48.5
    }
  }
}

Check GitHub Status

GET /api/bug-reports/admin/github-status

Utility Endpoints

Get Bug Categories

GET /api/bug-reports/categories

Get Severity Levels

GET /api/bug-reports/severity-levels

Get Bug Report Template

GET /api/bug-reports/template

GitHub Integration Setup

Environment Variables

Add to your .env file:

# GitHub Integration
GITHUB_TOKEN=your_personal_access_token_here

GitHub Token Requirements

The GitHub token needs the following permissions:

Generating GitHub Token

  1. Go to GitHub Settings → Developer settings → Personal access tokens
  2. Click “Generate new token (classic)”
  3. Select scopes:
    • repo (Full control of private repositories)
    • write:discussion (Write access to discussions)
  4. Copy the token and add to your .env file

Label Management

The system automatically creates these labels in your repository:

Category Labels:

Severity Labels:

Priority Labels:

System Labels:

Bug Categories

Category Description Examples
UI/UX User interface or experience issues Layout problems, confusing navigation, styling issues
Functionality Features not working as expected Buttons not working, forms not submitting, broken workflows
Performance Speed, loading, or responsiveness issues Slow page loads, timeouts, memory issues
Data Data inconsistency or corruption Missing data, incorrect calculations, sync issues
Security Security vulnerabilities or concerns Authentication bypasses, data exposure, XSS vulnerabilities
Mobile Mobile-specific issues Touch problems, responsive design issues, mobile browser bugs
Integration Third-party service problems API failures, payment processing issues, email delivery problems
Other Issues that don’t fit other categories Configuration problems, deployment issues

Severity Levels

Severity Description Response Time Examples
Low Minor issue, workaround available 7-14 days Cosmetic issues, minor typos
Medium Affects functionality but not blocking 3-7 days Form validation errors, broken links
High Significant impact on user experience 1-3 days Login issues, data not saving
Critical Blocks core functionality or security risk Same day App crashes, security vulnerabilities

Workflow

1. User Reports Bug

// Frontend code example
const reportBug = async (bugData) => {
  const response = await fetch('/api/bug-reports', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${userToken}`
    },
    body: JSON.stringify({
      title: bugData.title,
      description: bugData.description,
      category: bugData.category,
      severity: bugData.severity,
      stepsToReproduce: bugData.steps,
      environment: {
        browser: navigator.userAgent,
        screenResolution: `${screen.width}x${screen.height}`,
        url: window.location.href
      }
    })
  });
  
  const result = await response.json();
  if (result.success) {
    showNotification('Bug report submitted! GitHub issue #' + result.data.bugReport.githubIssue.issueNumber);
  }
};

2. System Processing

  1. Validation: Input validation and sanitization
  2. GitHub Issue Creation: Automatic issue creation with formatted content
  3. Notification: Admins notified via communication system
  4. Confirmation: User receives confirmation with GitHub link

3. Admin Workflow

// Admin dashboard example
const updateBugStatus = async (bugId, newStatus, resolution) => {
  const response = await fetch(`/api/bug-reports/${bugId}/status`, {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${adminToken}`
    },
    body: JSON.stringify({
      status: newStatus,
      resolution: resolution
    })
  });
  
  // This automatically:
  // - Updates bug in database
  // - Syncs status to GitHub issue
  // - Notifies user of status change
  // - Closes GitHub issue if resolved
};

4. GitHub Issue Example

When a bug report is submitted, it creates a GitHub issue like this:

## Bug Report

**Reported by:** John Doe (john.doe@example.com)
**Category:** MOBILE
**Severity:** MEDIUM
**Priority:** NORMAL

## Description
Login button not working on mobile devices. When I tap the login button on my phone, nothing happens.

## Steps to Reproduce
1. Open the app on mobile browser
2. Navigate to login page
3. Enter credentials
4. Tap login button

## Expected Behavior
Should log in and redirect to dashboard

## Actual Behavior
Button doesn't respond to taps

## Environment
- **Browser:** Safari 17.0
- **OS:** iOS 17.1
- **Screen Resolution:** 390x844
- **URL:** https://sobie.example.com/login
- **Timestamp:** 2024-03-15T10:30:00Z

---
**Internal ID:** 65f8b12c45d6e7f8a9b0c1d2
**Contact User:** Yes
**Contact Preference:** in_app

Labels: bug, user-reported, category:mobile, severity:medium, browser:safari, os:ios

Database Schema

BugReport Model

{
  // Basic information
  reporterId: ObjectId,          // User who reported
  title: String,                 // Bug title
  description: String,           // Detailed description
  category: String,              // Bug category
  severity: String,              // Severity level
  priority: String,              // Priority level
  
  // Reproduction details
  stepsToReproduce: [{
    step: Number,
    description: String
  }],
  expectedBehavior: String,
  actualBehavior: String,
  additionalContext: String,
  
  // Environment information
  environment: {
    browser: String,
    browserVersion: String,
    operatingSystem: String,
    screenResolution: String,
    userAgent: String,
    url: String,
    timestamp: Date
  },
  
  // GitHub integration
  githubIssue: {
    issueNumber: Number,
    issueUrl: String,
    createdAt: Date,
    status: String              // 'pending', 'created', 'failed'
  },
  
  // Status tracking
  status: String,               // Workflow status
  assignedTo: ObjectId,         // Assigned developer
  resolution: String,           // Resolution description
  resolvedAt: Date,
  resolvedBy: ObjectId,
  timeToResolve: Number,        // Hours to resolve
  
  // Contact preferences
  userCanContact: Boolean,
  contactPreference: String,    // 'email', 'in_app', 'none'
  
  // Relations
  relatedConference: ObjectId,
  relatedSession: ObjectId,
  relatedSubmission: ObjectId,
  
  // Metadata
  createdAt: Date,
  updatedAt: Date
}

Testing

Run Bug Report Tests

node src/tests/bugReportTests.js

Test GitHub Integration

# Set your GitHub token
export GITHUB_TOKEN="your_token_here"

# Run the tests
node src/tests/bugReportTests.js

Manual Testing

  1. Submit a bug report via POST /api/bug-reports
  2. Check GitHub - verify issue was created at https://github.com/thesobie/sobieNode/issues
  3. Update status via PUT /api/bug-reports/{id}/status
  4. Verify GitHub sync - check that issue was updated/closed

Security Considerations

Performance Optimization

Integration with Existing Systems

Communication System

User Management

Conference System

Monitoring and Analytics

Bug Metrics

GitHub Integration Health

Future Enhancements

Troubleshooting

Common Issues

GitHub token not working:

Issues not being created:

Labels not appearing:

Debug Commands

# Test GitHub connection
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     https://api.github.com/repos/thesobie/sobieNode

# Check repository permissions
curl -H "Authorization: Bearer $GITHUB_TOKEN" \
     https://api.github.com/repos/thesobie/sobieNode/issues

# Test label creation
curl -X POST \
     -H "Authorization: Bearer $GITHUB_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"test-label","color":"ff0000"}' \
     https://api.github.com/repos/thesobie/sobieNode/labels

This comprehensive bug reporting system provides a seamless way for users to report issues while automatically creating GitHub issues for development tracking, ensuring no bugs fall through the cracks!