WhiteFlow

A real-time collaborative whiteboard application with integrated games, chat, and productivity features. WhiteFlow enables teams to work together seamlessly with synchronized drawing, interactive games, and communication tools.

Features

🎨 Collaborative Whiteboard

Real-time synchronized drawing and annotations
Multiple users can draw simultaneously
Ghost cursor tracking to see where other users are working
Customizable user colors and themes

🎮 Interactive Games

Connect 4 - Classic strategy game for two players
Tic-Tac-Toe - Quick and fun game sessions
Rock-Paper-Scissors - Fast-paced decision making
Real-time game state synchronization
Server-authoritative seat management

💬 Real-time Chat

Live messaging within board rooms
Typing indicators
Chat history persistence (last 50 messages)
User presence indicators

⏱️ Pomodoro Timer

Synchronized Pomodoro timer across all users in a room
Auto-starts when first user joins
Phase tracking (work/break)
Real-time countdown synchronization

🏠 Room Management

Create custom rooms with unique codes
Join existing rooms via room code
Room-based collaboration spaces
User presence tracking with ghost mode (inactive users)

🔐 Authentication

Auth0 integration for secure user authentication
User profile management
Persistent user preferences (colors, themes)

Tech Stack

Backend

Node.js - Runtime environment
Express.js - Web framework
Socket.IO - Real-time bidirectional communication
Redis - Data persistence and caching
Auth0 - Authentication and user management
bcrypt - Password hashing

Frontend

Vanilla JavaScript - Core functionality
Tailwind CSS - Utility-first CSS framework
Interact.js - Drag and drop interactions
Font Awesome - Icon library

Prerequisites

Before you begin, ensure you have the following installed:

Node.js (v16 or higher)
npm (v7 or higher)
Redis server (local or cloud instance)

Installation

Clone the repository
```
git clone <repository-url>
cd WhiteFlow
```

Install dependencies

npm install
cd backend
npm install
cd ..

Set up environment variables

Create a .env file in the backend directory with the following variables:

# Auth0 Configuration
AUTH0_SECRET=your_auth0_secret_here
AUTH0_BASE_URL=http://localhost:3000
AUTH0_CLIENT_ID=your_auth0_client_id
AUTH0_DOMAIN=your_auth0_domain.auth0.com

# Redis Configuration
REDIS_HOST=your_redis_host
REDIS_USERNAME=your_redis_username
REDIS_PASSWORD=your_redis_password

Note: For local development, you can use a local Redis instance. Update REDIS_HOST to localhost and adjust the port in backend/redis.js if needed.

Configure Auth0
- Create an Auth0 account at auth0.com
- Create a new application (Single Page Application)
- Add http://localhost:3000 to allowed callback URLs, logout URLs, and web origins
- Copy your Client ID and Domain to the .env file
- Generate a secret for AUTH0_SECRET (can be any long random string)

Start Redis (if using locally)

# On macOS with Homebrew
brew services start redis

# On Linux
sudo systemctl start redis

# On Windows
# Use Redis for Windows or WSL

Start the server
```
npm start
```
The application will be available at http://localhost:3000

Project Structure

WhiteFlow/
├── backend/
│   ├── node_modules/
│   ├── redis.js              # Redis client configuration
│   ├── server.js             # Main Express server and Socket.IO setup
│   ├── show-redis-users.js   # Utility to view Redis users
│   ├── watch-redis.js        # Utility to monitor Redis
│   ├── package.json
│   └── .env                  # Environment variables (not in git)
├── src/
│   ├── mainapp.html          # Main SPA entry point
│   ├── mainJS.js             # Router and app initialization
│   ├── mainCSS.css           # Global styles
│   ├── Pages/                # Page templates
│   │   ├── homepage.html
│   │   ├── board.html
│   │   ├── chats.html
│   │   ├── login.html
│   │   ├── room.html
│   │   └── signin.html
│   ├── components/           # Reusable components
│   │   ├── navbar.html
│   │   └── chat.html
│   ├── javascript/           # Frontend scripts
│   │   ├── board.js          # Whiteboard functionality
│   │   ├── chat.js           # Chat functionality
│   │   ├── games.js          # Game logic
│   │   ├── homepage.js       # Homepage logic
│   │   ├── login.js          # Login handling
│   │   ├── navbar.js         # Navigation bar
│   │   ├── pomodoro.js       # Timer functionality
│   │   └── room.js           # Room management
│   └── css/                  # Stylesheets
│       ├── board.css
│       ├── chats.css
│       ├── homepage.css
│       ├── login.css
│       ├── navbar.css
│       ├── room.css
│       └── sign-in.css
├── package.json
└── README.md

