Codouss - Interactive Code Execution Platform

Write, Execute, and Share Code Instantly in Your Browser

🌟 Overview

Codouss is a comprehensive web-based REPL (Read-Eval-Print Loop) platform that enables instant code execution across multiple programming languages directly in your browser. Built with modern technologies and a focus on user experience, it provides a VS Code-like coding environment with powerful features for learning, prototyping, and collaboration.

✨ Features

🎯 Complete Implementation - All 4 Project Steps

✅ Step 1: Basic REPL

Monaco Editor Integration: Full VS Code editing experience in browser
Multi-Language Support: Python, JavaScript, TypeScript
Instant Code Execution: Client-side execution with Pyodide for Python
Real-time Output: Live execution results with comprehensive error handling
Syntax Highlighting: Language-specific syntax highlighting and autocomplete

✅ Step 2: Script Management

Create & Save Scripts: Persistent script storage with cloud synchronization
Script Library: Organized dashboard with search and filtering
Auto-save: Never lose your work with automatic saving
Script Operations: Edit, delete, duplicate, and organize scripts
Import/Export: Download scripts and import existing code

✅ Step 3: User Authentication & Cross-Device Access

Secure Authentication: JWT-based login system with encrypted passwords
User Registration: Quick and easy account creation
Cross-Device Sync: Access your scripts from anywhere
Session Management: Secure session handling with auto-refresh
Password Security: Secure password hashing and change functionality

✅ Step 4: Multi-Language Support

Python: Full Python 3 with NumPy, Pandas, Matplotlib libraries
JavaScript: Modern ES6+ features, async/await, Promise support
TypeScript: Type-safe JavaScript with full TypeScript compilation
Extensible Architecture: Easy to add more programming languages

🎨 Modern User Interface

Dark Coding Theme

Optimized for Coding: Eye-friendly dark theme designed for long coding sessions
Syntax Highlighting: Beautiful, accurate syntax highlighting for all languages
Terminal-style Output: Realistic terminal appearance with color-coded output
Responsive Design: Works perfectly on desktop, tablet, and mobile devices

Intuitive Navigation

Clean Dashboard: Beautiful card-based script management interface
Smart Search: Find scripts by name, content, or programming language
Activity Stats: View your coding activity and favorite languages
Quick Actions: Fast access to common operations

👤 Comprehensive User Management

Profile Management

User Profile Page: Complete profile management with avatar and stats
Activity Statistics: Track your coding activity and progress
Account Information: View and edit username, email, and account details
Data Export: Download all your scripts and data in JSON format
Account Security: Secure account deletion with confirmation

Settings & Preferences

Editor Customization: Font size, theme, tab size, line numbers
Code Preferences: Default language, auto-save, word wrap, minimap
Privacy Controls: Public profile, activity visibility settings
Security Settings: Password change, notification preferences
Data Management: Export data, reset settings, account controls

🔧 Advanced Features

Smart Script Management

Duplicate Prevention: Intelligent handling of duplicate script names
Script Forking: Create copies of scripts with auto-generated unique names
Validation: Real-time validation with helpful error messages
Bulk Operations: Select and manage multiple scripts at once

Code Execution Engine

Secure Execution: Client-side code execution eliminates server security risks
Performance Optimized: Fast execution with WebAssembly (Pyodide)
Error Handling: Comprehensive error capture and display
Output Formatting: Clean, readable output with proper formatting

Developer Experience

Monaco Editor: Full VS Code editing experience with IntelliSense
Live Collaboration Ready: Architecture supports future real-time features
Extensible Plugin System: Ready for custom language plugins
API-First Design: RESTful API for all operations

🚀 Technology Stack

Frontend Architecture

React 18 with TypeScript for type-safe development
Vite for lightning-fast development and optimized builds
TailwindCSS for modern, responsive styling
Monaco Editor for professional code editing experience
Pyodide for secure client-side Python execution
Framer Motion for smooth animations and transitions
React Query for efficient API state management
React Router for seamless navigation

Backend Architecture

Flask web framework with RESTful API design
SQLAlchemy ORM for database operations
JWT Authentication for secure user sessions
SQLite database (easily upgradeable to PostgreSQL/MySQL)
CORS for secure cross-origin requests
Werkzeug for password hashing and security

Development Tools

TypeScript for enhanced code quality and developer experience
ESLint & Prettier for code formatting and linting
Vitest for comprehensive testing
Concurrently for development server management

📁 Project Structure

