📕 Files

📖 Overview

The Files service manages document storage and retrieval for project-related files, including deliverables, resources, and client-specific documents. It provides secure file management with access control based on account relationships and user scopes.

Source Files:

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

Key Capabilities:

• Store file metadata after S3 upload
• List files with pagination and search
• Update file metadata
• Delete single or multiple files
• Scope-based access control
• Client-specific file organization

🗄️ Collections Used

projects-files

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

Key Fields:

{
  _id: ObjectId,
  accountId: ObjectId,        // Agency account
  clientId: ObjectId,         // Client account
  userId: ObjectId,           // Uploader
  key: String,                // S3 key
  fileName: String,
  bucketName: String,
  fileType: String,
  fileSize: Number,
  created_by: ObjectId,
  createdAt: Date,
  updatedAt: Date
}

_users

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

🔧 Business Logic & Functions

Service Layer Functions

storeFiles(options)

Purpose: Stores file metadata after S3 upload completion.

Parameters:

• accountId (ObjectId) - Agency account ID
• userId (ObjectId) - User who uploaded
• reqBody (Object) - File details from S3 upload
  • clientId, key, fileName, bucketName, fileType, fileSize

Returns: Created file document

Business Logic:

• Creates file record with metadata
• Associates with both agency and client accounts
• Tracks uploader for audit trail

---

getAllFiles(options)

Purpose: Retrieves paginated file list with search and filtering.

Parameters:

• clientId (ObjectId, optional) - Filter by client
• search (String, optional) - Filename search term
• skip (Number) - Pagination offset
• limit (Number) - Max files 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 dashboardPreferences.parent_account
   • Admins with PROJECT_ROLES: No account filter (global access)

2. Search Implementation: Case-insensitive regex on fileName

3. User Enrichment: Joins uploader information

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

---

updateFile(options)

Purpose: Updates file metadata.

Parameters:

• data (Object) - Fields to update
• fileId (ObjectId) - Target file ID
• accountId (ObjectId) - Account validation

Returns: Updated file document

Business Logic:

• Validates file belongs to account
• Uses findOneAndUpdate for atomic update
• Returns updated document

---

deleteFile(options)

Purpose: Deletes a single file (soft or hard delete based on implementation).

Parameters:

• fileId (ObjectId) - Target file ID
• clientId (ObjectId, optional) - Client filter
• scope (Array) - User scopes
• accountId (ObjectId) - Account validation

Returns: Delete result

Business Logic:

• Authorization Check: Requires files or files.delete scope
• Dual Query: Matches by accountId OR by _id alone (admin bypass)
• Physical deletion from database

---

deleteMultipleFiles(options)

Purpose: Batch deletes multiple files.

Parameters:

• ids (Array) - Array of file IDs
• clientId, scope, accountId - Same as deleteFile

Returns: { message: "X files successfully deleted" }

Business Logic:

• Same authorization as single delete
• Uses $in operator for batch operation
• Returns count of deleted files

---

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 (not sub-accounts) can manage files.

🔀 Integration Points

Internal Dependencies

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

External Services

• AWS S3 - Actual file storage (external to this module)

⚠️ Important Notes

• 🔒 Main Account Only: Only main agency accounts can create/update/delete files
• 📁 S3 Integration: This module only handles metadata; actual uploads happen via separate S3 service
• 🗑️ Hard Deletes: Files are physically removed from database (no soft delete)
• 🔍 Search: Simple regex search (consider full-text indexing for scale)
• 📊 Scope Required: Delete operations require explicit files or files.delete scope

🔗 Related Documentation

• Projects Module Overview - Parent module
• Activity - File uploads may be logged

---

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