Codeum 🚀

🧠 Practice the skills you actually use.

Codeum is an open-source developer skill practice platform by Skelvric. It is intentionally not a LeetCode clone: the focus is on short, realistic exercises around debugging, runtime reasoning, code review, and refactoring.

🛠️ Stack

• ⚡ Next.js App Router
• ⚛️ React 19
• 🔷 TypeScript
• 🍃 MongoDB official Node.js driver (no ORM)
• 🎨 Tailwind CSS + CSS Modules
• 🌓 next-themes for light/dark mode
• 🧩 lucide-react for UI icons
• 🛡️ Zod for server-side validation
• 🔐 HTTP-only, database-backed sessions with device management
• 🌍 Content-first i18n in data/content.ts

🎯 Product Model

Codeum is guest-first.

Visitors can browse Practice, open a challenge, run JavaScript in a browser Web Worker, submit it, and see the result without creating an account.

An account becomes necessary when the user wants to:

• 💾 Persist completion history
• 📈 Earn Codeum Score and XP
• 🧠 Build skill progress
• 👤 Create and customize a public developer profile

The core loop is:

Landing → Practice → Challenge → Run → Submit → Result → Progress

🧩 Challenge Philosophy

Challenges are designed to test transferable engineering judgment, not trivia.

✅ Prefer

• Clear symptoms and realistic code context
• 🎯 A single primary learning objective
• 🪤 Plausible wrong paths
• 🔍 Edge cases that reward careful reading
• 💡 Concise explanations after success
• ⏱️ Short sessions, roughly 30 seconds to 15 minutes

❌ Avoid

• Giant algorithm prompts
• Syntax trivia
• Trick questions with no practical value
• Problems that reward memorization instead of engineering judgment

🌐 Browser Execution

JavaScript challenges can opt into:

execution.mode="browser"

The code is executed in a dedicated Web Worker in the user's browser.

Common network primitives are blocked and a hard timeout terminates the worker.

Browser execution is not trusted for ranking. The final Submit request is checked by the server-side deterministic verifier.

Rating and XP are persisted only for authenticated users, and each user can receive completion rewards only once per challenge.

This is intentionally a JavaScript-first MVP architecture.

⚠️ Do not execute arbitrary user code inside the Next.js process.

When Codeum needs Python, additional runtimes, dependency installation, or secret hidden tests, add a separate isolated runner service with resource limits and sandboxing.

🔐 Authentication & Sessions

Sessions use opaque random tokens.

Only a SHA-256 token hash is stored in MongoDB.

Active sessions also keep:

• 🌐 User-agent / device information
• 🌍 IP information
• ⏳ Expiry state
• 🚫 Revocation state

Users can manage their active sessions from Settings and:

• Revoke individual devices
• Sign out of all other sessions

👤 Developer Profiles

Codeum includes customizable public developer profiles with:

• 🖼️ Avatar
• 📝 Bio
• 📍 Location
• 🌐 Website
• 🐙 GitHub
• 💼 LinkedIn
• 🏆 Codeum Score
• ⚡ XP
• ✅ Completed challenges
• 🧠 Skill progress

Public profiles are available at:

/u/[username]

🌍 Internationalization

Codeum supports:

• 🇬🇧 English — default
• 🇹🇷 Turkish

Localized content is centralized in:

data/content.ts

🌓 Theme

Codeum supports:

• ☀️ Light mode
• 🌙 Dark mode

Theme switching is handled with next-themes.

🗄️ MongoDB

Collections use camelCase naming:

• users
• sessions
• submissions
• ratingEvents
• challengeCompletions
• rateLimits

Required indexes are created automatically when the application connects to MongoDB.

There are no seed or migration scripts in this repository.

🏠 Local Setup

npm install
npm run dev

The application will then be available at the configured local development URL.

🚀 Production

npm install
npm run build
npm start

Environment variables are documented in:

.env.example

🛡️ Production Checklist

Before going public:

• 🗄️ Use a production MongoDB deployment with backups
• 🔐 Set production secrets securely
• 🌐 Serve the application over HTTPS
• 🚫 Never commit .env files or secrets
• 🛡️ Put the application behind a trusted proxy/CDN that preserves the real client IP headers
• 📊 Review error logging and database alerting
• ✅ Run a real npm run build before deployment
• 🧪 Test login, logout, device revocation, guest challenges, and authenticated scoring from a clean browser session
• 📱 Test responsive layouts on real mobile devices

📁 Project Structure

app/ Next.js routes and API handlers
components/ Reusable UI components
components/example/ Example CSS Module component pattern
data/content.ts Localized product copy
lib/auth/ Session and authentication helpers
lib/challenges/ Challenge model, browser runner and verifier
lib/db/ MongoDB client and data types
lib/security/ Rate limiting

🏗️ Architecture

Codeum follows a modular architecture with clear boundaries between UI, domain logic, authentication, database access, and challenge verification.

For a detailed overview of the project structure, challenge quality standards, and code execution architecture, see:

👉 docs/ARCHITECTURE.md

🤝 Open Source

Codeum is developed and maintained by Skelvric.

Contributions, feedback, challenge ideas, and issue reports are welcome.

📄 License

Codeum is released under the MIT LICENSE.