# aditya726/teamsketch architecture

> Architecture diagram of the GitHub repository aditya726/teamsketch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aditya726/teamsketch
- Repository: https://github.com/aditya726/teamsketch

## Overview

#### Purpose and runtime topology
TeamSketch is a collaborative whiteboarding system with room-based drawing, text chat, voice chat, and authenticated access. It runs as three processes: a React/Vite browser client, an Express API server, and a separate Socket.IO whiteboard synchronization server. Deployment automation is defined in `.github/workflows/deploy.yml`.

#### Frontend application shell
The React TypeScript client bootstraps from `frontend/src/main.tsx` and composes routing/UI in `frontend/src/App.tsx`. Page-level flows cover landing, credential/OAuth completion, registration, and user profile at `frontend/src/pages/LandingPage.tsx`, `frontend/src/pages/AuthSuccess.tsx`, and `frontend/src/pages/UserProfile.tsx`. Vite serves the client and injects API/socket URLs through environment configuration.

#### Authentication and client state boundary
Authentication is owned by the API and exposed through `backend/src/routes/authRoutes.js` and `backend/src/controllers/authController.js`. Passport configuration supports Google OAuth in `backend/src/config/passport.js`; JWT-based protection is enforced by `backend/src/middleware/authMiddleware.js`. The browser persists/consumes auth state through Zustand in `frontend/src/store/useAuthStore.ts`, separating session state from feature components.

#### Core REST API and persistence
The main Express entry point is `backend/src/app.js`. It initializes API routes, database, middleware, and Swagger documentation. MongoDB/Mongoose persistence is configured in `backend/src/config/database.js`, with user identity modeled by `backend/src/models/User.js`. Room creation/joining is handled across `backend/src/routes/roomRoutes.js` and `backend/src/controllers/roomController.js`; frontend callers are centralized in `frontend/src/services/roomApi.ts`.

#### Real-time whiteboard subsystem
Whiteboard synchronization is intentionally isolated from the REST server in `backend/src/whiteboardServer.js`. Socket event behavior resides in `backend/src/socket/whiteboardSocket.js`, allowing room-scoped canvas updates to flow independently of HTTP requests. The interactive Fabric.js client canvas is `frontend/src/components/Whiteboard.tsx`, with shared drawing/event types in `frontend/src/types/whiteboard.types.ts`. The client connects using the dedicated socket-server URL rather than the API base URL.

#### Collaboration features
The room experience layers communication beside the canvas: `frontend/src/components/RoomChat.tsx` provides real-time text chat, while `frontend/src/components/RoomVoiceChat.tsx` handles room voice interaction. These components are feature boundaries around the central room/whiteboard context rather than API entry points.

#### External infrastructure and service contracts
MongoDB stores application/user data; Redis is configured through `backend/src/config/redis.js` for caching and/or Socket.IO-scale pub/sub responsibilities. Google Cloud OAuth is an optional external identity provider. Swagger is configured in `backend/src/config/swagger.js` and exposed by the Express API. Browser-to-server boundaries are: HTTP API via `frontend/src/services/api.ts`, authenticated API calls via JWT, and live collaborative events via Socket.IO.

