|
| 1 | +# 🙋♂️ Handstack |
| 2 | + |
| 3 | +**Digital hand raising for in-person meetings** |
| 4 | + |
| 5 | +Handstack is a mobile-friendly web application that brings the convenience of digital hand raising (like Google Meet) to in-person meetings. Perfect for classrooms, conferences, and any meeting where you need to manage speaking order efficiently. |
| 6 | + |
| 7 | +## ✨ Features |
| 8 | + |
| 9 | +- **Mobile-first design** - Works great on phones and tablets |
| 10 | +- **Real-time synchronization** - All participants see updates instantly |
| 11 | +- **Simple room system** - 4-character room codes (new rooms use unambiguous characters, but can join any alphanumeric code) |
| 12 | +- **Admin controls** - Meeting hosts can manage the queue |
| 13 | +- **Session persistence** - Automatically restores your session after page refresh |
| 14 | +- **Zero-cost hosting** - Runs on GitHub Pages for free |
| 15 | +- **No registration required** - Just enter your name and start |
| 16 | + |
| 17 | +## 📁 Project Structure |
| 18 | +``` |
| 19 | +handstack/ |
| 20 | +├── src/ |
| 21 | +│ ├── components/ # React components |
| 22 | +│ │ ├── Home.jsx # Landing page |
| 23 | +│ │ ├── CreateRoom.jsx # Room creation |
| 24 | +│ │ ├── JoinRoom.jsx # Room joining |
| 25 | +│ │ ├── AdminRoom.jsx # Admin dashboard |
| 26 | +│ │ └── UserRoom.jsx # User interface |
| 27 | +│ ├── services/ # Firebase services |
| 28 | +│ │ └── firebase.js # Database operations |
| 29 | +│ ├── utils/ # Utility functions |
| 30 | +│ │ └── roomCode.js # Room code generation |
| 31 | +│ ├── firebase/ # Firebase config |
| 32 | +│ │ └── config.js # Firebase setup |
| 33 | +│ └── App.jsx # Main app component |
| 34 | +├── .github/workflows/ # GitHub Actions |
| 35 | +│ └── deploy.yml # Auto-deployment |
| 36 | +└── README.md # Full documentation |
| 37 | +``` |
| 38 | + |
| 39 | +## 🔧 Quick Start Guide |
| 40 | + |
| 41 | +### 1. Fork and Clone the Repository |
| 42 | + |
| 43 | +```bash |
| 44 | +git clone https://github.com/petecheslock/handstack.git |
| 45 | +cd handstack |
| 46 | +``` |
| 47 | + |
| 48 | +### 2. Install Dependencies |
| 49 | + |
| 50 | +```bash |
| 51 | +npm install |
| 52 | +``` |
| 53 | + |
| 54 | +### 3. Firebase Configuration |
| 55 | + |
| 56 | +1. Go to [Firebase Console](https://console.firebase.google.com/) |
| 57 | +2. Create a new project (or use an existing one) |
| 58 | +3. **Create a Web App** (This step is crucial!): |
| 59 | + - Click the **⚙️ Settings** icon next to "Project Overview" |
| 60 | + - Select **Project Settings** |
| 61 | + - Scroll down to "Your apps" section |
| 62 | + - Click **Add app** and select the **Web** icon `</>` |
| 63 | + - Enter app nickname (e.g., "Handstack") |
| 64 | + - Click **Register app** |
| 65 | +4. **Enable Realtime Database**: |
| 66 | + - Go to **Build** → **Realtime Database** |
| 67 | + - Click **Create Database** |
| 68 | + - Choose **Start in test mode** |
| 69 | + - Select your preferred location |
| 70 | +5. **Set database rules** (in Realtime Database → Rules tab): |
| 71 | + ```json |
| 72 | + { |
| 73 | + "rules": { |
| 74 | + "rooms": { |
| 75 | + "$roomCode": { |
| 76 | + ".read": true, |
| 77 | + ".write": true |
| 78 | + } |
| 79 | + } |
| 80 | + } |
| 81 | + } |
| 82 | + ``` |
| 83 | +6. **Get your Firebase config** from the web app you created: |
| 84 | + - Go to Project Settings → General tab |
| 85 | + - Scroll to "Your apps" and click on your web app |
| 86 | + - Copy the config object values |
| 87 | +7. **Create a `.env` file** in the root directory (copy from `env.example`): |
| 88 | + ```bash |
| 89 | + cp env.example .env |
| 90 | + ``` |
| 91 | +8. **Fill in your Firebase configuration** in `.env`: |
| 92 | + ```bash |
| 93 | + VITE_FIREBASE_API_KEY=AIzaSyC... # From firebaseConfig.apiKey |
| 94 | + VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com |
| 95 | + VITE_FIREBASE_DATABASE_URL=https://your-project-default-rtdb.firebaseio.com/ |
| 96 | + VITE_FIREBASE_PROJECT_ID=your-project-id |
| 97 | + VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com |
| 98 | + VITE_FIREBASE_MESSAGING_SENDER_ID=123456789 |
| 99 | + VITE_FIREBASE_APP_ID=1:123456789:web:abc123def456 |
| 100 | + ``` |
| 101 | + |
| 102 | + **⚠️ Important**: The `.env` file is automatically ignored by Git for security. Never commit your Firebase credentials to the repository. |
| 103 | + |
| 104 | +### 4. Update GitHub Pages Configuration |
| 105 | + |
| 106 | +1. Update `package.json` homepage field to match your GitHub username: |
| 107 | + ```json |
| 108 | + "homepage": "https://yourgithubuser.github.io" |
| 109 | + ``` |
| 110 | + |
| 111 | +2. In your GitHub repository settings: |
| 112 | + - Go to **Settings** → **Pages** |
| 113 | + - Set **Source** to "Deploy from a branch" |
| 114 | + - Set **Branch** to "main" and **Folder** to "/ (root)" |
| 115 | + |
| 116 | + **Note**: This configuration serves from your main GitHub Pages domain (`petecheslock.github.io`). If you want to serve from a subdirectory like `/handstack`, you can create a repository named `handstack` and it will be available at `petecheslock.github.io/handstack`. |
| 117 | + |
| 118 | +### 5. Test Locally |
| 119 | + |
| 120 | +```bash |
| 121 | +npm run dev |
| 122 | +``` |
| 123 | + |
| 124 | +Visit `http://localhost:5173` to test the application. You should see the Handstack home page with "Create Room" and "Join Room" buttons. |
| 125 | + |
| 126 | +**Testing the Full Flow:** |
| 127 | +1. Create a room with your name |
| 128 | +2. Note the 4-character room code |
| 129 | +3. Open a new browser tab/window and join the room with the code |
| 130 | +4. Test raising/lowering hands and queue management |
| 131 | + |
| 132 | +## 🚀 Deployment to GitHub Pages |
| 133 | + |
| 134 | +### GitHub Secrets Configuration |
| 135 | + |
| 136 | +Before deploying, you need to add your Firebase configuration as GitHub Secrets: |
| 137 | + |
| 138 | +1. Go to your GitHub repository Settings > Secrets and variables > Actions |
| 139 | +2. Add the following secrets with your Firebase config values: |
| 140 | + - `VITE_FIREBASE_API_KEY` |
| 141 | + - `VITE_FIREBASE_AUTH_DOMAIN` |
| 142 | + - `VITE_FIREBASE_DATABASE_URL` |
| 143 | + - `VITE_FIREBASE_PROJECT_ID` |
| 144 | + - `VITE_FIREBASE_STORAGE_BUCKET` |
| 145 | + - `VITE_FIREBASE_MESSAGING_SENDER_ID` |
| 146 | + - `VITE_FIREBASE_APP_ID` |
| 147 | + |
| 148 | +### Option 1: Automatic Deployment (Recommended) |
| 149 | + |
| 150 | +1. Push your code to GitHub |
| 151 | +2. Go to your repository Settings > Pages |
| 152 | +3. Choose "GitHub Actions" as the source |
| 153 | +4. The workflow in `.github/workflows/deploy.yml` will automatically deploy on push to main |
| 154 | +5. Your app will be available at `https://petecheslock.github.io` |
| 155 | + |
| 156 | +### Option 2: Manual Deployment |
| 157 | + |
| 158 | +```bash |
| 159 | +npm run build |
| 160 | +npm run deploy |
| 161 | +``` |
| 162 | + |
| 163 | +## 📱 How to Use |
| 164 | + |
| 165 | +### For Meeting Hosts (Admins) |
| 166 | + |
| 167 | +1. Click "Create Room" |
| 168 | +2. Enter your name |
| 169 | +3. Share the 4-character room code with participants |
| 170 | +4. Monitor the queue and click "Done Speaking" to remove people |
| 171 | +5. See all participants and their hand status |
| 172 | + |
| 173 | +### For Participants |
| 174 | + |
| 175 | +1. Click "Join Room" |
| 176 | +2. Enter the room code and your name |
| 177 | +3. Use "Raise Hand" when you want to speak |
| 178 | +4. See your position in the queue |
| 179 | +5. Use "Lower Hand" when you're done |
| 180 | + |
| 181 | +## 🛠️ Technical Stack |
| 182 | + |
| 183 | +- **Frontend**: React 18 + Vite |
| 184 | +- **Styling**: Tailwind CSS |
| 185 | +- **Database**: Firebase Realtime Database |
| 186 | +- **Hosting**: GitHub Pages |
| 187 | +- **Routing**: React Router |
| 188 | + |
| 189 | +## 📈 Scaling Considerations |
| 190 | + |
| 191 | +The free Firebase Realtime Database tier includes: |
| 192 | +- 1GB storage |
| 193 | +- 10GB/month transfer |
| 194 | +- 100 concurrent connections |
| 195 | + |
| 196 | +This should handle hundreds of concurrent users across multiple rooms. |
| 197 | + |
| 198 | +## 🤝 Contributing |
| 199 | + |
| 200 | +1. Fork the repository |
| 201 | +2. Create a feature branch |
| 202 | +3. Make your changes |
| 203 | +4. Submit a pull request |
| 204 | + |
| 205 | +## 📄 License |
| 206 | + |
| 207 | +MIT License - feel free to use this for your meetings! |
| 208 | + |
| 209 | +## 🐛 Troubleshooting |
| 210 | + |
| 211 | +### Common Issues |
| 212 | + |
| 213 | +1. **Firebase connection errors**: |
| 214 | + - Verify your `.env` file has all required `VITE_FIREBASE_*` variables |
| 215 | + - Check that Realtime Database is enabled in your Firebase project |
| 216 | + - Ensure database rules allow read/write access to `rooms` |
| 217 | + |
| 218 | +2. **Deployment issues**: |
| 219 | + - Verify all GitHub Secrets are added to your repository |
| 220 | + - Check that your GitHub Pages settings use "GitHub Actions" as source |
| 221 | + |
| 222 | +3. **Room not found**: Ensure the room code is correct (4 alphanumeric characters). |
| 223 | + |
| 224 | +4. **Environment variable errors**: |
| 225 | + - Local development: Check your `.env` file |
| 226 | + - Deployment: Check your GitHub repository secrets |
| 227 | + |
| 228 | +**Need Help?** Create an issue on GitHub if you encounter problems or have suggestions for improvements. |
| 229 | + |
| 230 | +--- |
| 231 | + |
| 232 | +## 🎉 Ready to Use! |
| 233 | + |
| 234 | +Once you complete the Firebase setup, your Handstack will be ready to host on GitHub Pages at zero cost. The application will handle multiple concurrent rooms and real-time updates seamlessly. |
| 235 | + |
| 236 | +**Perfect for**: Classrooms, conferences, team meetings, workshops, and any event where you need organized hand raising! |
| 237 | + |
| 238 | +--- |
| 239 | + |
| 240 | +**Made with ❤️ for better meetings** |
0 commit comments