codouss/
├── frontend/                 # React + TypeScript frontend
│   ├── src/
│   │   ├── components/      # Reusable UI components
│   │   │   └── ui/         # Core UI component library (40+ components)
│   │   ├── pages/          # Application pages
│   │   │   ├── Auth.tsx    # Login/Register page
│   │   │   ├── Dashboard.tsx # Script management dashboard
│   │   │   ├── Editor.tsx  # Code editor with execution
│   │   │   ├── Profile.tsx # User profile management
│   │   │   ├── Settings.tsx # User preferences
│   │   │   └── NotFound.tsx # 404 error page
│   │   ├── contexts/       # React contexts
│   │   │   ├── AuthContext.tsx        # User authentication
│   │   │   └── CodeExecutionContext.tsx # Code execution state
│   │   ├── lib/           # Utilities and API clients
│   │   │   ├── api.ts            # API client functions
│   │   │   ├── codeExecution.ts  # Pyodide integration
│   │   │   ├── errorHandling.ts  # Error management
│   │   │   └── utils.ts          # Utility functions
│   │   └── hooks/         # Custom React hooks
│   ├── public/            # Static assets
│   └── package.json       # Frontend dependencies
├── backend/               # Flask backend API
│   ├── app.py            # Main Flask application
│   ├── config.py         # Configuration settings
│   ├── requirements.txt  # Python dependencies
│   └── .env.example      # Environment variables template
├── package.json          # Root package.json for monorepo
├── README.md            # This comprehensive documentation
└── START.md             # Quick start guide

🛠️ Installation & Setup

Prerequisites

Node.js 18+ and npm (for frontend)
Python 3.8+ and pip (for backend)
Git for version control

Quick Start

Clone the Repository
```
git clone <repository-url>
cd codouss
```
Install All Dependencies
```
npm run install:all
```

Set Up Environment Variables

cd backend
cp .env.example .env
# Edit .env with your configuration

Start Development Servers

# From root directory - starts both frontend and backend
npm run dev

Access the Application
- Frontend: http://localhost:3000
- Backend API: http://localhost:5000

Manual Setup

Frontend Setup

cd frontend
npm install
npm run dev

Backend Setup

cd backend
pip install -r requirements.txt
python app.py

🎯 Usage Guide

Getting Started

Create Account: Register with username, email, and password
Dashboard: View your script library and activity statistics
Create Script: Click "New Script" to start coding
Choose Language: Select Python, JavaScript, or TypeScript
Write Code: Use Monaco editor with full autocomplete and syntax highlighting
Execute: Click "Run" to execute code instantly in your browser
Save Script: Give your script a name and save for future access

Code Execution Environments

Python Environment

Libraries: NumPy, Pandas, Matplotlib pre-installed
Execution: Secure client-side execution via Pyodide
Features: Full Python 3 syntax, exception handling, output capture
Security: Sandboxed execution with no server-side risks

JavaScript Environment

Features: ES6+, async/await, modern JavaScript APIs
Execution: Direct browser execution in isolated scope
Capabilities: DOM manipulation, fetch API, Promise handling
Security: Controlled execution environment

TypeScript Environment

Features: Full TypeScript syntax with type checking
Compilation: Automatic transpilation to JavaScript
Type Safety: Real-time type error detection
IntelliSense: Advanced code completion and hints

Script Management

Dashboard Features

Script Library: View all saved scripts with thumbnails
Search & Filter: Find scripts by name, content, or language
Statistics: View coding activity and favorite languages
Quick Actions: Edit, delete, fork, or run scripts

Advanced Operations

Script Forking: Create copies with auto-generated unique names
Bulk Management: Select and operate on multiple scripts
Import/Export: Share scripts or backup your work
Version History: Track script modifications

Profile & Settings

Profile Management

Personal Information: Update username, email, and avatar
Activity Stats: View coding statistics and achievements
Data Export: Download all scripts and profile data
Account Security: Manage password and security settings

Editor Preferences

Theme Options: Dark, light, or high-contrast themes
Font Settings: Adjustable font size and family
Editor Features: Line numbers, minimap, word wrap, auto-save
Language Defaults: Set preferred programming language

🔧 Configuration

Environment Variables

Create backend/.env file:

# Security Keys (CHANGE IN PRODUCTION)
SECRET_KEY=your-super-secret-key-here
JWT_SECRET_KEY=your-jwt-secret-key-here

