PolyCode Backend

Express.js backend API serving documentation content with real-time file watching and markdown rendering.

🚀 Features

• Real-time File Watching - Auto-reloads documentation changes
• Markdown Rendering - Converts markdown to HTML with syntax highlighting
• File System API - Serves code and documentation from local directories
• CORS Support - Cross-origin requests for frontend integration
• Compression - Response compression for better performance
• Rate Limiting - Built-in protection against API abuse
• Health Monitoring - Service health check endpoint

📋 Prerequisites

• Node.js 16+
• npm or yarn
• Optional: MongoDB (if using database features)

🛠️ Installation

cd backend
npm install

⚙️ Configuration

Copy .env.example to .env and configure:

🚦 Running the Server

# Development (with auto-restart on file changes)
npm run dev

# Production
npm start

📡 API Endpoints

Documents

• GET /api/documents - List all documents and folders
• GET /api/documents/categories - Get document categories
• GET /api/documents/*path - Get specific document content

Health & Status

• GET /api/health - Server health check

Daily XP progress (auth required)

• GET /api/auth/progress/daily-xp — JSON daily XP breakdown per user (all courses)
• POST /api/auth/progress/daily-xp/record — body { "course", "lessonId", "title", "xp" } records lesson XP
• POST /api/auth/progress/daily-xp/mark-read — body { "date": "YYYY-MM-DD" }, marks day read and awards +3 XP once

Example GET /api/auth/progress/daily-xp response:

{
  "days": [
    {
      "date": "2026-06-23",
      "lessonXp": 25,
      "lessonsCompleted": 2,
      "read": false,
      "readBonusXp": 0,
      "xpEarned": 25
    }
  ],
  "totalXp": 128,
  "unreadDays": 1,
  "currentStreak": 3,
  "readBonusXp": 3
}

Polycoder progress (Postman-friendly JSON)

Import postman/PolyCode-Polycoder-Progress.postman_collection.json into Postman.

• GET /api/auth/polycoder/:username/progress — full progress for a polycoder (PolyCode username), including pointsByDay (daily points earned)
• GET /api/auth/polycoder/:username/daily-points — daily points only (lighter response)
• GET /api/auth/polycoder/me/progress — same payload for the logged-in user (Authorization: Bearer <token>)
• GET /api/auth/polycoder/me/daily-points — daily points for the logged-in user

Example GET /api/auth/polycoder/jane_dev/progress:

{
  "polycoder": "jane_dev",
  "userId": "665f1a2b3c4d5e6f7a8b9c0d",
  "profile": {
    "id": "665f1a2b3c4d5e6f7a8b9c0d",
    "username": "jane_dev",
    "firstName": "Jane",
    "lastName": "Dev",
    "preferredLanguages": ["Python"],
    "currentStreak": 3,
    "highestStreak": 7
  },
  "summary": {
    "languagesStarted": 2,
    "languagesCompleted": 0,
    "languagesInProgress": 1,
    "totalMinutesSpent": 45,
    "totalDocumentsCompleted": 12,
    "completedLessonsCount": 8,
    "oopsCppTotalXp": 120,
    "dailyXpTotal": 128,
    "currentStreak": 3,
    "highestStreak": 7
  },
  "languages": [],
  "courses": {
    "oopsCpp": null
  },
  "dailyXp": {
    "days": [
      {
        "date": "2026-06-23",
        "pointsEarned": 28,
        "lessonPoints": 25,
        "readBonusPoints": 3,
        "lessonsCompleted": 2,
        "courses": ["oops-cpp"],
        "lessons": [
          {
            "lessonId": "intro-classes",
            "course": "oops-cpp",
            "title": "Classes",
            "points": 15
          }
        ],
        "read": true
      }
    ],
    "totalPoints": 128,
    "totalXp": 128,
    "unreadDays": 0,
    "readBonusXp": 3
  },
  "pointsByDay": [
    {
      "date": "2026-06-23",
      "pointsEarned": 28,
      "lessonPoints": 25,
      "readBonusPoints": 3,
      "lessonsCompleted": 2,
      "courses": ["oops-cpp"],
      "lessons": [
        {
          "lessonId": "intro-classes",
          "course": "oops-cpp",
          "title": "Classes",
          "points": 15
        }
      ],
      "read": true
    }
  ],
  "generatedAt": "2026-06-27T12:00:00.000Z"
}

File Operations

• Auto-discovery - Scans data folder for documentation
• Real-time updates - File changes trigger automatic reload
• Markdown parsing - Converts .md files to HTML
• Code highlighting - Syntax highlighting for code files

📁 Project Structure

backend/
├── server.js              # Main Express server
├── routes/
│   └── documents.js       # Document API routes
├── models/                 # Database models (if needed)
├── utils/                 # Helper functions
├── data/                   # Documentation content (external)
├── .env.example           # Environment template
├── package.json           # Dependencies
└── README.md              # This file

🧩 Dependencies

Core

• express (v5.2.1) - Web framework
• cors (v2.8.6) - Cross-origin resource sharing
• dotenv (v17.3.1) - Environment variable management

File Processing

• chokidar (v5.0.0) - File system watcher
• fs-extra (v11.3.4) - Enhanced file system operations
• marked (v17.0.4) - Markdown parser
• highlight.js (v11.11.1) - Syntax highlighting

Performance & Security

• compression (v1.7.4) - Gzip compression
• express-rate-limit (v7.4.1) - Rate limiting

Database (Optional)

• mongoose (v9.3.0) - MongoDB ODM

Development

• nodemon (v3.1.14) - Auto-restart on changes

🔧 Development

File Watching

The backend automatically watches the data folder for changes:

• New files are detected and added to the API
• Modified files trigger real-time updates
• Deleted files are removed from the API

Error Handling

• Graceful handling of missing files
• Comprehensive error logging
• Fallback to default configurations

🌐 Production Deployment

# Set production environment
export NODE_ENV=production

# Start the server
npm start

Environment Variables for Production

• NODE_ENV=production - Enables production optimizations
• PORT - Server port (default: 5000)
• PYTHON_PATH - Absolute path to documentation folder

🔍 Troubleshooting

Common Issues

File not found errors

• Check PYTHON_PATH in .env
• Verify data folder exists and contains files

CORS errors

• Ensure frontend is running on allowed origins
• Check CORS configuration in server.js

Performance issues

• Enable compression middleware
• Consider caching strategies
• Monitor file system changes

Debug Mode

Enable verbose logging:

VERBOSE_LOGGING=true

📝 License

QuantumLogics Pvt Ltd. License

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📞 Support

For issues and questions:

• Check the troubleshooting section
• Review server logs for detailed error messages
• Verify environment configuration