Notifications system (#727)

* Notifications

* Updated lockfile

---------

Co-authored-by: Rajat <hi@rajatsaxena.dev>

Author: rajat1saxena

AGENTS.md

@@ -9,6 +9,13 @@
 - When working with forms, always use refs to keep the current state of the form's data and use it to enable/disable the form submit button.
 - Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
 - While working with forms, always use zod and react-hook-form to validate the form. Take reference implementation from `apps/web/components/admin/settings/sso/new.tsx`.
+- `packages/scripts` is meant to contain maintenance scripts which can be re-used over and over, not one-off migrations. One-off migrations should be in `apps/web/.migrations`.
+- `packages/utils` should be the place for containing utilities which are used in more than one package.
+- `apps/web` and `apps/queue` can share business logic and db models. Common business logic should be moved to `packages/common-logic`. Common DB related functionality should be moved to `packages/orm-models`.
+- For migrations (located in `apps/web/.migrations`), follow the "Gold Standard" pattern:
+    - Use **Cursors** (`.cursor()`) to stream data from MongoDB, ensuring the script remains memory-efficient regardless of dataset size.
+    - Use **Batching** with `bulkWrite` (e.g., batches of 500) to maximize performance and minimize network roundtrips.
+    - Ensure **Idempotency** (safe to re-run) by using upserts or `$setOnInsert` where applicable.
 
 ## Documentation tips
 

apps/docs/public/assets/users/notifications-hub.png

@@ -122,6 +122,7 @@ export const SIDEBAR: Sidebar = {
         Users: [
             { text: "Introduction", link: "en/users/introduction" },
             { text: "Manage users", link: "en/users/manage" },
+            { text: "Customize notifications", link: "en/users/notifications" },
             { text: "User permissions", link: "en/users/permissions" },
             { text: "Filter users", link: "en/users/filters" },
             { text: "Segment users", link: "en/users/segments" },

apps/docs/src/config.ts

@@ -0,0 +1,42 @@
+---
+title: Customize notifications
+description: Customize app and email notifications
+layout: ../../../layouts/MainLayout.astro
+---
+
+CourseLit lets each user control how they receive notifications for different activities.
+
+> This feature is currently in beta, which means you may encounter bugs. Please report them in our <a href="https://discord.com/invite/GR4bQsN" target="_blank">Discord</a> group if you run into any issues.
+
+## Open notification settings
+
+1. Log in to your school.
+2. Open `Dashboard`.
+3. Click on your avatar (in the bottom-left corner) to open up the user menu.
+4. Click on `Notifications`.
+
+![Notifications hub](/assets/users/notifications-hub.png)
+
+## Understand notification groups
+
+Notification preferences are shown in groups based on activity type:
+
+- **General**
+- **Product**
+- **User**
+- **Community**
+
+General notification preferences are available to all users.
+
+## Choose channels
+
+Each activity row has two channels:
+
+- **App**: sends notifications inside your CourseLit dashboard.
+- **Email**: sends notifications to your email inbox.
+
+Tick or untick the checkboxes to turn each channel on or off for that activity. Changes are saved immediately.
+
+## Stuck somewhere?
+
+We are always here for you. Come chat with us in our <a href="https://discord.com/invite/GR4bQsN" target="_blank">Discord</a> channel or send a tweet at <a href="https://twitter.com/courselit" target="_blank">@CourseLit</a>.

apps/docs/src/pages/en/users/notifications.md

@@ -0,0 +1,10 @@
+## Development Tips
+
+- The code is organised domain wise. All related resources for a domain are kept in a folder under `src/<domain-name>`.
+- Inside `src/<domain-name>` folder, you will find `model`, `queue`, `routes`, `services`, `utils` folders/files.
+- `model` contains the mongoose models for the domain.
+- `queue` contains the bullmq queues for the domain.
+- `worker` contains the bullmq workers for the domain.
+- `routes` contains the express routes for the domain.
+- `services` contains the services for the domain.
+- `utils` contains the utils for the domain.

apps/queue/AGENTS.md

@@ -7,6 +7,7 @@ const config = {
         "@courselit/common-logic": "<rootDir>/../../packages/common-logic/src",
         "@courselit/common-models":
             "<rootDir>/../../packages/common-models/src",
+        "@courselit/orm-models": "<rootDir>/../../packages/orm-models/src",
         "@courselit/email-editor":
             "<rootDir>/__mocks__/@courselit/email-editor.ts",
         nanoid: "<rootDir>/__mocks__/nanoid.ts",

apps/queue/jest.config.ts

@@ -1,20 +1,22 @@
 {
     "name": "@courselit/queue",
     "version": "0.25.10",
+    "type": "module",
     "private": true,
     "packageManager": "pnpm@9.14.2",
     "scripts": {
         "build": "tsup",
         "tsc:build": "tsc",
         "check-types": "tsc --noEmit",
-        "start": "node dist/index.mjs",
+        "start": "node dist/index.js",
         "build:dev": "tsup --watch",
-        "dev": "node --env-file .env.local --watch dist/index.mjs"
+        "dev": "node --watch --env-file .env.local --import tsx src/index.ts"
     },
     "dependencies": {
         "@courselit/common-logic": "workspace:^",
         "@courselit/common-models": "workspace:^",
         "@courselit/email-editor": "workspace:^",
+        "@courselit/orm-models": "workspace:^",
         "@courselit/utils": "workspace:^",
         "@types/jsdom": "^21.1.7",
         "bullmq": "^4.14.0",
@@ -37,6 +39,7 @@
         "ts-jest": "^29.4.4",
         "tsconfig": "workspace:^",
         "tsup": "^7.2.0",
+        "tsx": "^4.21.0",
         "typescript": "^5.9.3",
         "typescript-eslint": "^8.46.4"
     }

apps/queue/package.json

@@ -1,18 +1,20 @@
 import type { MailJob } from "./model/mail-job";
-import notificationQueue from "./notification-queue";
 import mailQueue from "./queue";
 
-export async function addMailJob({ to, subject, body, from }: MailJob) {
+export async function addMailJob({
+    to,
+    subject,
+    body,
+    from,
+    headers,
+}: MailJob) {
     for (const recipient of to) {
         await mailQueue.add("mail", {
             to: recipient,
             subject,
             body,
             from,
+            headers,
         });
     }
 }
-
-export async function addNotificationJob(notification) {
-    await notificationQueue.add("notification", notification);
-}

apps/queue/src/domain/handler.ts

@@ -5,6 +5,7 @@ export const MailJob = z.object({
     from: z.string(),
     subject: z.string(),
     body: z.string(),
+    headers: z.record(z.string()).optional(),
 });
 
 export type MailJob = z.infer<typeof MailJob>;