# Database Configuration
DATABASE_URL=sqlite:///codouss.db
# For PostgreSQL: DATABASE_URL=postgresql://username:password@localhost/codouss
# For MySQL: DATABASE_URL=mysql://username:password@localhost/codouss

# CORS Settings
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

# Environment
FLASK_ENV=development
FLASK_DEBUG=1

Database Configuration

Development (SQLite)

DATABASE_URL=sqlite:///codouss.db

Production (PostgreSQL)

DATABASE_URL=postgresql://username:password@host:port/database

Production (MySQL)

DATABASE_URL=mysql://username:password@host:port/database

🚀 Deployment

Frontend Deployment

Build for Production

cd frontend
npm run build

Deploy to Netlify/Vercel

Upload frontend/dist/ folder
Set build command: npm run build
Set publish directory: dist

Backend Deployment

Using Gunicorn

cd backend
pip install gunicorn
gunicorn -w 4 -b 0.0.0.0:5000 app:app

Docker Deployment

# Backend Dockerfile
FROM python:3.9-slim
WORKDIR /app
COPY backend/ .
RUN pip install -r requirements.txt
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:5000", "app:app"]

Environment Variables for Production

SECRET_KEY=your-production-secret-key
JWT_SECRET_KEY=your-production-jwt-key
DATABASE_URL=your-production-database-url
CORS_ORIGINS=https://your-domain.com
FLASK_ENV=production

🔐 Security Features

Code Execution Security

Client-side Execution: All code runs in user's browser (Pyodide for Python)
Sandboxed Environment: Isolated execution with limited system access
No Server-side Code Execution: Eliminates server security vulnerabilities
Input Validation: All user inputs validated and sanitized

Authentication Security

JWT Tokens: Stateless authentication with secure token handling
Password Hashing: Bcrypt password hashing with salt
Session Management: Secure session handling with auto-refresh
CORS Protection: Proper cross-origin request handling

Data Security

Input Sanitization: All inputs validated against XSS and injection
SQL Injection Prevention: Parameterized queries with SQLAlchemy
Secure Headers: Proper security headers implementation
Data Privacy: User data encrypted and properly handled

📊 Performance

Frontend Performance

Code Splitting: Optimized bundle sizes with lazy loading
Asset Optimization: Compressed images and minified code
Caching Strategy: Efficient browser caching for static assets
Loading States: Smooth user experience with loading indicators

Backend Performance

Database Indexing: Optimized queries with proper indexing
Connection Pooling: Efficient database connection management
Caching: Response caching where appropriate
API Optimization: Minimal response payloads and efficient endpoints

Code Execution Performance

Pyodide Optimization: Cached Python environment for faster execution
WebAssembly: Near-native execution speed for Python code
Memory Management: Efficient memory usage and cleanup
Concurrent Execution: Non-blocking code execution

🗄️ Database Schema

Users Table

