|
1 | | -# template |
2 | | -A Template Repository for OpenSpringFest (OSF) |
| 1 | +# 🎨 CollabCanvas |
| 2 | + |
| 3 | +### A Real-Time, Infinite Collaborative Whiteboard |
| 4 | + |
| 5 | +**CollabCanvas** is an open-source infinite canvas web app inspired by tools like [Excalidraw](https://excalidraw.com) and [Eraser.io](https://eraser.io). It enables users to draw, brainstorm, and collaborate in real-time with a focus on simplicity and performance. |
| 6 | + |
| 7 | +Born out of our **College Open Source Event**, this project serves as a practical guide to building real-time applications using **WebSockets**, **React**, and the **HTML Canvas API**. |
| 8 | + |
| 9 | +[](https://opensource.org/licenses/MIT) |
| 10 | +[](http://makeapullrequest.com) |
| 11 | +[](https://github.com/your-username/collab-canvas/graphs/contributors) |
| 12 | + |
| 13 | +--- |
| 14 | + |
| 15 | +## ✨ Core Features |
| 16 | + |
| 17 | +| Feature | Description | Status | |
| 18 | +| ------------------------- | --------------------------------------------------------------------------- | ---------- | |
| 19 | +| ✏️ **Freehand Drawing** | Smooth, responsive sketching on an infinite, pannable canvas. | 🗓️ Planned | |
| 20 | +| 🎨 **Color Palette** | Choose from a curated set of colors for your brush. | 🗓️ Planned | |
| 21 | +| 🖌️ **Stroke Control** | Adjust brush thickness for fine details or bold strokes. | 🗓️ Planned | |
| 22 | +| 👥 **Live Collaboration** | See cursors and drawings from other users in real-time. | 🗓️ Planned | |
| 23 | +| 🔗 **Shareable Rooms** | Create a private room and share the link to invite collaborators instantly. | 🗓️ Planned | |
| 24 | +| 🧽 **Eraser Tool** | Easily remove any part of your drawing. | 🗓️ Planned | |
| 25 | +| ⬛ **Shape Tools** | Draw perfect rectangles, circles, and lines. | 🗓️ Planned | |
| 26 | +| 💾 **Session Saving** | Save your canvas state to the server and resume your work later. | 🗓️ Planned | |
| 27 | +| 🔒 **Private Rooms** | Secure your sessions with a unique room code or password. | 🗓️ Planned | |
| 28 | + |
| 29 | +--- |
| 30 | + |
| 31 | +## 🧰 Tech Stack |
| 32 | + |
| 33 | +We chose a modern, scalable tech stack designed for real-time performance and a great developer experience. |
| 34 | + |
| 35 | +| Layer | Technology | Purpose | |
| 36 | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | |
| 37 | +| **Frontend** | **[React](https://reactjs.org/)**, **[Tailwind CSS](https://tailwindcss.com/)** & **[HTML Canvas API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Canvas_API)** | For a reactive UI, utility-first styling, and high-performance canvas rendering. | |
| 38 | +| **Backend** | **[Node.js](https://nodejs.org/)** & **[Express](https://expressjs.com/)** | To build a fast, non-blocking server-side API. | |
| 39 | +| **Real-Time Engine** | **[Socket.IO](https://socket.io/)** | For bidirectional, low-latency communication. | |
| 40 | +| **Database** | **[MongoDB](https://www.mongodb.com/)** | To store room data and user session information. | |
| 41 | +| **Deployment** | **[Vercel](https://vercel.com/)** / **[Render](https://render.com/)** | For seamless, continuous deployment. | |
| 42 | + |
| 43 | +--- |
| 44 | + |
| 45 | +## 🏛️ Architecture Overview |
| 46 | + |
| 47 | +CollabCanvas uses a classic client-server architecture, with Socket.IO acting as the real-time communication backbone. |
| 48 | + |
| 49 | +- **Client (React)**: Handles all rendering and user interaction. When a user draws, the client captures the canvas events, processes them, and emits a WebSocket event to the server with the drawing data. |
| 50 | +- **Server (Node.js/Express)**: Acts as the central hub. It manages user rooms and brokers messages. It does not handle any drawing logic itself. |
| 51 | +- **Socket.IO**: When a client sends a drawing event, the server receives it and broadcasts it to all _other_ clients in the same room. This ensures that everyone's canvas stays in sync. |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +## 📁 Folder Structure |
| 56 | + |
| 57 | +The project is organized as a monorepo with two main packages: `client` and `server`. |
| 58 | + |
| 59 | +``` |
| 60 | +collab-canvas/ |
| 61 | +├── client/ # Contains the React frontend application |
| 62 | +│ ├── public/ |
| 63 | +│ │ └── index.html # HTML template |
| 64 | +│ ├── src/ |
| 65 | +│ │ ├── components/ # Reusable React components (Canvas, Toolbar) |
| 66 | +│ │ ├── hooks/ # Custom hooks (e.g., useSocket) |
| 67 | +│ │ ├── pages/ # Main application pages (HomePage, RoomPage) |
| 68 | +│ │ ├── App.jsx # Main app component and routing |
| 69 | +│ │ └── index.js # Entry point for the React app |
| 70 | +│ └── package.json |
| 71 | +│ |
| 72 | +├── server/ # Contains the Node.js backend |
| 73 | +│ ├── models/ # Mongoose schemas (e.g., RoomModel.js) |
| 74 | +│ ├── sockets/ # Socket.IO event handlers and logic |
| 75 | +│ ├── index.js # Server entry point (sets up Express & Socket.IO) |
| 76 | +│ ├── .env # Environment variables |
| 77 | +│ └── package.json |
| 78 | +│ |
| 79 | +├── .gitignore |
| 80 | +├── https://www.google.com/search?q=LICENSE # MIT License file |
| 81 | +└── README.md # You are here! |
| 82 | +
|
| 83 | +``` |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +## 🚀 Getting Started |
| 88 | + |
| 89 | +Follow these steps to set up and run the project locally. |
| 90 | + |
| 91 | +### Prerequisites |
| 92 | + |
| 93 | +- [Node.js](https://nodejs.org/en/) (v16 or higher) |
| 94 | +- [npm](https://www.npmjs.com/) or [yarn](https://yarnpkg.com/) |
| 95 | +- [Git](https://git-scm.com/) |
| 96 | + |
| 97 | +### 1. Clone the Repository |
| 98 | + |
| 99 | +```bash |
| 100 | +git clone https://github.com/your-username/collab-canvas.git |
| 101 | +cd collab-canvas |
| 102 | +``` |
| 103 | + |
| 104 | +### 2. Install Dependencies |
| 105 | + |
| 106 | +Install dependencies for both the client and server. |
| 107 | + |
| 108 | +```bash |
| 109 | +# Install client dependencies |
| 110 | +cd client |
| 111 | +npm install |
| 112 | + |
| 113 | +# Install server dependencies |
| 114 | +cd ../server |
| 115 | +npm install |
| 116 | +``` |
| 117 | + |
| 118 | +### 3. Set Up Environment Variables |
| 119 | + |
| 120 | +Create a `.env` file in the `/server` directory and add the following: |
| 121 | + |
| 122 | +```env |
| 123 | +PORT=5000 |
| 124 | +MONGO_URI=your_mongodb_connection_string |
| 125 | +CORS_ORIGIN=http://localhost:3000 |
| 126 | +``` |
| 127 | + |
| 128 | +### 4. Run the Application |
| 129 | + |
| 130 | +You'll need two separate terminals to run the frontend and backend servers. |
| 131 | + |
| 132 | +**Terminal 1: Start the React Client** |
| 133 | + |
| 134 | +```bash |
| 135 | +cd client |
| 136 | +npm start |
| 137 | +``` |
| 138 | + |
| 139 | +**Terminal 2: Start the Node.js Server** |
| 140 | + |
| 141 | +```bash |
| 142 | +cd server |
| 143 | +npm run dev |
| 144 | +``` |
| 145 | + |
| 146 | +Your application should now be running at [http://localhost:3000](http://localhost:3000) 🎉 |
| 147 | + |
| 148 | +## 🗺️ Project Roadmap |
| 149 | + |
| 150 | +Our goal is to build a fully-featured collaborative tool. Here's what's on our radar: |
| 151 | + |
| 152 | +### Phase 1: Core Drawing MVP |
| 153 | + |
| 154 | +- [ ] Basic freehand drawing |
| 155 | +- [ ] Color and stroke size selection |
| 156 | +- [ ] Real-time broadcasting of drawing data |
| 157 | +- [ ] Room creation and joining |
| 158 | + |
| 159 | +### Phase 2: Enhanced Tools |
| 160 | + |
| 161 | +- [ ] Shape tools (rectangle, circle, line) |
| 162 | +- [ ] Text insertion tool |
| 163 | +- [ ] Pan and zoom on the infinite canvas |
| 164 | +- [ ] Export canvas as PNG/SVG |
| 165 | + |
| 166 | +### Phase 3: Collaboration & Persistence |
| 167 | + |
| 168 | +- [ ] User authentication (optional) |
| 169 | +- [ ] Save & load canvas history from the database |
| 170 | +- [ ] User cursor and name display |
| 171 | +- [ ] Undo/Redo functionality |
| 172 | + |
| 173 | +### Phase 4: Future Polish |
| 174 | + |
| 175 | +- [ ] Touch support for mobile devices |
| 176 | +- [ ] Performance optimizations for large drawings |
| 177 | +- [ ] Image and file uploads |
| 178 | + |
| 179 | +## 🤝 How to Contribute |
| 180 | + |
| 181 | +We ❤️ contributions from the community! Whether you're fixing a bug, adding a new feature, or improving our documentation, your help is welcome. |
| 182 | + |
| 183 | +**Steps to contribute:** |
| 184 | + |
| 185 | +1. **Fork the repository** |
| 186 | + Click the "Fork" button at the top right of the GitHub page. |
| 187 | + |
| 188 | +2. **Create a new branch** |
| 189 | + |
| 190 | + ```bash |
| 191 | + git checkout -b feature/your-feature-name |
| 192 | + ``` |
| 193 | + |
| 194 | +3. **Make your changes and commit them with a clear message** |
| 195 | + |
| 196 | + ```bash |
| 197 | + git commit -m "feat: Add shape drawing tool" |
| 198 | + ``` |
| 199 | + |
| 200 | +4. **Push your changes to your fork** |
| 201 | + |
| 202 | + ```bash |
| 203 | + git push origin feature/your-feature-name |
| 204 | + ``` |
| 205 | + |
| 206 | +5. **Create a Pull Request** |
| 207 | + Describe the changes you've made. Please include screenshots if the UI is affected. |
| 208 | +
|
| 209 | +For more details, check out our `CONTRIBUTING.md` guide. |
| 210 | +
|
| 211 | +--- |
| 212 | +
|
| 213 | +## 🎯 Project Purpose |
| 214 | +
|
| 215 | +This project was built for our College Open Source Event to: |
| 216 | +
|
| 217 | +- **Educate:** Provide a clear, real-world example of how collaborative web apps are built. |
| 218 | +- **Inspire:** Encourage students to dive into web development and open-source. |
| 219 | +- **Collaborate:** Foster teamwork and build a sense of community through code. |
| 220 | +
|
| 221 | +--- |
| 222 | +
|
| 223 | +## 📜 License |
| 224 | +
|
| 225 | +This project is licensed under the MIT License. See the LICENSE file for details. |
| 226 | +
|
| 227 | +> "Collaboration is the canvas where creativity paints its best ideas." 🖌️ |
| 228 | +
|
| 229 | +Made with ❤️ by the open-source community. |
0 commit comments