PyScape-Basic 🎓

The foundational single-agent adaptive learning system for Python & AI.

What is PyScape-Basic?

PyScape-Basic is a clean, foundational implementation of the PyScape adaptive learning ecosystem. It's designed to teach Python, AI, Machine Learning, and Data Science through personalized learning paths, real-time coding challenges, interactive visualizations, and guided projects.

This is the base version because it:

✅ Has clear, modular architecture
✅ Teaches core concepts of adaptive learning systems
✅ Serves as the foundation for research variants and multi-agent extensions
✅ Prioritizes educational clarity over complex orchestration

Looking for something else?

Multi-agent orchestration? → See pyscape-multi-agent
Research benchmarks? → See pyscape-research

🚀 Core Features

1. Adaptive Learning Platform

📚 Personalized learning roadmaps based on interests
🎮 Gamified progression (XP, levels, achievements)
🎯 Topic-driven skill tree for Python + AI domains

2. Real-Time Code Duels ⚔️

👥 Live 1v1 competitive coding battles
🎯 Skill-based matchmaking by difficulty and language
🔗 WebSocket-powered real-time updates
🏆 Leaderboard rankings and statistics

3. Algorithm Visualizers

🔄 Sorting (Bubble, Quick, Merge, Heap)
🗺️ Pathfinding (A*, Dijkstra, BFS, DFS)
📊 K-Means Clustering
🧠 Neural Network Architecture
⬇️ Gradient Descent Optimization
🌳 Data Structures (trees, graphs, heaps)

4. ML Sandbox

🐍 Python with NumPy, Pandas, Matplotlib
☕ JavaScript (browser-based)
☕ Java with full library support
⚙️ C/C++ compilation and execution
💾 Interactive code execution with stdin/stdout

5. Guided Project Labs

🎓 Step-by-step project walkthroughs
📈 Performance metrics and visualization
🎓 Project completion tracking

6. Portfolio Generation

📄 Markdown and PDF export
🏅 Showcase completed projects
📊 Display skills and achievements
📤 Shareable portfolio links

🏗️ Architecture

Frontend: React + Tailwind CSS + Framer Motion
Backend: Node.js Express + WebSockets
Database: Supabase (PostgreSQL + Real-time)
Code Execution: Judge0 API
Authentication: Supabase Auth (JWT)

System Architecture

┌─────────────────────┐       ┌──────────────────────┐
│  Frontend (React)   │       │ Backend (Express)    │
│                     │◄─────►│                      │
│ Pages (Feature-org) │  HTTP │ REST API Routes      │
│ Components          │       │ Services             │
│ Context/Hooks       │       │ Models               │
└─────────────────────┘       └──────────────────────┘
         │                            │
         └────────────────┬───────────┘
                          │
                   ┌──────▼──────┐
                   │  Supabase   │
                   │ PostgreSQL  │
                   │   Real-time │
                   └─────────────┘

See ARCHITECTURE.md for full system design.

⚡ Quick Start

Prerequisites

Node.js v16+
npm or yarn
Supabase account (free tier works)

Installation

Clone the repository

git clone https://github.com/yourusername/pyscape-basic.git
cd pyscape-basic

Create environment file

cp .env.example .env
# Fill in your Supabase and Judge0 credentials

Install dependencies and start

Terminal 1 - Frontend:

cd frontend
npm install
npm start

Terminal 2 - Backend REST API:

cd backend
npm install
npm run dev

Terminal 3 - Backend WebSocket:

cd backend
npm run dev:duel

Visit http://localhost:3000 → Sign up → Select topics → Start learning! 🚀

📚 Documentation

DEVELOPMENT.md — Setup, running, and debugging
ARCHITECTURE.md — System design and data flow
API.md — REST and WebSocket API reference
DATABASE.md — Schema and migrations
FEATURES/ — Feature-specific documentation
CONTRIBUTING.md — How to contribute

🗂️ Project Structure

pyscape-basic/
├── frontend/              # React frontend application
│   └── src/
│       ├── pages/        # Feature-based pages
│       ├── components/   # Reusable UI components
│       ├── features/     # Feature-specific logic
│       ├── services/     # API and Supabase clients
│       └── utils/        # Helper functions
├── backend/               # Express.js API
│   └── src/
│       ├── routes/       # API endpoints and WebSocket handlers
│       ├── services/     # Business logic
│       ├── models/       # Database models
│       └── config/       # Configuration
├── database/              # Database schema and migrations
├── docs/                  # Comprehensive documentation
├── .github/               # GitHub templates and workflows
└── scripts/               # Utility scripts

See docs/ARCHITECTURE.md for full structure details.

🎮 How It Works

User Journey: Onboarding → Learning → Dueling → Portfolio

1. Sign Up (Auth.js)
   └─> Supabase Auth created

2. Select Topics (TopicSelection.js)
   └─> Roadmap generated based on interests

3. Start Learning (Dashboard.js → Learn.js)
   └─> Complete lessons (reading, quiz, coding)
   └─> Earn XP and unlock levels

4. Practice with Code Duels (CodeDuel.js)
   └─> Real-time 1v1 battles
   └─> Climb leaderboard
   └─> Earn competitive XP