Usage

Starting the Application

Ensure Redis is running
Start the server: npm start
Open your browser to http://localhost:3000
Sign in with Auth0 credentials

Creating a Room

Navigate to the Room page
Enter a room name
Optionally provide a custom room code
Click "Create Room"
Share the room code with others to collaborate

Joining a Room

Navigate to the Room page
Enter the room code
Click "Join Room"

Using the Whiteboard

Click and drag to draw
Your cursor position is visible to other users
Customize your color in profile settings
All drawings are synchronized in real-time

Playing Games

Navigate to a board room
Click on an available game (Connect 4, Tic-Tac-Toe, or Rock-Paper-Scissors)
Take a seat when prompted
Game state persists even if users disconnect and reconnect

Using Chat

Type messages in the chat panel
Messages are saved and visible to all users in the room
Typing indicators show when others are typing

Pomodoro Timer

Timer automatically starts when the first user joins a room
Timer is synchronized across all users
Use controls to pause, reset, or change phases

Available Scripts

Root Level

npm start - Start the Express server

Backend Directory

npm start - Start the server
npm run show-users - Display all users stored in Redis
npm run watch - Monitor Redis activity

Environment Variables

Variable	Description	Required
`AUTH0_SECRET`	Secret key for Auth0 session encryption	Yes
`AUTH0_BASE_URL`	Base URL of your application	Yes
`AUTH0_CLIENT_ID`	Auth0 application client ID	Yes
`AUTH0_DOMAIN`	Your Auth0 domain	Yes
`REDIS_HOST`	Redis server hostname	Yes
`REDIS_USERNAME`	Redis username	Yes
`REDIS_PASSWORD`	Redis password	Yes

Development

Architecture

WhiteFlow uses a Single Page Application (SPA) architecture:

Client-side routing handled by mainJS.js
Dynamic HTML injection for page navigation
Socket.IO for real-time features
Redis for persistent data storage

Key Features Implementation

Real-time Synchronization: All drawing, game moves, and chat messages are broadcast via Socket.IO
State Persistence: Game states, chat history, and user profiles are stored in Redis
Ghost Mode: Users become "ghosts" after 10 seconds of inactivity, visible to others but with reduced opacity
Server Authority: Game seat assignments are managed server-side to prevent race conditions

Troubleshooting

Redis Connection Issues

Ensure Redis is running: redis-cli ping should return PONG
Verify Redis credentials in .env
Check firewall settings if using a remote Redis instance

Auth0 Authentication Issues

Verify callback URLs are correctly configured in Auth0 dashboard
Ensure AUTH0_BASE_URL matches your application URL
Check that AUTH0_SECRET is set correctly

Socket.IO Connection Issues

Check browser console for connection errors
Verify CORS settings in server.js
Ensure the server is running on the expected port

Contributing

This project was created for a beginner web development team. Contributions are welcome! Please ensure:

Code follows existing style conventions
New features include appropriate error handling
Socket.IO events are properly documented

License

ISC

Team

Repository for Beginner Web Development Team - Beginning Oct. 14 2025 - About 12-13 members

Note: This application requires both Redis and Auth0 to function properly. Make sure both services are configured before running the application.

Name		Name	Last commit message	Last commit date
Latest commit History 169 Commits
backend		backend
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json

ryanlyn29/WhiteFlow

Folders and files

Latest commit

History

Repository files navigation