🎯 Cirkle - Perfect Circle Challenge

A creative circle-drawing game with real-time leaderboards powered by MongoDB and Deno 2.

✨ Features

• Perfect Circle Challenge: Draw circles and get scored on precision
• MongoDB Leaderboards: Persistent global rankings
• Real-time Competition: See how you rank against other players
• Dark Mode: Beautiful light/dark themes
• Detailed Scoring: Circularity, Closure, and Smoothness metrics
• Mobile Responsive: Works on all devices

🚀 Quick Start

Prerequisites

• Deno 2 installed
• MongoDB (local or cloud)

1. Clone & Install

git clone <your-repo>
cd cirkle

2. Database Setup (Choose One)

🌟 Option A: MongoDB Atlas (Recommended - Online Database)

For persistent global leaderboards, use MongoDB Atlas:

1. Follow the detailed setup guide: See SETUP_MONGODB_ATLAS.md for complete step-by-step instructions
2. Quick setup: Copy the template and configure your connection

   cp env.template .env
   # Edit .env with your MongoDB Atlas connection string

Option B: No Database (Local Development)

For quick testing without setup:

# Just run the app - it will use localStorage
deno task dev
# ⚠️ Leaderboard data will be local only

Option C: Local MongoDB

# Install MongoDB locally
brew install mongodb/brew/mongodb-community  # macOS
# Start MongoDB
brew services start mongodb/brew/mongodb-community
# Create .env file
echo "MONGODB_URI=mongodb://localhost:27017/cirkle" > .env

3. Run the Application

deno task dev

Visit http://localhost:8000 and start drawing circles! 🎨

🏆 Leaderboard System

API Endpoints

• GET /api/leaderboard - Get top 50 scores
• POST /api/leaderboard - Submit new score
• GET /api/leaderboard/stats - Get statistics
• DELETE /api/leaderboard - Clear all scores (admin)

Data Structure

interface LeaderboardEntry {
  name: string;
  score: number;  // 0-100%
  date: string;   // ISO timestamp
  metrics: {
    circularityScore: number;
    closureScore: number;
    smoothnessScore: number;
  };
}

Fallback Mode

If MongoDB is unavailable, the app automatically falls back to localStorage for offline functionality.

🎮 How to Play

1. Draw a Circle: Click and drag to draw a circle anywhere on the page
2. Get Scored: Algorithm analyzes your circle's perfection (0-100%)
3. Make the Leaderboard: Scores ≥70% prompt for your name
4. Compete: Check the 🏆 leaderboard to see global rankings
5. Improve: Try to join the elite 95% Club!

🛠 Development

Project Structure

cirkle/
├── main.ts          # Deno server with MongoDB integration
├── deno.json        # Deno configuration & dependencies
├── public/
│   ├── index.html   # Main application
│   ├── style.css    # Responsive styling
│   └── script.js    # Circle drawing & leaderboard logic
└── README.md

Key Technologies

• Backend: Deno 2 with MongoDB integration
• Frontend: Vanilla JavaScript with HTML5 Canvas
• Database: MongoDB with automatic fallback to localStorage
• Styling: Modern CSS with glassmorphism effects
• Algorithm: Mathematical circle analysis with 4 metrics

🔧 Configuration

MongoDB Collections

The app automatically creates:

• leaderboard collection with score/date indexes
• Efficient queries for top scores and statistics

Performance Features

• Caching: Static assets cached for 1 hour
• Indexing: MongoDB indexes for fast leaderboard queries
• Graceful Degradation: Automatic fallback to localStorage
• CORS: Enabled for cross-origin requests

📊 Scoring Algorithm

Circles are scored on:

• Circularity (55%): How round your shape is
• Closure (30%): How well you complete the loop
• Smoothness (15%): How fluid your drawing motion is

Target: 95%+ to join the elite circle masters! 👑

🎨 Features

• 🌙 Dark Mode: Toggle between light/dark themes
• 📱 Mobile Ready: Touch support and responsive design
• 🎉 Celebrations: Confetti and animations for high scores
• ⌨️ Shortcuts: Ctrl+C (clear), Ctrl+R (particles), Ctrl+Shift+C (tips)
• 🔧 Developer Tools: Console logging and performance metrics

🤝 Contributing

Pull requests welcome! Areas for improvement:

• Advanced scoring algorithms
• Multiplayer competitions
• Social features
• Performance optimizations

📄 License

MIT License - feel free to use this code for your own projects!

---

Happy Circle Drawing! 🎯✨