How tuananhtrieu1305/workhub works
1. High-level shape
- WorkHub is a Dockerized monorepo with a Node.js backend and a React/Vite frontend.
- The root docker-compose.yml is the main orchestration boundary; the README explicitly says you run the whole stack with docker compose up and do not need Node installed on the host.
2. Backend responsibilities
- backend-node/src/app.js is the backend entrypoint.
- The backend is organized by concern: models, services, middlewares, presenters, views, utils, config, and scripts.
- This suggests an API-centric server with layered request handling rather than a single-controller style app.
3. Core backend data layer
- src/models covers the main business entities: users, organizations, projects, tasks, posts, comments, likes, documents, folders, chats, meetings, calls, notifications, and activity logs.
- The data model is clearly multi-domain and workspace-oriented, with organization membership/roles/invites as a central boundary.
4. Backend domain boundaries
- Identity & access: User, OrganizationMember, OrganizationRole, invite and preference models, plus authMiddleware and adminMiddleware.
- Work management: Project, Task, TaskAssignee, ChecklistItem.
- Social/feed: Post, Comment, Like, Reaction-related services.
- Docs: Document, Folder, DocumentShare, DocumentVersion.
- Realtime collaboration: Conversation, Message, Notification, Call, Meeting.
- Operations/admin: activity logs, admin stats, permission services.
5. Backend service layer
- services holds the business rules and side effects: permission checks, notification fan-out, presence tracking, OTP, file validation, upload/storage, activity logging, task events, and realtime meeting/call helpers.
- redisClient.js plus services like presenceService, callLockService, and rate limiting indicate Redis is used for ephemeral state and coordination, not just caching.
6. Uploads and storage
- File handling is split across multer, upload path config, upload middleware, file validation, and r2StorageService.
- That points to a hybrid storage flow: files may be accepted through the API, validated, stored locally in src/uploads during development, and likely pushed to object storage via R2 in production.
- Documents and attachments are first-class architecture elements, not incidental blobs.
7. Realtime architecture
- The backend has socketHandler.js and realtime-oriented services/utilities for conversations, presence, and meetings.
- The frontend has a dedicated SocketContext and chat-specific useChatSocket, so socket connections are a shared app-level channel for messaging, presence, and possibly notifications/call state.
- Realtime behavior is tested explicitly in backend-node/test/conversationRealtime.test.js.
8. Presentation and response shaping
- presenters and views are a strong signal that the backend separates domain objects from API response shapes.
- presenters likely normalize model data, while views define feature-specific payloads for auth, users, organizations, posts, tasks, documents, meetings, calls, chats, and admin.
- This is important for diagrams because the API layer is not a direct pass-through from models.
9. Frontend structure
- The frontend is feature-sliced under src/modules: auth, feed, chat, call, meeting, organization, and profile.
- Shared app scaffolding lives in components, context, routes, and styles.
- API access is centralized in src/api with a shared axiosClient, which is the main HTTP boundary to the backend.
10. Frontend state and interaction model
- AuthContext, SocketContext, and feature-local state files show a mix of global session state and module-specific UI state.
- Chat, feed, meeting, and call each have their own state helpers and interaction logic, which keeps real-time UI concerns close to the feature that owns them.
- The app shell uses route guards: ProtectedRoute, GuestRoute, and AdminRoute.
11. Major user-facing flows
- Auth flow: login/register/verify/reset password through the auth module and auth API.
- Workspace flow: organization pages manage membership, invites, roles, banners, dashboards, and notification settings.
- Collaboration flow: chat, calls, meetings, posts, comments, reactions, and documents all sit inside the organization/workspace context.
- Task flow: projects and tasks are separate but permissioned, with event and policy services on the backend.
12. External/system concerns that matter architecturally
- Docker is the deployment/runtime envelope for both frontend and backend.
- Redis is a meaningful infrastructure dependency for presence, locks, and rate limiting.
- Email is handled through a utility service, and tokens/OTP are part of auth flows.
- Tests focus on policy and realtime behavior, which suggests business rules are a key stability boundary.
13. How the pieces connect
- Frontend feature modules call their matching API wrappers.
- Requests hit backend middleware first, then route/view logic, then services/models, and finally presenters/views for the response.
- Realtime events flow through sockets rather than HTTP for chat/presence/call-related updates.
- File uploads travel through upload middleware and storage services before being referenced by documents, posts, or attachments.
14. Good diagram anchors
- Draw two top-level boxes: Frontend (React/Vite) and Backend API (Node).
- Under backend, group subsystems by domain: identity/org, collaboration, work management, docs, admin.
- Add side services/infrastructure: Redis, object storage (R2), email, and socket channel.
- Show Docker Compose as the deployment wrapper around both apps and their dependencies.
Main entry points: app.js Backend App · App.jsx Frontend App · socketHandler.js Socket Handler · axiosClient.js API Client
Components 26
Deployment
Containerized runtime boundary for the whole stack
- Docker Compose · Main runtime wrapper for frontend, backend, and dependencies
docker-compose.yml
Backend API
Node.js server, domain model layer, and API shaping
- Backend App · Node.js API entrypoint and server bootstrap
backend-node/src/app.js - Backend Config · Database, Redis, sockets, multer, and upload path setup
backend-node/src/config - Middleware · Auth, admin, rate limiting, and upload guards
backend-node/src/middlewares - Identity Models · Users, organizations, membership, roles, invites, preferences, and activity logs
backend-node/src/models - Work Models · Projects, tasks, assignees, and checklist items
backend-node/src/models - Collab Models · Posts, comments, likes, conversations, messages, calls, meetings, and notifications
backend-node/src/models - Docs Models · Folders, documents, shares, and versions
backend-node/src/models - Policy Services · Permissions, organization scope, and task/document access control
backend-node/src/services - Realtime Services · Presence, call locks, meeting helpers, and task event coordination
backend-node/src/services - Storage Services · File validation, upload handling, R2 storage, email, and OTP side effects
backend-node/src/services - Presenters & Views · Transforms models into API payloads for auth, users, orgs, posts, tasks, docs, meetings, calls, and admin
backend-node/src/presenters - Socket Handler · Shared websocket channel for chat, presence, calls, and notifications
backend-node/src/config/socketHandler.js
Frontend App
React/Vite client and feature modules
- Frontend App · React/Vite client bootstrap and app shell
frontend/src/App.jsx - API Client · Central axios client and feature API wrappers
frontend/src/api/axiosClient.js - App Contexts · Auth, socket, and shared session state
frontend/src/context - Auth Module · Login, register, verify email, and password reset flow
frontend/src/modules/auth - Chat Module · Conversation list, message timeline, polls, reminders, and socket sync
frontend/src/modules/chat - Feed Module · Posts, comments, reactions, and attachment handling
frontend/src/modules/feed - Call Module · Incoming/outgoing calls and call room experience
frontend/src/modules/call - Meeting Module · Meeting rooms, lobby, dock, and whiteboard controls
frontend/src/modules/meeting - Org Module · Workspace dashboard, membership, invites, roles, and settings
frontend/src/modules/organization - Route Guards · Protected, guest, and admin route boundaries
frontend/src/routes
Shared Infra
Cross-cutting runtime dependencies and coordination services
- Redis · Presence, locks, and rate limiting coordination
backend-node/src/config/redisClient.js - R2 Storage · Object storage target for uploads and attachments
backend-node/src/services/r2StorageService.js - Email Service · Password reset, verification, and invite notifications
backend-node/src/utils/sendEmail.js
Connections 33
- Docker Compose → Backend App: runs · Compose starts the backend container
- Docker Compose → Frontend App: runs · Compose starts the frontend container
- Backend App → Backend Config: boots with · App initializes runtime config and connections
- Backend App → Middleware: uses · Requests pass through auth, admin, rate limit, and upload guards
- Backend App → Socket Handler: opens · Backend exposes the websocket channel
- Backend App → Presenters & Views: responds with · API responses are shaped before leaving the server
- Backend App → Identity Models: reads · Identity, org, and preference entities
- Backend App → Work Models: reads · Project and task entities
- Backend App → Collab Models: reads · Collaboration and communication entities
- Backend App → Docs Models: reads · Document and folder entities
- Backend App → Policy Services: delegates to · Permission and scope decisions
- Backend App → Realtime Services: delegates to · Presence, locks, meeting, and task event coordination
- Backend App → Storage Services: delegates to · Upload, validation, email, and OTP side effects
- Backend Config → Redis: connects · Redis client is configured in backend runtime
- Realtime Services → Redis: uses · Realtime state and coordination depend on Redis
- Storage Services → R2 Storage: stores in · Files and attachments are pushed to object storage
- Storage Services → Email Service: sends via · Auth and workspace flows send email notifications
- Socket Handler → App Contexts: feeds · Shared socket state is consumed by the client
- Frontend App → API Client: calls · UI features use the shared HTTP client
- Frontend App → App Contexts: uses · Session and socket state live in app contexts
- Frontend App → Route Guards: navigates through · Route guards control access to pages
- Frontend App → Auth Module: loads · Auth screens are a dedicated feature slice
- Frontend App → Chat Module: loads · Chat is a dedicated collaboration slice
- Frontend App → Feed Module: loads · Feed and reactions are a dedicated slice
- Frontend App → Call Module: loads · Calling has its own runtime and UI slice
- Frontend App → Meeting Module: loads · Meetings and whiteboard controls are isolated
- Frontend App → Org Module: loads · Organization workspace screens and settings
- Chat Module → API Client: syncs over HTTP · Initial data and mutations go through API wrappers
- Chat Module → Socket Handler: syncs over sockets · Message, presence, and call-related updates use realtime sockets
- Feed Module → API Client: syncs over HTTP · Feed data and reactions are fetched and mutated through APIs
- Call Module → Socket Handler: syncs over sockets · Call state is coordinated through realtime events
- Meeting Module → Socket Handler: syncs over sockets · Meeting room state and events use realtime sockets
- Org Module → API Client: syncs over HTTP · Workspace administration uses API wrappers