📔 Notebooks

📖 Overview

The Notebooks service provides structured documentation and note-taking capabilities for projects, enabling teams to maintain organized records, internal documentation, and collaborative notes throughout service delivery.

Source Files:

• Service: internal/api/v1/projects/services/notebooks.service.js
• Controller: internal/api/v1/projects/controllers/notebooks.controller.js

Key Capabilities:

• Create rich-text notebooks with attachments
• List notebooks with pagination and search
• Update notebook content
• Delete notebooks
• Client-specific organization
• User tracking for audit trails

🗄️ Collections Used

projects-notebooks

• Operations: Create, Read, Update, Delete
• Model: shared/models/projects-notebooks.js
• Usage Context: Primary storage for notebook documents

Key Fields:

{
  _id: ObjectId,
  accountId: ObjectId,        // Agency account
  clientId: ObjectId,         // Client account
  userId: ObjectId,           // Creator
  title: String,              // Notebook title
  description: String,        // Short description
  content: String,            // Rich text content
  attachments: Array,         // File references
  createdAt: Date,
  updatedAt: Date
}

_users

• Operations: Read (enrichment)
• Usage Context: Provides creator information

🔧 Business Logic & Functions

Service Layer Functions

storeNotebooks(options)

Purpose: Creates a new notebook with content and attachments.

Parameters:

• accountId (ObjectId) - Agency account ID
• userId (ObjectId) - User creating notebook
• reqBody (Object) - Notebook details
  • clientId, title, description, content, attachments

Returns: Created notebook document

Business Logic:

• Stores rich-text content
• Associates with client account
• Tracks creator for attribution
• Supports optional attachments array

---

getAllNotebooks(options)

Purpose: Retrieves paginated notebooks with search and filtering.

Parameters:

• clientId (ObjectId, optional) - Filter by client
• search (String, optional) - Title search term
• skip (Number) - Pagination offset
• limit (Number) - Max notebooks to return
• accountId (ObjectId) - Agency account ID
• dashclicks (Object) - User permissions
• dashboardPreferences (Object) - Client dashboard settings

Returns: { data: [], count: Number }

Business Logic:

1. Access Scoping:

   • Agency users: Scoped to accountId
   • Client dashboard: Scoped to parent_account
   • Admins with PROJECT_ROLES: No account filter

2. Search: Case-insensitive regex on title field

3. User Enrichment: Joins creator details

4. Sorting: Newest notebooks first (createdAt: -1)

5. Parallel Queries: Executes data and count queries simultaneously for performance

---

updateNotebook(options)

Purpose: Updates notebook content or metadata.

Parameters:

• data (Object) - Fields to update
• notebookId (ObjectId) - Target notebook ID
• accountId (ObjectId) - Account validation

Returns: Updated notebook document

Business Logic:

• Validates notebook belongs to account
• Atomic update with findOneAndUpdate
• Returns new document state
• No upsert (won't create if doesn't exist)

---

deleteNotebook(options)

Purpose: Permanently deletes a notebook.

Parameters:

• notebookId (ObjectId) - Target notebook ID
• accountId (ObjectId) - Account validation

Returns: Delete result

Business Logic:

• Validates notebook belongs to account
• Physical deletion from database
• No soft delete mechanism

---

Controller Layer

All controllers enforce main account restriction:

if (!req.auth.account.main) {
  throw badRequest('You are not allowed to perform this action');
}

Only main agency accounts can manage notebooks.

🔄 Data Flow

flowchart TD
    A[Create Notebook] --> B[Validate Main Account]
    B --> C[Store with Client Association]
    C --> D[Track Creator]
    D --> E[Return Notebook]

    F[List Notebooks] --> G{User Type?}
    G -->|Agency| H[Filter by accountId]
    G -->|Client Dashboard| I[Filter by parent_account]
    G -->|Admin| J[No Filter]
    H --> K[Search by Title]
    I --> K
    J --> K
    K --> L[Enrich with User Info]
    L --> M[Return Results]

🔀 Integration Points

Internal Dependencies

• PROJECT_ROLES - Admin role validation
• catchAsync() - Error handling
• generatePagination() - Pagination helper

External Services

None - Pure internal data operations

⚠️ Important Notes

• 🔒 Main Account Only: Only main agency accounts can create/update/delete notebooks
• 📝 Rich Text Support: content field supports HTML/Markdown (no sanitization in service)
• 🗑️ Hard Deletes: Notebooks are physically removed (no soft delete)
• 🔍 Title Search Only: Search limited to title field (consider full-text for content search)
• 📎 Attachments: Array of file references (no validation of file existence)

🔗 Related Documentation

• Files - Related file attachment management
• Projects Module Overview - Parent module

---

Last Updated: 2025-10-08
Service Files: services/notebooks.service.js, controllers/notebooks.controller.js
Primary Functions: 4 service functions, 5 controller endpoints