NeuroBlock - Neural Network Playground

A visual, drag-and-drop interface for building and training neural networks. Built for beginners to learn machine learning concepts without writing code.

🎯 Features

Core Functionality

• Drag-and-Drop Interface: Scratch-style puzzle piece connectors for intuitive block stacking
• 4 Workflow Zones: Sequential zones guide users through the entire ML workflow
• 20+ Building Blocks: Organized by category (Data, Architecture, Activation, Configuration, Actions)
• Real-time Training: Live training metrics with WebSocket updates
• Interactive Chat Assistant: AI-powered explanations using Gemini API
• Project Management: Save and load projects with Supabase
• Model Export: Export trained models and Python code

User Experience

• Beginner-Friendly: No coding required, visual interface
• Real-time Validation: Immediate feedback on architecture validity
• Visual Feedback: Progress tracking, error indicators, and success states
• Dark Mode: Dashboard always in dark mode, playground supports theme switching
• Auto-save: Automatic project saving every 30 seconds
• Manual Save: Save button for immediate progress saving

Block Categories

• Data Blocks: Load Dataset, Train/Test Split, Normalize
• Architecture Blocks: Input Layer, Dense, Conv2D, Flatten, MaxPooling2D, Dropout
• Activation Blocks: ReLU, Sigmoid, Tanh, Softmax
• Configuration Blocks: Optimizer (7 types), Loss Function (3 types), Training Settings
• Action Blocks: Train Model, Make Prediction

🚀 Getting Started

Prerequisites

• Node.js 18+ and npm
• Python 3.8+
• Supabase Account (for authentication and database)
• Gemini API Key (optional, for chat assistant)

Installation

1. Clone the Repository

git clone https://github.com/yourusername/NeuroBlock.git
cd NeuroBlock

2. Backend Setup

cd backend

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

3. Frontend Setup

cd frontend

# Install dependencies
npm install

4. Environment Variables

Backend (backend/.env):

GEMINI_API_KEY=your-gemini-api-key-here

Frontend (frontend/.env):

VITE_SUPABASE_URL=your-supabase-project-url
VITE_SUPABASE_ANON_KEY=your-supabase-anon-key

5. Database Setup

1. Create a Supabase project at supabase.com
2. Go to SQL Editor in your Supabase dashboard
3. Copy and paste the entire contents of supabase_schema.sql
4. Click "Run" to execute the SQL
5. Verify tables were created: profiles, projects, trained_models
6. Copy your project URL and anon key to frontend/.env

6. Gemini API Setup (Optional)

1. Get an API key from Google AI Studio
2. Add it to backend/.env as GEMINI_API_KEY
3. Install the package: pip install google-genai python-dotenv

Running the Application

Start Backend

cd backend
source venv/bin/activate  # On Windows: venv\Scripts\activate
python main.py

Backend runs on http://localhost:8000

Start Frontend

cd frontend
npm run dev

Frontend runs on http://localhost:5173

📖 How to Use

Step 1: Create an Account

1. Navigate to the landing page
2. Click "Get Started" or "Sign Up"
3. Create an account with email and password

Step 2: Create a Project

1. In the dashboard, click "New Project"
2. Enter a project name
3. Click "Create"

Step 3: Build Your Architecture

Load Data

1. Expand "Data Blocks" in the left panel
2. Drag "Load Dataset" to Zone 1
3. MNIST dataset loads automatically

Build Architecture

1. Drag blocks to Zone 2 in order:
   • Input Layer (must be first)
   • Architecture blocks (Dense, Conv2D, etc.)
   • Activation functions (ReLU, Softmax, etc.)

Example Simple Network:

Input Layer
→ Flatten
→ Dense (128 neurons)
→ ReLU
→ Dense (10 neurons)
→ Softmax

Example CNN:

Input Layer
→ Conv2D (32 filters, 3×3)
→ ReLU
→ MaxPooling2D (2×2)
→ Flatten
→ Dense (128 neurons)
→ ReLU
→ Dense (10 neurons)
→ Softmax

Configure Training

1. Drag blocks to Zone 3:
   • Optimizer (click to configure: Adam, SGD, RMSprop, etc.)
   • Loss Function (click to configure: Categorical Crossentropy, etc.)
   • Training Settings (set epochs, batch size, learning rate)

Step 4: Train Your Model

1. Drag "Train Model" to Zone 4
2. Click "Start Training" in the right panel
3. Watch real-time metrics update
4. View training progress in graphs and console

Step 5: Make Predictions

1. After training completes, go to "Predict" tab
2. Draw a digit on the canvas
3. Click "Predict" to see the model's prediction