5. Build Portfolio (ProjectLabs.js → Portfolio.js)
   └─> Complete guided projects
   └─> Generate and export portfolio

6. Share (Portfolio.js)
   └─> Download as PDF
   └─> Share link with recruiters/peers

🤖 Real-Time Features

Code Duels (WebSocket)

Matchmaking — Find opponent with similar skill level
Live Progress — See opponent's test pass count
Real-time Chat — Communicate during duel
Instant Results — Code execution via Judge0 API
Leaderboard — Global rankings updated live

Algorithm Visualizers

Step-by-step visualization of algorithms
Play/pause/speed controls
Compare different approaches
Educational explanations

🔧 Configuration

See DEVELOPMENT.md for detailed setup.

Key environment variables:

# Supabase
REACT_APP_SUPABASE_URL=
REACT_APP_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# Judge0 API (for code execution)
JUDGE0_API_HOST=
JUDGE0_API_KEY=

# Backend
BACKEND_PORT=5000
WS_PORT=8080
NODE_ENV=development

📊 Learning Path Example

User selects: Python, Machine Learning, Data Science

Generated roadmap:

Level 1: Python Basics
├─ Intro to Python (reading)
├─ Variables & Types (quiz)
└─ Control Flow (coding problem)

Level 2: Data Science Fundamentals
├─ NumPy Essentials (reading)
├─ Pandas Tutorial (coding lab)
└─ Data Visualization (interactive)

Level 3: Machine Learning
├─ Supervised Learning (reading)
├─ Build Classifier (project lab)
└─ Evaluate Model (guided)

Level 4: Applied AI
├─ Neural Networks (reading)
├─ Train & Deploy (project)
└─ Capstone Project (showcase)

Users progress through lessons, earn XP, and unlock projects!

🎯 Design Principles

Clarity — Code and documentation are clear and easy to follow
Modularity — Features are independent and reusable
Scalability — Architecture supports growth and research variants
Maintainability — Clean separation of concerns
Educational — Suitable for learning and teaching system design

🚀 Deployment

Deploy Frontend (Vercel)

cd frontend
npm run build
# Deploy build/ folder to Vercel

Deploy Backend (Heroku, Railway, etc.)

cd backend
# Push to hosting platform
# Set environment variables in dashboard

Database (Supabase)

Already cloud-hosted
Automatic backups
Real-time subscriptions included

See docs/DEVELOPMENT.md for detailed deployment steps.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

Code style guide
Commit message format
Pull request process
Bug report template
Feature request template

Ways to contribute:

💻 Code improvements
📚 Documentation
🐛 Bug reports
💡 Feature suggestions
🎨 UI/UX feedback

📈 Roadmap

Phase 2: Advanced matchmaking, expanded content, engagement features
Phase 3: Community features, instructor tools, public portfolios
Phase 4: AI tutor, advanced analytics, adaptive difficulty
Phase 5: Mobile app, IDE extensions, research ecosystem

See ROADMAP.md for detailed plans.

🔒 Security

✅ Supabase Auth with JWT tokens
✅ Row-Level Security (RLS) on all tables
✅ Code execution in isolated containers (Judge0)
✅ No API keys exposed in frontend
✅ CORS protection on backend

Reporting security issues: Please email security@pyscape.dev (or contact maintainers privately)

📝 License

MIT License — See LICENSE for details.

🙌 Acknowledgments

Built with:

📞 Support

Documentation: See docs/
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: connect @zxnb01

🌟 Show Your Support

If this project helps you, please:

⭐ Star the repository
🔗 Share with others
📝 Leave feedback
🚀 Contribute!

Start your learning journey today! 🚀

Get Started | Features | API Docs | Architecture

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github		.github
backend		backend
database		database
docs		docs
migrations		migrations
public		public
scripts		scripts
src		src
supabase/migrations		supabase/migrations
.editorconfig		.editorconfig
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
prd.md		prd.md
project_till_now.md		project_till_now.md
tailwind.config.js		tailwind.config.js

Folders and files

Latest commit

History

Repository files navigation

PyScape-Basic 🎓

What is PyScape-Basic?

This is the base version because it:

Looking for something else?

🚀 Core Features

1. Adaptive Learning Platform

2. Real-Time Code Duels ⚔️

3. Algorithm Visualizers

4. ML Sandbox

5. Guided Project Labs

6. Portfolio Generation

🏗️ Architecture

System Architecture

⚡ Quick Start

Prerequisites

Installation

📚 Documentation

🗂️ Project Structure

🎮 How It Works

User Journey: Onboarding → Learning → Dueling → Portfolio

🤖 Real-Time Features

Code Duels (WebSocket)

Algorithm Visualizers

🔧 Configuration

📊 Learning Path Example

🎯 Design Principles

🚀 Deployment

Deploy Frontend (Vercel)

Deploy Backend (Heroku, Railway, etc.)

Database (Supabase)

🤝 Contributing

📈 Roadmap

🔒 Security

📝 License

🙌 Acknowledgments

📞 Support

🌟 Show Your Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages