# jihadul021/orbit-board architecture

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

- Interactive diagram: https://gitdiagram.com/jihadul021/orbit-board
- Repository: https://github.com/jihadul021/orbit-board

## Overview

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: [`server/src/index.js`](https://github.com/jihadul021/orbit-board/blob/main/server/src/index.js) (Server boot), [`server/src/models`](https://github.com/jihadul021/orbit-board/tree/main/server/src/models) (Models), [`server/src/controllers/authController.js`](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/authController.js) (Auth), [`server/src/controllers/reviewController.js`](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/reviewController.js) (Review flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Frontend"]
  node_client_main["Boot<br/>client entry<br/>[main.jsx]"]
  node_client_app["App shell<br/>routing shell<br/>[App.jsx]"]
  node_client_pages["Pages<br/>screens"]
  node_client_components["UI components<br/>workflow UI"]
  node_client_editor["Article editor<br/>rich text editor<br/>[ArticleEditor.jsx]"]
  node_client_authstore["Auth store<br/>zustand session<br/>[authStore.js]"]
  node_client_api["API client<br/>axios client<br/>[axios.js]"]
end

subgraph group_server["Backend"]
  node_server_entry["Server boot<br/>express entrypoint<br/>[index.js]"]
  node_server_auth["Auth<br/>controller/route<br/>[authController.js]"]
  node_server_groups["Groups<br/>controller/route<br/>[groupController.js]"]
  node_server_boards["Boards<br/>controller/route<br/>[boardController.js]"]
  node_server_lists["Lists<br/>controller/route<br/>[listController.js]"]
  node_server_articles["Articles<br/>controller/route"]
  node_server_review["Review flow<br/>controller/route"]
  node_server_comments["Comments<br/>controller/route"]
  node_server_notifications["Notifications<br/>controller/route"]
  node_server_activity["Activity log<br/>controller/route"]
  node_server_middleware["Middleware<br/>auth/validation"]
  node_server_lib["Shared lib<br/>utilities"]
end

subgraph group_data["Data & external"]
  node_db_models[("Models")]
  node_mongo[("MongoDB<br/>document store")]
  node_email["Email service<br/>delivery provider<br/>[email.js]"]
  node_google["Google auth<br/>oauth provider"]
end

node_client_main -->|"renders"| node_client_app
node_client_app -->|"routes to"| node_client_pages
node_client_app -->|"composes"| node_client_components
node_client_pages -->|"uses"| node_client_editor
node_client_pages -->|"reads state"| node_client_authstore
node_client_components -->|"calls"| node_client_api
node_client_authstore -.->|"hydrates from"| node_client_api
node_client_api -->|"HTTP"| node_server_entry
node_server_entry -->|"installs"| node_server_middleware
node_server_entry -->|"mounts"| node_server_auth
node_server_entry -->|"mounts"| node_server_groups
node_server_entry -->|"mounts"| node_server_boards
node_server_entry -->|"mounts"| node_server_lists
node_server_entry -->|"mounts"| node_server_articles
node_server_entry -->|"mounts"| node_server_review
node_server_entry -->|"mounts"| node_server_comments
node_server_entry -->|"mounts"| node_server_notifications
node_server_entry -->|"mounts"| node_server_activity
node_server_auth -->|"uses"| node_server_lib
node_server_groups -->|"uses"| node_server_lib
node_server_review -->|"uses"| node_server_lib
node_server_auth -->|"reads/writes"| node_db_models
node_server_groups -->|"reads/writes"| node_db_models
node_server_boards -->|"reads/writes"| node_db_models
node_server_lists -->|"reads/writes"| node_db_models
node_server_articles -->|"reads/writes"| node_db_models
node_server_review -->|"reads/writes"| node_db_models
node_server_comments -->|"reads/writes"| node_db_models
node_server_notifications -->|"reads/writes"| node_db_models
node_server_activity -->|"reads/writes"| node_db_models
node_db_models -->|"persists to"| node_mongo
node_server_auth -.->|"oauth"| node_google
node_server_auth -.->|"sends"| node_email
node_server_articles -.->|"fans out"| node_server_notifications
node_server_review -.->|"logs"| node_server_activity
node_server_comments -.->|"logs"| node_server_activity

click node_client_main "https://github.com/jihadul021/orbit-board/blob/main/client/src/main.jsx"
click node_client_app "https://github.com/jihadul021/orbit-board/blob/main/client/src/App.jsx"
click node_client_pages "https://github.com/jihadul021/orbit-board/tree/main/client/src/pages"
click node_client_components "https://github.com/jihadul021/orbit-board/tree/main/client/src/components"
click node_client_editor "https://github.com/jihadul021/orbit-board/blob/main/client/src/components/ArticleEditor.jsx"
click node_client_authstore "https://github.com/jihadul021/orbit-board/blob/main/client/src/store/authStore.js"
click node_client_api "https://github.com/jihadul021/orbit-board/blob/main/client/src/api/axios.js"
click node_server_entry "https://github.com/jihadul021/orbit-board/blob/main/server/src/index.js"
click node_server_auth "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/authController.js"
click node_server_groups "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/groupController.js"
click node_server_boards "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/boardController.js"
click node_server_lists "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/listController.js"
click node_server_articles "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/articleController.js"
click node_server_review "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/reviewController.js"
click node_server_comments "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/commentController.js"
click node_server_notifications "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/notificationController.js"
click node_server_activity "https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/activityLogController.js"
click node_server_middleware "https://github.com/jihadul021/orbit-board/tree/main/server/src/middleware"
click node_server_lib "https://github.com/jihadul021/orbit-board/tree/main/server/src/lib"
click node_db_models "https://github.com/jihadul021/orbit-board/tree/main/server/src/models"
click node_email "https://github.com/jihadul021/orbit-board/blob/main/server/src/lib/email.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_client_main,node_client_app,node_client_pages,node_client_components,node_client_editor,node_client_authstore,node_client_api toneBlue
class node_server_entry,node_server_auth,node_server_groups,node_server_boards,node_server_lists,node_server_articles,node_server_review,node_server_comments,node_server_notifications,node_server_activity,node_server_middleware,node_server_lib toneAmber
class node_db_models,node_mongo,node_email,node_google toneMint
```

## Components

### Frontend

React/Vite SPA and UI state

- [Boot](https://github.com/jihadul021/orbit-board/blob/main/client/src/main.jsx): client entry · Starts the React app · `client/src/main.jsx`
- [App shell](https://github.com/jihadul021/orbit-board/blob/main/client/src/App.jsx): routing shell · Wires routes and top-level layout · `client/src/App.jsx`
- [Pages](https://github.com/jihadul021/orbit-board/tree/main/client/src/pages): screens · Route-level screens for boards, groups, auth, profile, and admin · `client/src/pages`
- [UI components](https://github.com/jihadul021/orbit-board/tree/main/client/src/components): workflow UI · Reusable board, editor, modal, comment, notification, and sidebar components · `client/src/components`
- [Article editor](https://github.com/jihadul021/orbit-board/blob/main/client/src/components/ArticleEditor.jsx): rich text editor · Tiptap-based article editing with autosave and role-aware controls · `client/src/components/ArticleEditor.jsx`
- [Auth store](https://github.com/jihadul021/orbit-board/blob/main/client/src/store/authStore.js): zustand session · Client session and logged-in user state · `client/src/store/authStore.js`
- [API client](https://github.com/jihadul021/orbit-board/blob/main/client/src/api/axios.js): axios client · HTTP boundary to the backend API · `client/src/api/axios.js`

### Backend

Express REST API and workflow logic

- [Server boot](https://github.com/jihadul021/orbit-board/blob/main/server/src/index.js): express entrypoint · Configures middleware, routes, and MongoDB connection · `server/src/index.js`
- [Auth](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/authController.js): controller/route · Login, registration, OTP, refresh tokens, and Google sign-in · `server/src/controllers/authController.js`
- [Groups](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/groupController.js): controller/route · Workspace membership, invitations, and tenancy boundary · `server/src/controllers/groupController.js`
- [Boards](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/boardController.js): controller/route · Board access, roles, and board-level workflow · `server/src/controllers/boardController.js`
- [Lists](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/listController.js): controller/route · Kanban columns and article ordering · `server/src/controllers/listController.js`
- [Articles](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/articleController.js): controller/route · Article create, move, archive, and status updates · `server/src/controllers/articleController.js`
- [Review flow](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/reviewController.js): controller/route · Separate review-copy lifecycle and sync back to originals · `server/src/controllers/reviewController.js`
- [Comments](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/commentController.js): controller/route · Threaded comments, replies, and mentions · `server/src/controllers/commentController.js`
- [Notifications](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/notificationController.js): controller/route · Unread counts, read state, and deep links · `server/src/controllers/notificationController.js`
- [Activity log](https://github.com/jihadul021/orbit-board/blob/main/server/src/controllers/activityLogController.js): controller/route · Audit trail for editorial actions · `server/src/controllers/activityLogController.js`
- [Middleware](https://github.com/jihadul021/orbit-board/tree/main/server/src/middleware): auth/validation · Protects routes, validates payloads, and handles errors · `server/src/middleware`
- [Shared lib](https://github.com/jihadul021/orbit-board/tree/main/server/src/lib): utilities · Tokens, email, role mapping, notifications, activity helpers, and schemas · `server/src/lib`

### Data & external

MongoDB plus auth/email providers

- [Models](https://github.com/jihadul021/orbit-board/tree/main/server/src/models): mongoose models · User, Group, Board, List, Article, Comment, Notification, ActivityLog, and OtpToken documents · `server/src/models`
- **MongoDB**: document store · System of record for workflow and security data
- [Email service](https://github.com/jihadul021/orbit-board/blob/main/server/src/lib/email.js): delivery provider · Sends OTP and account emails · `server/src/lib/email.js`
- **Google auth**: oauth provider · External sign-in identity provider

## Connections

- 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