Step 6: Ask Questions

1. Go to "Explain" tab
2. Ask questions about your architecture
3. Get AI-powered explanations in simple terms

🏗️ Architecture

Frontend

• React 18 with TypeScript
• Tailwind CSS for styling
• Zustand for state management
• React DnD for drag-and-drop
• Recharts for data visualization
• Socket.IO Client for real-time updates
• React Router for navigation
• Supabase Client for authentication and database

Backend

• FastAPI for REST API and WebSocket
• TensorFlow/Keras for model building and training
• Socket.IO for real-time training updates
• NumPy for data processing
• Google Gemini API for AI chat assistant

Database

• Supabase (PostgreSQL) for:
  • User authentication
  • Project storage
  • Trained model storage
  • Workflow data persistence

📁 Project Structure

NeuroBlock/
├── backend/
│   ├── main.py                 # FastAPI server
│   ├── model_builder.py        # Block-to-Keras translation
│   ├── dataset_loader.py       # MNIST dataset loading
│   └── requirements.txt        # Python dependencies
├── frontend/
│   ├── src/
│   │   ├── components/         # React components
│   │   ├── pages/              # Page components
│   │   ├── store/              # Zustand state management
│   │   ├── utils/              # Utility functions
│   │   └── api/                # API client
│   └── package.json
├── landing_page/               # Landing page components
├── supabase_schema.sql         # Database schema
└── README.md

🔧 Configuration

Optimizers

• Adam (default)
• SGD
• RMSprop
• Adagrad
• Adamax
• Nadam
• Ftrl

Loss Functions

• Categorical Crossentropy (multi-class classification)
• Binary Crossentropy (binary classification)
• Mean Squared Error (regression)

Data Preprocessing

• Train/Test Split: Configurable ratio (default: 0.2)
• Normalization: Min-Max (0-1) or Standard (mean=0, std=1)

🎓 Example Architectures

Simple Dense Network (~97% accuracy)

Load Dataset → Normalize
Input → Flatten → Dense(128) → ReLU → Dense(10) → Softmax
Adam optimizer, Categorical Crossentropy, 10 epochs

CNN (~99% accuracy)

Load Dataset → Normalize
Input → Conv2D(32,3×3) → ReLU → MaxPool(2×2) → Flatten → Dense(128) → ReLU → Dense(10) → Softmax
Adam optimizer, Categorical Crossentropy, 10 epochs

Deep Network

Load Dataset → Normalize
Input → Flatten →
Dense(256) → ReLU → Dropout(0.3) →
Dense(128) → ReLU → Dropout(0.3) →
Dense(64) → ReLU →
Dense(10) → Softmax

🛠️ Development

Backend Development

cd backend
source venv/bin/activate
python main.py

Frontend Development

cd frontend
npm run dev

Build for Production

# Frontend
cd frontend
npm run build

# Backend
# Deploy FastAPI app using uvicorn, gunicorn, or similar

📝 API Endpoints

REST Endpoints

• GET / - Health check
• POST /api/datasets/load - Load MNIST dataset
• POST /api/model/build - Build and validate model
• POST /api/train - Start training
• POST /api/chat - AI chat assistant
• POST /api/predict - Make predictions

WebSocket Events

• training_started - Training has begun
• epoch_end - Epoch complete with metrics
• training_complete - Training finished with test accuracy
• training_error - Error occurred

🐛 Troubleshooting

Backend Issues

• Port 8000 in use: Change port in main.py or kill the process using port 8000
• TensorFlow errors: Make sure TensorFlow is installed: pip install tensorflow
• Gemini API errors: Check that GEMINI_API_KEY is set correctly

Frontend Issues

• Cannot connect to backend: Ensure backend is running on port 8000
• Supabase errors: Check environment variables in frontend/.env
• Build errors: Delete node_modules and reinstall: rm -rf node_modules && npm install

Database Issues

• Authentication errors: Verify Supabase URL and anon key
• RLS policy errors: Make sure you ran supabase_schema.sql
• Project not saving: Check browser console for errors

🤝 Next Steps

Future areas for improvement:

1. More Blocks: Add LSTM, GRU, BatchNormalization, etc.
2. More Datasets: Support for CIFAR-10, Fashion-MNIST, etc.
3. Model Export: Export trained models in different formats
4. Templates: Pre-built example architectures
5. Documentation: Improve docs and add tutorials

📄 License

MIT License - feel free to use for educational purposes

🙏 Acknowledgments

• Inspired by Scratch's visual programming interface
• TensorFlow Playground for the educational approach
• Built for HackUMass 2025