A narrative-driven cyberpunk AI operating system where you learn Python through interactive missions.
CodeQuest AI is not just another coding platform—it is a narrative-driven AI operating system.
We grew tired of boring video tutorials and sterile, static coding environments. Instead of watching someone else code, players become Agents inside the neon-lit, dystopian Neural City. To progress, you must hack corporate AI systems, solve programming challenges, interact with dynamic AI NPCs, and unlock restricted districts.
CodeQuest AI seamlessly fuses premium gamification, AI-driven mentorship, and an immersive cyberpunk storyline into an entirely new way to master Python.
Traditional coding education is fundamentally broken. Here is how we fix it.
| Feature | Normal Coding Platform | CodeQuest AI |
|---|---|---|
| Learning Format | Watch videos ❌ | Live AI Missions ✅ |
| Environment | Static Exercises ❌ | Interactive Story ✅ |
| Engagement | Boring tests ❌ | XP + Levels + Badges ✅ |
| Assistance | Read the docs ❌ | Live AI Mentor (Ghost) ✅ |
| Aesthetics | Sterile UI ❌ | Cyberpunk Neural OS ✅ |
|
🤖 AI Story Engine The world reacts to your code. Interactions and challenges are dynamically driven by our AI engine. |
⚔️ Interactive Missions Solve practical Python challenges—from basic data types to advanced vector operations. |
|
💻 Python Sandbox A live, sandboxed code execution environment directly in your browser. |
👻 AI Mentor Meet "Ghost", your AI NPC companion who guides you, hints at solutions, and reacts to your progress. |
|
🗺️ District Progression Unlock new areas of Neural City as you level up your skills and complete story arcs. |
📈 XP System Earn experience points for every successful hack, optimal solution, and completed mission. |
|
🏆 Achievements Unlock exclusive badges and showcase your prowess on the Neural Grid. |
🎨 Cyberpunk UI A premium, glassmorphism-heavy OS interface designed with Framer Motion. |
|
🔒 Authentication Secure military-grade login via Better Auth and Google OAuth. |
👑 Leaderboard Compete against other rogue agents globally for the top spot. |
Landing Page
Dashboard
District Map
Mission Terminal
Ghost AI
Authentication
CodeQuest AI uses a modern, scalable, and decoupled architecture.
graph TD
A[User] -->|Interacts| B(Next.js App Router)
B -->|API Routes| C{Secure Backend API}
C -->|Database Queries| D[Prisma ORM]
D -->|Persistent Data| E[(PostgreSQL)]
C -->|AI Inference| F[Gemini AI Engine]
F -->|Persona| G[Ghost AI NPC]
C -->|Code Execution| H[Vercel Serverless Python]
A highly organized, maintainable, and scalable project structure.
codequest-ai/
├── api/ # Vercel serverless execution endpoints
├── app/ # Next.js 15 App Router routes and layouts
├── components/ # Reusable UI elements (HUDs, Modals, Forms)
├── lib/ # Utility functions, auth clients, and API wrappers
├── hooks/ # Custom React hooks
├── prisma/ # Database schema and seed scripts
├── public/ # Static assets (images, logos, fonts)
├── styles/ # Global CSS and Tailwind configurations
└── types/ # Global TypeScript definitions
| Category | Technology |
|---|---|
| Framework | Next.js 15 App Router (React 19) |
| Authentication | Better Auth |
| Database | PostgreSQL |
| ORM | Prisma ORM |
| AI Integration | Google Gemini API |
| Styling & Animations | Tailwind CSS + Framer Motion |
| Deployment | Vercel |
| Package Manager | npm |
Follow these steps to deploy Neural City on your local machine.
git clone https://github.com/Divyanshu-2907/CodeQuest-AI.git
cd CodeQuest-AInpm installCopy the example environment file and configure it.
cp .env.example .envPush the schema and seed the initial missions.
npx prisma db push
npx tsx --env-file=.env prisma/seed.tsnpm run dev| Variable | Purpose | Required | Example |
|---|---|---|---|
DATABASE_URL |
PostgreSQL connection string | ✅ | postgresql://neondb_owner:... |
BETTER_AUTH_SECRET |
Security key for session encryption | ✅ | super_secret_string_123 |
BETTER_AUTH_URL |
Base URL for auth callbacks | ✅ | http://localhost:3000 |
GEMINI_API_KEY |
Key for Ghost NPC and AI generation | ✅ | AIzaSy... |
- Login: Users authenticate via the military-grade
CinematicLoginCard. - Onboarding: New agents are introduced to Neural City's lore.
- District Map: An interactive 3D/parallax map showing unlocked sectors.
- Mission Terminal: The core IDE where code is written and evaluated.
- Ghost Mentorship: The AI character provides real-time hints when stuck.
- XP & Leaderboard: Successful executions grant XP, ranking users globally.
The heartbeat of CodeQuest AI is powered by large language models.
- Ghost NPC: A meticulously prompted AI persona that acts as your underground guide.
- Mission Evaluation: AI assists in evaluating edge-case code solutions.
- Story Engine: Dynamic dialogue generation that makes every interaction feel unique.
- Hint Generation: Context-aware hints based directly on the user's syntax errors.
Note
"An interface should not just be used; it should be felt."
- NeuralOS: The overarching design language. Dark mode native.
- Glassmorphism: Frosted glass panels over moving geometric backgrounds.
- HUD Elements: Cybernetic overlays, progress bars, and tactical data streams.
- Motion Design: Every interaction is spring-loaded and physics-based via Framer Motion.
- Typography: Custom monospace and geometric sans-serif fonts for that authentic terminal feel.
- App Router: Fully leveraging Next.js 15 for optimal routing.
- Server Components: Pushing heavy lifting to the server to keep the client fast.
- Lazy Loading & Dynamic Imports: Only loading complex 3D or editor components when needed.
- Image Optimization: Next/Image with proper sizing and format handling.
- GPU Animations: Offloading Framer Motion properties to hardware acceleration.
- Authentication: Handled entirely by
Better Authensuring secure session management. - Protected Routes: Middleware guarantees that only authenticated agents access the grid.
- Sandboxed Execution: Python code is evaluated securely using Vercel Serverless isolated environments.
- Environment Scrubbing: Complete
os.environclearance before code execution prevents data leaks.
- Python Execution Sandbox
- AI NPC (Ghost)
- District Progression System
- Voice AI: Ghost speaks directly to you.
- Multiplayer: Co-op missions and hacking challenges.
- Boss Battles: Time-constrained, high-stakes coding sprints.
- Rust Integration: Learn memory safety through cyber-defense missions.
- VS Code Extension: Bring Neural City directly into your IDE.
We welcome contributions from fellow agents!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Please read our Contributing Guidelines for details on our code of conduct and the process for submitting pull requests.
Distributed under the MIT License. See LICENSE for more information.
Divyanshu Kumar
- GitHub: @Divyanshu-2907
- LinkedIn: Divyanshu Kumar
- Email: Contact Me