CREATE TABLE user (
    id VARCHAR(36) PRIMARY KEY,
    username VARCHAR(80) UNIQUE NOT NULL,
    email VARCHAR(120) UNIQUE NOT NULL,
    password_hash VARCHAR(200) NOT NULL,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Scripts Table

CREATE TABLE script (
    id VARCHAR(36) PRIMARY KEY,
    title VARCHAR(200) NOT NULL,
    content TEXT DEFAULT '',
    language VARCHAR(50) DEFAULT 'python',
    user_id VARCHAR(36) NOT NULL,
    is_public BOOLEAN DEFAULT FALSE,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES user (id) ON DELETE CASCADE
);

📈 API Documentation

Authentication Endpoints

POST /api/auth/register - Register new user
POST /api/auth/login - User login
GET /api/auth/me - Get current user info

Script Management Endpoints

GET /api/scripts - Get user's scripts
POST /api/scripts - Create new script
GET /api/scripts/{id} - Get specific script
PUT /api/scripts/{id} - Update script
DELETE /api/scripts/{id} - Delete script
POST /api/scripts/{id}/fork - Fork script
POST /api/scripts/check-name - Check name availability

User Management Endpoints

GET /api/user/profile - Get user profile
PUT /api/user/profile - Update profile
PUT /api/user/password - Change password
GET /api/user/settings - Get user settings
PUT /api/user/settings - Update settings
GET /api/user/export - Export user data
DELETE /api/user/account - Delete account

Public Endpoints

GET /api/public/scripts - Get public scripts
GET /api/health - Health check

🧪 Testing

Run Tests

# Frontend tests
cd frontend
npm test

# Backend tests (if implemented)
cd backend
python -m pytest

Test Coverage

Unit Tests: Core utility functions and API endpoints
Integration Tests: Full user workflows and authentication
E2E Tests: Complete user journeys from registration to execution

🗺️ Development Roadmap

Current Features (v1.0)

✅ Multi-language code execution (Python, JavaScript, TypeScript)
✅ User authentication and account management
✅ Script saving and management
✅ Profile and settings pages
✅ Dark theme optimized for coding
✅ Responsive design for all devices
✅ Comprehensive error handling
✅ Data export and import

Planned Features (v2.0)

🔄 Real-time collaboration and sharing
🔄 Code sharing with public script library
�� Plugin system for custom languages
🔄 Advanced code analysis and linting
🔄 Integration with GitHub/GitLab
🔄 Mobile app (React Native)
🔄 Team workspaces and collaboration
🔄 Code completion and AI assistance

Future Enhancements (v3.0)

🔄 Live collaboration editing
🔄 Video chat integration for pair programming
🔄 Advanced analytics and insights
🔄 Custom themes and editor extensions
🔄 Marketplace for code snippets
🔄 Educational features and tutorials

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Guidelines

Fork the Repository
Create Feature Branch: git checkout -b feature/amazing-feature
Follow Code Standards: Use TypeScript for frontend, PEP 8 for backend
Write Tests: Include tests for new features
Update Documentation: Keep README and comments current
Commit Changes: git commit -m 'Add amazing feature'
Push to Branch: git push origin feature/amazing-feature
Open Pull Request: Describe your changes clearly

Code Standards

Frontend: TypeScript, ESLint, Prettier formatting
Backend: Python PEP 8, type hints, docstrings
UI/UX: Follow existing design patterns and accessibility guidelines
Testing: Write tests for new functionality

🆘 Support & Troubleshooting

Common Issues

Pyodide Loading Problems

Check browser console for errors
Ensure stable internet connection (loads from CDN)
Try refreshing the page or clearing browser cache

Backend Connection Issues

Verify Flask server is running on port 5000
Check CORS settings in backend configuration
Ensure environment variables are properly set

Frontend Build Issues

Run npm install in frontend directory
Clear node_modules and reinstall if needed
Check Node.js version compatibility

Database Issues

Verify database connection string
Check file permissions for SQLite database
Ensure database migrations are applied

Getting Help

GitHub Issues: Report bugs and request features
Documentation: Check this README and START.md

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Monaco Editor team for the excellent web-based code editor
Pyodide project for bringing Python to the browser
React and Flask communities for robust frameworks
TailwindCSS for beautiful, utility-first styling
Radix UI for accessible component primitives

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
backend		backend
frontend		frontend
README.md		README.md
START.md		START.md

oussssaman/codouss

Folders and files

Latest commit

History

Repository files navigation

Codouss - Interactive Code Execution Platform

🌟 Overview

✨ Features

🎯 Complete Implementation - All 4 Project Steps

✅ Step 1: Basic REPL

✅ Step 2: Script Management

✅ Step 3: User Authentication & Cross-Device Access

✅ Step 4: Multi-Language Support

🎨 Modern User Interface

Dark Coding Theme

Intuitive Navigation

👤 Comprehensive User Management

Profile Management

Settings & Preferences

🔧 Advanced Features

Smart Script Management

Code Execution Engine

Developer Experience

🚀 Technology Stack

Frontend Architecture

Backend Architecture

Development Tools

📁 Project Structure

🛠️ Installation & Setup

Prerequisites

Quick Start

Manual Setup

Frontend Setup

Backend Setup

🎯 Usage Guide

Getting Started

Code Execution Environments

Python Environment

JavaScript Environment

TypeScript Environment

Script Management

Dashboard Features

Advanced Operations

Profile & Settings

Profile Management

Editor Preferences

🔧 Configuration

Environment Variables

Database Configuration

Development (SQLite)

Production (PostgreSQL)

Production (MySQL)

🚀 Deployment

Frontend Deployment

Build for Production

Deploy to Netlify/Vercel

Backend Deployment

Using Gunicorn

Docker Deployment

Environment Variables for Production

🔐 Security Features

Code Execution Security

Authentication Security

Data Security

📊 Performance

Frontend Performance

Backend Performance

Code Execution Performance

🗄️ Database Schema

Users Table

Scripts Table

📈 API Documentation

Authentication Endpoints

Script Management Endpoints

User Management Endpoints

Public Endpoints

🧪 Testing

Run Tests

Test Coverage

🗺️ Development Roadmap

Packages