# tuananhtrieu1305/workhub architecture

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

- Interactive diagram: https://gitdiagram.com/tuananhtrieu1305/workhub
- Repository: https://github.com/tuananhtrieu1305/workhub

## Overview

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: [`backend-node/src/app.js`](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/app.js) (Backend App), [`frontend/src/App.jsx`](https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/App.jsx) (Frontend App), [`backend-node/src/config/socketHandler.js`](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/config/socketHandler.js) (Socket Handler), [`frontend/src/api/axiosClient.js`](https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/api/axiosClient.js) (API Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_deployment["Deployment"]
  node_docker_compose[("Docker Compose<br/>orchestration<br/>[docker-compose.yml]")]
end

subgraph group_backend["Backend API"]
  node_backend_app["Backend App<br/>node entrypoint<br/>[app.js]"]
  node_backend_config["Backend Config<br/>runtime config"]
  node_backend_middleware["Middleware<br/>request guards"]
  node_backend_models_identity[("Identity Models<br/>domain models")]
  node_backend_models_work[("Work Models<br/>domain models")]
  node_backend_models_collab[("Collab Models<br/>domain models")]
  node_backend_models_docs[("Docs Models<br/>domain models")]
  node_backend_services_policy["Policy Services<br/>business rules"]
  node_backend_services_realtime["Realtime Services<br/>coordination"]
  node_backend_services_storage["Storage Services<br/>file pipeline"]
  node_backend_presenters_views["Presenters & Views<br/>response shaping"]
  node_backend_socket(("Socket Handler<br/>realtime gateway<br/>[socketHandler.js]"))
end

subgraph group_frontend["Frontend App"]
  node_frontend_app["Frontend App<br/>react entrypoint<br/>[App.jsx]"]
  node_frontend_api["API Client<br/>http boundary<br/>[axiosClient.js]"]
  node_frontend_context["App Contexts<br/>client state"]
  node_frontend_modules_auth["Auth Module<br/>feature slice"]
  node_frontend_modules_chat["Chat Module<br/>feature slice"]
  node_frontend_modules_feed["Feed Module<br/>feature slice"]
  node_frontend_modules_call["Call Module<br/>feature slice"]
  node_frontend_modules_meeting["Meeting Module<br/>feature slice"]
  node_frontend_modules_org["Org Module<br/>feature slice"]
  node_frontend_routes["Route Guards<br/>navigation"]
end

subgraph group_infra["Shared Infra"]
  node_redis[("Redis<br/>ephemeral state<br/>[redisClient.js]")]
  node_r2_storage[("R2 Storage<br/>object storage")]
  node_email_service["Email Service<br/>outbound service<br/>[sendEmail.js]"]
end

node_docker_compose -->|"runs"| node_backend_app
node_docker_compose -->|"runs"| node_frontend_app
node_backend_app -->|"boots with"| node_backend_config
node_backend_app -->|"uses"| node_backend_middleware
node_backend_app -->|"opens"| node_backend_socket
node_backend_app -->|"responds with"| node_backend_presenters_views
node_backend_app -->|"reads"| node_backend_models_identity
node_backend_app -->|"reads"| node_backend_models_work
node_backend_app -->|"reads"| node_backend_models_collab
node_backend_app -->|"reads"| node_backend_models_docs
node_backend_app -->|"delegates to"| node_backend_services_policy
node_backend_app -->|"delegates to"| node_backend_services_realtime
node_backend_app -->|"delegates to"| node_backend_services_storage
node_backend_config -->|"connects"| node_redis
node_backend_services_realtime -->|"uses"| node_redis
node_backend_services_storage -->|"stores in"| node_r2_storage
node_backend_services_storage -->|"sends via"| node_email_service
node_backend_socket -->|"feeds"| node_frontend_context
node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"uses"| node_frontend_context
node_frontend_app -->|"navigates through"| node_frontend_routes
node_frontend_app -->|"loads"| node_frontend_modules_auth
node_frontend_app -->|"loads"| node_frontend_modules_chat
node_frontend_app -->|"loads"| node_frontend_modules_feed
node_frontend_app -->|"loads"| node_frontend_modules_call
node_frontend_app -->|"loads"| node_frontend_modules_meeting
node_frontend_app -->|"loads"| node_frontend_modules_org
node_frontend_modules_chat -->|"syncs over HTTP"| node_frontend_api
node_frontend_modules_chat -->|"syncs over sockets"| node_backend_socket
node_frontend_modules_feed -->|"syncs over HTTP"| node_frontend_api
node_frontend_modules_call -->|"syncs over sockets"| node_backend_socket
node_frontend_modules_meeting -->|"syncs over sockets"| node_backend_socket
node_frontend_modules_org -->|"syncs over HTTP"| node_frontend_api

click node_docker_compose "https://github.com/tuananhtrieu1305/workhub/blob/main/docker-compose.yml"
click node_backend_app "https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/app.js"
click node_backend_config "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/config"
click node_backend_middleware "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/middlewares"
click node_backend_models_identity "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models"
click node_backend_models_work "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models"
click node_backend_models_collab "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models"
click node_backend_models_docs "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models"
click node_backend_services_policy "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services"
click node_backend_services_realtime "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services"
click node_backend_services_storage "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services"
click node_backend_presenters_views "https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/presenters"
click node_backend_socket "https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/config/socketHandler.js"
click node_frontend_app "https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/App.jsx"
click node_frontend_api "https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/api/axiosClient.js"
click node_frontend_context "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/context"
click node_frontend_modules_auth "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/auth"
click node_frontend_modules_chat "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/chat"
click node_frontend_modules_feed "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/feed"
click node_frontend_modules_call "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/call"
click node_frontend_modules_meeting "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/meeting"
click node_frontend_modules_org "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/organization"
click node_frontend_routes "https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/routes"
click node_redis "https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/config/redisClient.js"
click node_r2_storage "https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/services/r2StorageService.js"
click node_email_service "https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/utils/sendEmail.js"

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_docker_compose toneBlue
class node_backend_app,node_backend_config,node_backend_middleware,node_backend_models_identity,node_backend_models_work,node_backend_models_collab,node_backend_models_docs,node_backend_services_policy,node_backend_services_realtime,node_backend_services_storage,node_backend_presenters_views,node_backend_socket toneAmber
class node_frontend_app,node_frontend_api,node_frontend_context,node_frontend_modules_auth,node_frontend_modules_chat,node_frontend_modules_feed,node_frontend_modules_call,node_frontend_modules_meeting,node_frontend_modules_org,node_frontend_routes toneMint
class node_redis,node_r2_storage,node_email_service toneRose
```

## Components

### Deployment

Containerized runtime boundary for the whole stack

- [Docker Compose](https://github.com/tuananhtrieu1305/workhub/blob/main/docker-compose.yml): orchestration · Main runtime wrapper for frontend, backend, and dependencies · `docker-compose.yml`

### Backend API

Node.js server, domain model layer, and API shaping

- [Backend App](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/app.js): node entrypoint · Node.js API entrypoint and server bootstrap · `backend-node/src/app.js`
- [Backend Config](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/config): runtime config · Database, Redis, sockets, multer, and upload path setup · `backend-node/src/config`
- [Middleware](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/middlewares): request guards · Auth, admin, rate limiting, and upload guards · `backend-node/src/middlewares`
- [Identity Models](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models): domain models · Users, organizations, membership, roles, invites, preferences, and activity logs · `backend-node/src/models`
- [Work Models](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models): domain models · Projects, tasks, assignees, and checklist items · `backend-node/src/models`
- [Collab Models](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models): domain models · Posts, comments, likes, conversations, messages, calls, meetings, and notifications · `backend-node/src/models`
- [Docs Models](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/models): domain models · Folders, documents, shares, and versions · `backend-node/src/models`
- [Policy Services](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services): business rules · Permissions, organization scope, and task/document access control · `backend-node/src/services`
- [Realtime Services](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services): coordination · Presence, call locks, meeting helpers, and task event coordination · `backend-node/src/services`
- [Storage Services](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/services): file pipeline · File validation, upload handling, R2 storage, email, and OTP side effects · `backend-node/src/services`
- [Presenters & Views](https://github.com/tuananhtrieu1305/workhub/tree/main/backend-node/src/presenters): response shaping · Transforms models into API payloads for auth, users, orgs, posts, tasks, docs, meetings, calls, and admin · `backend-node/src/presenters`
- [Socket Handler](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/config/socketHandler.js): realtime gateway · 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](https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/App.jsx): react entrypoint · React/Vite client bootstrap and app shell · `frontend/src/App.jsx`
- [API Client](https://github.com/tuananhtrieu1305/workhub/blob/main/frontend/src/api/axiosClient.js): http boundary · Central axios client and feature API wrappers · `frontend/src/api/axiosClient.js`
- [App Contexts](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/context): client state · Auth, socket, and shared session state · `frontend/src/context`
- [Auth Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/auth): feature slice · Login, register, verify email, and password reset flow · `frontend/src/modules/auth`
- [Chat Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/chat): feature slice · Conversation list, message timeline, polls, reminders, and socket sync · `frontend/src/modules/chat`
- [Feed Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/feed): feature slice · Posts, comments, reactions, and attachment handling · `frontend/src/modules/feed`
- [Call Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/call): feature slice · Incoming/outgoing calls and call room experience · `frontend/src/modules/call`
- [Meeting Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/meeting): feature slice · Meeting rooms, lobby, dock, and whiteboard controls · `frontend/src/modules/meeting`
- [Org Module](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/modules/organization): feature slice · Workspace dashboard, membership, invites, roles, and settings · `frontend/src/modules/organization`
- [Route Guards](https://github.com/tuananhtrieu1305/workhub/tree/main/frontend/src/routes): navigation · Protected, guest, and admin route boundaries · `frontend/src/routes`

### Shared Infra

Cross-cutting runtime dependencies and coordination services

- [Redis](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/config/redisClient.js): ephemeral state · Presence, locks, and rate limiting coordination · `backend-node/src/config/redisClient.js`
- [R2 Storage](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/services/r2StorageService.js): object storage · Object storage target for uploads and attachments · `backend-node/src/services/r2StorageService.js`
- [Email Service](https://github.com/tuananhtrieu1305/workhub/blob/main/backend-node/src/utils/sendEmail.js): outbound service · Password reset, verification, and invite notifications · `backend-node/src/utils/sendEmail.js`

## Connections

- 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