Main entry points: [`frontend/src/App.tsx`](https://github.com/aditya726/teamsketch/blob/main/frontend/src/App.tsx) (App shell & routes), [`backend/src/app.js`](https://github.com/aditya726/teamsketch/blob/main/backend/src/app.js) (Express API), [`backend/src/whiteboardServer.js`](https://github.com/aditya726/teamsketch/blob/main/backend/src/whiteboardServer.js) (Socket.IO server), [`.github/workflows/deploy.yml`](https://github.com/aditya726/teamsketch/blob/main/.github/workflows/deploy.yml) (Deployment workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser client"]
  node_client_bootstrap["React/Vite bootstrap<br/>frontend entry<br/>[main.tsx]"]
  node_app_shell["App shell &amp; routes<br/>React application<br/>[App.tsx]"]
  node_auth_pages["Auth and profile pages<br/>page flows<br/>[LandingPage.tsx]"]
  node_auth_store["Auth state<br/>Zustand store<br/>[useAuthStore.ts]"]
  node_http_client["HTTP API client<br/>frontend service<br/>[api.ts]"]
  node_room_api["Room API client<br/>frontend service<br/>[roomApi.ts]"]
  node_whiteboard["Fabric.js canvas<br/>whiteboard UI<br/>[Whiteboard.tsx]"]
  node_room_chat["Room text chat<br/>collaboration UI<br/>[RoomChat.tsx]"]
  node_room_voice["Room voice chat<br/>collaboration UI<br/>[RoomVoiceChat.tsx]"]
end

subgraph group_api["REST API"]
  node_express_app["Express API<br/>server entry<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>API routes<br/>[authRoutes.js]"]
  node_auth_controller["Auth controller<br/>authentication logic<br/>[authController.js]"]
  node_passport["Google OAuth<br/>Passport config<br/>[passport.js]"]
  node_jwt_guard["JWT protection<br/>auth middleware<br/>[authMiddleware.js]"]
  node_room_routes["Room routes &amp; controller<br/>room API<br/>[roomRoutes.js]"]
  node_swagger["Swagger docs<br/>API contract<br/>[swagger.js]"]
end

subgraph group_realtime["Whiteboard sync"]
  node_whiteboard_server["Socket.IO server<br/>realtime server entry"]
  node_socket_events["Room canvas events<br/>Socket.IO handlers"]
end

subgraph group_infra["Infrastructure"]
  node_mongodb[("MongoDB / User model<br/>application persistence<br/>[User.js]")]
  node_redis[("Redis<br/>cache / Socket.IO pub-sub<br/>[redis.js]")]
  node_google(("Google<br/>OAuth provider"))
  node_deploy["Deployment workflow<br/>CI/CD<br/>[deploy.yml]"]
end

node_client_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"routes to"| node_auth_pages
node_auth_pages -->|"updates session"| node_auth_store
node_app_shell -->|"uses"| node_room_api
node_room_api -->|"uses"| node_http_client
node_http_client -->|"HTTP + JWT"| node_express_app
node_app_shell -->|"hosts room canvas"| node_whiteboard
node_app_shell -->|"hosts"| node_room_chat
node_app_shell -->|"hosts"| node_room_voice
node_whiteboard -->|"Socket.IO events"| node_whiteboard_server
node_room_chat -->|"room events"| node_whiteboard_server
node_room_voice -->|"room interaction"| node_whiteboard_server
node_whiteboard_server -->|"registers"| node_socket_events
node_socket_events -.->|"scales via pub/sub"| node_redis
node_express_app -->|"mounts"| node_auth_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"uses OAuth strategy"| node_passport
node_passport -->|"OAuth"| node_google
node_express_app -->|"protects routes"| node_jwt_guard
node_express_app -->|"mounts"| node_room_routes
node_auth_controller -->|"reads/writes users"| node_mongodb
node_room_routes -->|"persists room access"| node_mongodb
node_express_app -->|"serves documentation"| node_swagger
node_deploy -.->|"deploys client"| node_client_bootstrap
node_deploy -.->|"deploys API"| node_express_app
node_deploy -.->|"deploys sync server"| node_whiteboard_server

click node_client_bootstrap "https://github.com/aditya726/teamsketch/blob/main/frontend/src/main.tsx"
click node_app_shell "https://github.com/aditya726/teamsketch/blob/main/frontend/src/App.tsx"
click node_auth_pages "https://github.com/aditya726/teamsketch/blob/main/frontend/src/pages/LandingPage.tsx"
click node_auth_store "https://github.com/aditya726/teamsketch/blob/main/frontend/src/store/useAuthStore.ts"
click node_http_client "https://github.com/aditya726/teamsketch/blob/main/frontend/src/services/api.ts"
click node_room_api "https://github.com/aditya726/teamsketch/blob/main/frontend/src/services/roomApi.ts"
click node_whiteboard "https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/Whiteboard.tsx"
click node_room_chat "https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/RoomChat.tsx"
click node_room_voice "https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/RoomVoiceChat.tsx"
click node_express_app "https://github.com/aditya726/teamsketch/blob/main/backend/src/app.js"
click node_auth_routes "https://github.com/aditya726/teamsketch/blob/main/backend/src/routes/authRoutes.js"
click node_auth_controller "https://github.com/aditya726/teamsketch/blob/main/backend/src/controllers/authController.js"
click node_passport "https://github.com/aditya726/teamsketch/blob/main/backend/src/config/passport.js"
click node_jwt_guard "https://github.com/aditya726/teamsketch/blob/main/backend/src/middleware/authMiddleware.js"
click node_room_routes "https://github.com/aditya726/teamsketch/blob/main/backend/src/routes/roomRoutes.js"
click node_whiteboard_server "https://github.com/aditya726/teamsketch/blob/main/backend/src/whiteboardServer.js"
click node_socket_events "https://github.com/aditya726/teamsketch/blob/main/backend/src/socket/whiteboardSocket.js"
click node_mongodb "https://github.com/aditya726/teamsketch/blob/main/backend/src/models/User.js"
click node_redis "https://github.com/aditya726/teamsketch/blob/main/backend/src/config/redis.js"
click node_swagger "https://github.com/aditya726/teamsketch/blob/main/backend/src/config/swagger.js"
click node_deploy "https://github.com/aditya726/teamsketch/blob/main/.github/workflows/deploy.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client_bootstrap,node_app_shell,node_auth_pages,node_auth_store,node_http_client,node_room_api,node_whiteboard,node_room_chat,node_room_voice toneBlue
class node_express_app,node_auth_routes,node_auth_controller,node_passport,node_jwt_guard,node_room_routes,node_swagger toneAmber
class node_whiteboard_server,node_socket_events toneMint
class node_mongodb,node_redis,node_google,node_deploy toneRose
```

## Components

### Browser client

- [React/Vite bootstrap](https://github.com/aditya726/teamsketch/blob/main/frontend/src/main.tsx): frontend entry · `frontend/src/main.tsx`
- [App shell & routes](https://github.com/aditya726/teamsketch/blob/main/frontend/src/App.tsx): React application · `frontend/src/App.tsx`
- [Auth and profile pages](https://github.com/aditya726/teamsketch/blob/main/frontend/src/pages/LandingPage.tsx): page flows · Landing, OAuth completion, registration, and profile flows. · `frontend/src/pages/LandingPage.tsx`
- [Auth state](https://github.com/aditya726/teamsketch/blob/main/frontend/src/store/useAuthStore.ts): Zustand store · Persists browser session state separately from feature components. · `frontend/src/store/useAuthStore.ts`
- [HTTP API client](https://github.com/aditya726/teamsketch/blob/main/frontend/src/services/api.ts): frontend service · `frontend/src/services/api.ts`
- [Room API client](https://github.com/aditya726/teamsketch/blob/main/frontend/src/services/roomApi.ts): frontend service · `frontend/src/services/roomApi.ts`
- [Fabric.js canvas](https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/Whiteboard.tsx): whiteboard UI · `frontend/src/components/Whiteboard.tsx`
- [Room text chat](https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/RoomChat.tsx): collaboration UI · `frontend/src/components/RoomChat.tsx`
- [Room voice chat](https://github.com/aditya726/teamsketch/blob/main/frontend/src/components/RoomVoiceChat.tsx): collaboration UI · `frontend/src/components/RoomVoiceChat.tsx`

### REST API

- [Express API](https://github.com/aditya726/teamsketch/blob/main/backend/src/app.js): server entry · Initializes middleware, routes, database, and Swagger. · `backend/src/app.js`
- [Auth routes](https://github.com/aditya726/teamsketch/blob/main/backend/src/routes/authRoutes.js): API routes · `backend/src/routes/authRoutes.js`
- [Auth controller](https://github.com/aditya726/teamsketch/blob/main/backend/src/controllers/authController.js): authentication logic · `backend/src/controllers/authController.js`
- [Google OAuth](https://github.com/aditya726/teamsketch/blob/main/backend/src/config/passport.js): Passport config · `backend/src/config/passport.js`
- [JWT protection](https://github.com/aditya726/teamsketch/blob/main/backend/src/middleware/authMiddleware.js): auth middleware · `backend/src/middleware/authMiddleware.js`
- [Room routes & controller](https://github.com/aditya726/teamsketch/blob/main/backend/src/routes/roomRoutes.js): room API · Creates and joins rooms. · `backend/src/routes/roomRoutes.js`
- [Swagger docs](https://github.com/aditya726/teamsketch/blob/main/backend/src/config/swagger.js): API contract · `backend/src/config/swagger.js`

### Whiteboard sync

- [Socket.IO server](https://github.com/aditya726/teamsketch/blob/main/backend/src/whiteboardServer.js): realtime server entry · Runs independently from the REST API. · `backend/src/whiteboardServer.js`
- [Room canvas events](https://github.com/aditya726/teamsketch/blob/main/backend/src/socket/whiteboardSocket.js): Socket.IO handlers · Scopes drawing updates to rooms. · `backend/src/socket/whiteboardSocket.js`

### Infrastructure

- [MongoDB / User model](https://github.com/aditya726/teamsketch/blob/main/backend/src/models/User.js): application persistence · Mongoose stores user identity and application data. · `backend/src/models/User.js`
- [Redis](https://github.com/aditya726/teamsketch/blob/main/backend/src/config/redis.js): cache / Socket.IO pub-sub · `backend/src/config/redis.js`
- **Google**: OAuth provider
- [Deployment workflow](https://github.com/aditya726/teamsketch/blob/main/.github/workflows/deploy.yml): CI/CD · `.github/workflows/deploy.yml`

## Connections

- React/Vite bootstrap → App shell & routes: mounts
- App shell & routes → Auth and profile pages: routes to
- Auth and profile pages → Auth state: updates session
- App shell & routes → Room API client: uses
- Room API client → HTTP API client: uses
- HTTP API client → Express API: HTTP + JWT
- App shell & routes → Fabric.js canvas: hosts room canvas
- App shell & routes → Room text chat: hosts
- App shell & routes → Room voice chat: hosts
- Fabric.js canvas → Socket.IO server: Socket.IO events
- Room text chat → Socket.IO server: room events
- Room voice chat → Socket.IO server: room interaction
- Socket.IO server → Room canvas events: registers
- Room canvas events → Redis: scales via pub/sub
- Express API → Auth routes: mounts
- Auth routes → Auth controller: dispatches
- Auth controller → Google OAuth: uses OAuth strategy
- Google OAuth → Google: OAuth
- Express API → JWT protection: protects routes
- Express API → Room routes & controller: mounts
- Auth controller → MongoDB / User model: reads/writes users
- Room routes & controller → MongoDB / User model: persists room access
- Express API → Swagger docs: serves documentation
- Deployment workflow → React/Vite bootstrap: deploys client
- Deployment workflow → Express API: deploys API
- Deployment workflow → Socket.IO server: deploys sync server