How jihadul021/orbit-board works
1. Overall shape: two-tier monorepo
- OrbitBoard is split into a React/Vite frontend under client/ and an Express/MongoDB backend under server/.
- The frontend is a single-page app that talks to the backend over HTTP using Axios.
- The backend is a REST API that owns authentication, editorial workflow logic, and persistence.
2. Frontend boundary
- client/src/main.jsx boots the app, App.jsx wires routing/layout, and client/src/pages/ contains route-level screens such as Landing, Login/Register/ForgotPassword, Boards, Board, Groups, Profile, and AdminBoard.
- client/src/components/ holds reusable UI for the workflow: article editor, modal dialogs, sidebar, page header, comment thread, notifications, activity log, and review-pick dialogs.
- client/src/store/authStore.js is the main client-side state boundary, tracking logged-in user/session state.
3. Frontend technology and UI behavior
- The client uses React Router for navigation, Zustand for auth state, Axios for API calls, Tiptap for rich-text editing, and Tailwind CSS for styling.
- The article editor is a key UI subsystem because it supports autosave, manual save, and role-aware editing controls.
- The UI is organized around board-centric workflow screens rather than generic CRUD forms.
4. Backend boundary
- server/src/index.js is the entrypoint that wires Express middleware, routes, and MongoDB connection.
- The backend is structured by resource: controllers/, routes/, models/, middleware/, and lib/.
- Each major domain area has its own controller and route file: auth, groups, boards, lists, articles, review, comments, notifications, and activity logs.
5. Persistence model
- The backend uses Mongoose models for the core entities: User, Group, Board, List, Article, Comment, Notification, ActivityLog, and OtpToken.
- This suggests MongoDB is the system of record for both workflow data and security-related OTP records.
- The architecture is document-centric, with boards/lists/articles forming the editorial hierarchy.
6. Authentication and session flow
- Auth is handled by authController, with JWT access tokens plus httpOnly refresh-token cookies.
- Email OTP registration and password reset are backed by OtpToken and email delivery through server/src/lib/email.js.
- Google sign-in is supported via Google Auth Library, and protect middleware gates authenticated API access.
- Client-side auth state likely mirrors the server session through /api/auth/me and refresh flows.
7. Group and board tenancy
- Group is the workspace boundary: users belong to groups, and boards live inside groups.
- Group management includes invitations, member removal, and leave actions.
- Boards are role-aware and support writer/editor/admin participation, including a generated admin overview board per group.
- Board access is enforced server-side, not just by hiding UI.
8. Editorial workflow and review-copy architecture
- The distinctive system behavior is the separate review copy model: writers own the original article, while editors work on a copied version.
- reviewController manages “pick for review,” copy status changes, synchronization back to the original, and cleanup when review copies are deleted.
- This creates an important architectural boundary between the immutable/original draft and the editable review artifact.
- The admin overview board aggregates content across boards and prefers the latest review copy when present.
9. Kanban content flow
- Boards contain List collections, and lists contain Article items.
- Articles can be created, moved between lists, reordered, archived through list state, and status-updated independently of board membership.
- Closed boards become read-only, so workflow state is enforced at the board level as well as the article level.
10. Collaboration features
- commentController supports threaded comments and replies, including mention support and role-aware permissions.
- notificationController exposes unread counts and read state, with deep links back into articles or threads.
- activityLogController records audit events such as article creation, review pickup/return, status changes, and comments.
11. Shared server-side utilities
- server/src/lib/ contains cross-cutting helpers: token generation, email sending, role mapping, activity logging, notification fan-out, and Zod validation schemas.
- validate middleware and validationSchemas indicate request payload validation is a first-class boundary before controllers mutate data.
- errorHandler centralizes API failure handling.
12. End-to-end data flow
- A typical flow starts in the React UI, calls a REST endpoint via Axios, passes through auth/validation middleware, reaches a controller, updates a Mongoose model, and may trigger email, notifications, or activity-log writes.
- The reverse flow is also important: server responses drive board state, unread counts, article content, and review status in the client.
13. Operational/deployment shape
- The app expects separate frontend and backend environments: VITE_API_URL on the client, and PORT, MONGO_URI, JWT secrets, Google client ID, and Resend API keys on the server.
- This means the architecture is deployed as at least two services: a browser-based SPA and an API server backed by MongoDB and external email/auth providers.
Main entry points: index.js Server boot · models Models · authController.js Auth · reviewController.js Review flow
Components 23
Frontend
React/Vite SPA and UI state
- Boot · Starts the React app
client/src/main.jsx - App shell · Wires routes and top-level layout
client/src/App.jsx - Pages · Route-level screens for boards, groups, auth, profile, and admin
client/src/pages - UI components · Reusable board, editor, modal, comment, notification, and sidebar components
client/src/components - Article editor · Tiptap-based article editing with autosave and role-aware controls
client/src/components/ArticleEditor.jsx - Auth store · Client session and logged-in user state
client/src/store/authStore.js - API client · HTTP boundary to the backend API
client/src/api/axios.js
Backend
Express REST API and workflow logic
- Server boot · Configures middleware, routes, and MongoDB connection
server/src/index.js - Auth · Login, registration, OTP, refresh tokens, and Google sign-in
server/src/controllers/authController.js - Groups · Workspace membership, invitations, and tenancy boundary
server/src/controllers/groupController.js - Boards · Board access, roles, and board-level workflow
server/src/controllers/boardController.js - Lists · Kanban columns and article ordering
server/src/controllers/listController.js - Articles · Article create, move, archive, and status updates
server/src/controllers/articleController.js - Review flow · Separate review-copy lifecycle and sync back to originals
server/src/controllers/reviewController.js - Comments · Threaded comments, replies, and mentions
server/src/controllers/commentController.js - Notifications · Unread counts, read state, and deep links
server/src/controllers/notificationController.js - Activity log · Audit trail for editorial actions
server/src/controllers/activityLogController.js - Middleware · Protects routes, validates payloads, and handles errors
server/src/middleware - Shared lib · Tokens, email, role mapping, notifications, activity helpers, and schemas
server/src/lib
Data & external
MongoDB plus auth/email providers
- Models · User, Group, Board, List, Article, Comment, Notification, ActivityLog, and OtpToken documents
server/src/models - MongoDB · System of record for workflow and security data
- Email service · Sends OTP and account emails
server/src/lib/email.js - Google auth · External sign-in identity provider
Connections 36
- Boot → App shell: renders · Bootstraps the application shell
- App shell → Pages: routes to · Dispatches to screen-level pages
- App shell → UI components: composes · Uses shared layout and workflow UI
- Pages → Article editor: uses · Board and article screens embed the editor
- Pages → Auth store: reads state · Screens reflect session and role state
- UI components → API client: calls · UI actions invoke the REST client
- Auth store → API client: hydrates from · Session state follows auth API responses and refresh flow
- API client → Server boot: HTTP · Frontend talks to the backend API
- Server boot → Middleware: installs · Wires protection, validation, and error handling
- Server boot → Auth: mounts · Registers auth endpoints
- Server boot → Groups: mounts · Registers group endpoints
- Server boot → Boards: mounts · Registers board endpoints
- Server boot → Lists: mounts · Registers list endpoints
- Server boot → Articles: mounts · Registers article endpoints
- Server boot → Review flow: mounts · Registers review endpoints
- Server boot → Comments: mounts · Registers comment endpoints
- Server boot → Notifications: mounts · Registers notification endpoints
- Server boot → Activity log: mounts · Registers audit endpoints
- Auth → Shared lib: uses · Shares token generation, email, and validation helpers
- Groups → Shared lib: uses · Uses role mapping and activity/notification helpers
- Review flow → Shared lib: uses · Uses workflow helpers and logging utilities
- Auth → Models: reads/writes · Mutates users and OTP records
- Groups → Models: reads/writes · Manages group membership and invitations
- Boards → Models: reads/writes · Enforces board membership and roles
- Lists → Models: reads/writes · Persists list ordering and board columns
- Articles → Models: reads/writes · Stores article content and workflow state
- Review flow → Models: reads/writes · Manages review copies and synchronization
- Comments → Models: reads/writes · Persists threaded discussion
- Notifications → Models: reads/writes · Tracks unread/read notification state
- Activity log → Models: reads/writes · Stores audit events
- Models → MongoDB: persists to · MongoDB is the backing store
- Auth → Google auth: oauth · Supports Google sign-in
- Auth → Email service: sends · Delivers OTP and reset emails
- Articles → Notifications: fans out · Triggers notifications on editorial events
- Review flow → Activity log: logs · Records review pickup and return events
- Comments → Activity log: logs · Records comment activity