Flux Board

Flux Board is a full-stack collaborative canvas app with real-time multi-user editing, Clerk authentication, and MongoDB persistence.

This repository contains both:

• Backend API + Socket.IO server
• Frontend React application

Tech Stack

Frontend

• React 19
• Vite
• React Router
• Clerk (client auth)
• React Flow
• Zustand
• Socket.IO client
• Tailwind CSS

Backend

• Node.js + Express
• Socket.IO
• Clerk (server auth)
• MongoDB + Mongoose
• Helmet + rate limiting + CORS hardening
• Cloudinary (thumbnail uploads)

Repository Structure

• backend: Express API, Socket.IO, MongoDB models/controllers/routes
• frontend: React app and canvas UI

Prerequisites

• Node.js 18+ (recommended 20+)
• npm 9+
• MongoDB Atlas (or compatible MongoDB)
• Clerk app (publishable + secret keys)
• Cloudinary account (for production thumbnail storage)

Quick Start (Local Development)

1) Install dependencies

Backend:

cd backend
npm install

Frontend:

cd frontend
npm install

2) Configure environment variables

Backend:

cd backend
cp .env.example .env

Frontend:

cd frontend
cp .env.example .env

If you are on Windows PowerShell and cp is not available:

Copy-Item .env.example .env

3) Fill required values

Backend required values:

• MONGODB_URI
• CLERK_SECRET_KEY
• CLOUDINARY_CLOUD_NAME
• CLOUDINARY_API_KEY
• CLOUDINARY_API_SECRET

Frontend required values:

• VITE_API_BASE_URL
• VITE_CLERK_PUBLISHABLE_KEY

4) Run the app

Run backend in terminal 1:

cd backend
npm run dev

Run frontend in terminal 2:

cd frontend
npm run dev

Open:

• Frontend: http://localhost:5173
• Backend health: http://localhost:5000/api/health

Scripts

Backend

• npm run dev: start with nodemon
• npm start: production start

Frontend

• npm run dev: start Vite dev server
• npm run build: production build
• npm run preview: preview built app
• npm run lint: run ESLint

API Endpoints

All routes are under /api and require auth unless dev bypass is enabled in development.

Health

• GET /api/health

Users

• POST /api/users
• GET /api/users/me
• GET /api/users/search
• GET /api/users/:userId
• PUT /api/users/:userId
• DELETE /api/users/:userId

Boards

• POST /api/boards
• GET /api/boards/user/all
• GET /api/boards/shared/:collaborationId
• GET /api/boards/:boardId
• PUT /api/boards/:boardId
• DELETE /api/boards/:boardId
• PUT /api/boards/:boardId/thumbnail
• POST /api/boards/collaborator/add
• POST /api/boards/collaborator/remove

Collaboration Sessions

• GET /api/collaboration/:boardId/sessions
• PUT /api/collaboration/:sessionId/end

Activity

• GET /api/activity/:boardId
• POST /api/activity

Realtime Collaboration (Socket.IO)

Socket server runs on the backend host.

High-level flow

1. Client authenticates socket with Clerk token (or guarded dev bypass headers in development).
2. Client emits join_board.
3. Backend verifies board access and creates/updates active collaboration session.
4. Presence is emitted with presence_updated.
5. Canvas/cursor events are broadcast to other collaborators in the same board room.

Main events

Client emits:

• join_board
• leave_board
• canvas_state_updated
• cursor_moved
• node_added, node_updated, node_deleted, node_moved
• edge_added, edge_deleted

Server emits:

• presence_updated
• canvas_state_updated
• collaborator_cursor
• user_joined
• user_left
• collaboration_error

Environment Variables

Backend (.env)

Runtime:

• NODE_ENV (development or production)
• PORT
• HOST
• PUBLIC_BASE_URL

Database:

• MONGODB_URI
• DB_NAME
• DNS_FALLBACK_SERVERS

Security and network:

• CORS_ORIGINS
• SOCKET_CORS_ORIGINS
• TRUST_PROXY
• JSON_BODY_LIMIT
• RATE_LIMIT_WINDOW_MS
• RATE_LIMIT_MAX_REQUESTS

Clerk:

• CLERK_SECRET_KEY
• CLERK_PUBLISHABLE_KEY
• CLERK_JWT_KEY (optional)
• CLERK_AUTHORIZED_PARTIES (recommended in production)

Cloudinary:

• CLOUDINARY_CLOUD_NAME
• CLOUDINARY_API_KEY
• CLOUDINARY_API_SECRET

Development-only bypass:

• ALLOW_DEV_AUTH_BYPASS
• DEV_AUTH_SHARED_SECRET

Frontend (.env)

• VITE_API_BASE_URL (must include /api)
• VITE_SOCKET_URL (optional if same origin as API)
• VITE_CLERK_PUBLISHABLE_KEY

Development-only bypass:

• VITE_USE_DEV_AUTH_BYPASS
• VITE_DEV_CLERK_ID
• VITE_DEV_EMAIL
• VITE_DEV_NAME
• VITE_DEV_AVATAR
• VITE_DEV_AUTH_SHARED_SECRET

Production Deployment Checklist

1. Set NODE_ENV=production on backend.
2. Keep ALLOW_DEV_AUTH_BYPASS=false in production.
3. Set strict CORS_ORIGINS and SOCKET_CORS_ORIGINS to your real frontend domain.
4. Configure CLERK_AUTHORIZED_PARTIES to your frontend origin.
5. Use HTTPS for both frontend and backend.
6. Enable TRUST_PROXY if behind reverse proxy/load balancer.
7. Provide production Cloudinary credentials.
8. Build frontend with npm run build and deploy static output.
9. Start backend with npm start.
10. Verify:

• /api/health
• login flow
• board CRUD
• realtime presence and cursor sync

Troubleshooting

Backend crashes with EADDRINUSE on port 5000

Another process is already using the port. Stop stale node processes and restart backend.

Collaboration shows 0 People

• Verify backend is running and socket auth is successful.
• Ensure both tabs are on the same board.
• Ensure Clerk session is valid and not expired.
• Check backend logs for Socket authentication failed messages.

Socket authentication failed: JWT is expired

Refresh the client session (hard refresh/sign in again). The client now requests fresh tokens at connection time.

CORS errors in browser console

Confirm CORS_ORIGINS and SOCKET_CORS_ORIGINS include the exact frontend origin.

Frontend starts on 5174 instead of 5173

Port 5173 is already in use; this is normal Vite behavior. Use the printed local URL.

Security Notes

• Dev auth bypass is for local development only.
• Never expose dev bypass env variables in production.
• Keep Clerk and Cloudinary secrets server-side only.
• Do not commit .env files.

License

ISC