Compass - Nimbly Documentation

Department Backend

9 min read

1. Overview

The API Departments service is a microservice responsible for managing organizational departments within the Nimbly ecosystem. It provides comprehensive department management capabilities including hierarchical structures, user assignments, site associations, and questionnaire mappings. The service follows a clean architecture pattern with clear separation between controllers, use cases, and repositories.

Key Features

  • Department CRUD operations with hierarchical support
  • Department index management for user, site, and questionnaire associations
  • Department groups for logical organization
  • Bulk import/export capabilities
  • Role-based [access control](../Settings/Access control/AccessControlOverview.md) integration
  • Real-time activity tracking
  • Multi-tenant support with organization isolation

2. Technology Stack & Libraries

Core Dependencies

LibraryVersionPurpose
@google-cloud/functions-framework^3.1.1Google Cloud Functions runtime
@google-cloud/tasks^2.3.0Async task queue management
@nimbly-technologies/entity-node1.66.68Entity repositories and data access
@nimbly-technologies/nimbly-access^1.0.0[Access control](../Settings/Access control/AccessControlOverview.md) and [permissions](../Settings/Access control/AccessControlOverview.md)
@nimbly-technologies/nimbly-backend-utils^1.1.2Shared utilities and middleware
@nimbly-technologies/nimbly-common1.92.78Common types and interfaces
express^4.18.2Web framework
mongoose^5.13.21MongoDB object modeling
firebase-admin^12.0.0Firebase services integration
jsonwebtoken^8.5.1JWT authentication
joi^17.3.0Schema validation
axios^0.21.1HTTP client
busboy^1.6.0File upload parsing
lodash^4.17.20Utility functions
ramda^0.27.1Functional programming utilities

Development Dependencies

LibraryPurpose
typescript^5.3.3
jest^29.7.0
eslint^7.22.0
prettier^2.2.1
nodemon^2.0.7
supertest^6.1.1

3. API Endpoints Reference

3.1. Public Endpoints (No Authentication Required)

MethodEndpointDescription
GET/pingHealth check endpoint
GET/readyDatabase connection status
GET/open/department/:organizationID/:departmentIDPublic department details

3.2. Department Management Endpoints

MethodEndpointDescription
GET/departmentsList all departments for user
POST/departmentsCreate new department
GET/departments/:departmentIDGet department by ID
PUT/departments/:departmentIDUpdate department details
GET/departments/paginatePaginated department list
PUT/toggle-status/:departmentIDToggle department active/inactive
GET/user/:userIDGet departments for specific user
GET/site/:siteIDGet department IDs by site
GET/questionnaire/:questionnaireIDGet department IDs by questionnaire
GET/filter-optionsGet filter options for departments
GET/user-filter-optionsGet user-specific filter options

3.3. Department Index Endpoints

MethodEndpointDescription
GET/departments/indexList department indexes
GET/departments/index/:departmentIDGet specific department index
PUT/departments/index/:departmentIDUpdate department index
GET/departments/index/populatedGet populated department indexes
GET/departments/index/:departmentID/populatedGet populated department index by ID
GET/departments/index/sites/:siteIDGet department indexes by site
PUT/departments/index/toggle-entityToggle entity status in index

3.4. Department Group Endpoints

MethodEndpointDescription
GET/departments/groupList department groups
POST/departments/groupCreate department group
GET/departments/group/:idGet department group by ID
PUT/departments/group/:idUpdate department group
DELETE/departments/group/:idDelete department group
PUT/departments/group/toggle-status/:idToggle group status

3.5. [Bulk Operationss](../Bulk Operation/BulkOperationOverview.md) Endpoints

MethodEndpointDescription
POST/upload-usersUpload users via Excel
POST/upload-bulk-usersBulk user upload
POST/upload-bulk-departmentsBulk department upload
POST/insert-siteAssociate site with departments
POST/insert-sitesAssociate multiple sites
POST/insert-userAdd user to departments
POST/questionnaire-indexAssociate questionnaire with departments

3.6. Internal Endpoints (Cross-Organization)

MethodEndpointDescription
GET/internal/list/:organizationIDList departments by organization
POST/internal/organization/:organizationIDCreate department for organization
GET/internal/organization/:organizationIDGet department indexes
GET/internal/organization/:organizationID/:departmentIDGet specific department
PUT/internal/organization/:organizationID/:departmentIDUpdate department
POST/internal/index/keyFind department IDs by organization
POST/internal/index/:departmentIDFind department index by ID
POST/internal/user-levelFind users by level
GET/internal/index/sites/:siteIDFind department indexes by site

4. Department Management System

4.1. Department Entity Model

Departments are the core entities representing organizational units with hierarchical relationships:

classDiagram
    class Department {
        +string departmentID
        +string organizationID
        +string name
        +string description
        +string email
        +string status
        +Date createdAt
        +Date updatedAt
    }
    
    class DepartmentIndex {
        +string departmentID
        +string organizationID
        +string[] users
        +string[] sites
        +string[] questionnaires
        +string status
        +Date createdAt
        +Date updatedAt
    }
    
    class DepartmentGroup {
        +string id
        +string organizationID
        +string name
        +string description
        +Department[] departments
        +string status
        +Date createdAt
        +Date updatedAt
    }
    
    Department "1" --> "1" DepartmentIndex : has
    DepartmentGroup "1" --> "*" Department : contains

4.2. Department Creation Flow

sequenceDiagram
    participant Client
    participant Controller
    participant UseCase
    participant Validator
    participant DeptRepo
    participant DeptIndexRepo
    participant ActivityRepo
    participant PubSub
    
    Client->>Controller: POST /departments
    Controller->>Validator: Validate Input
    Validator-->>Controller: Validation Result
    
    alt Validation Failed
        Controller-->>Client: 400 Bad Request
    else Validation Passed
        Controller->>UseCase: Create Department
        UseCase->>DeptRepo: Check Duplicate
        
        alt Department Exists
            UseCase-->>Controller: Conflict Error
            Controller-->>Client: 409 Conflict
        else New Department
            UseCase->>DeptRepo: Save Department
            UseCase->>DeptIndexRepo: Create Index
            UseCase->>ActivityRepo: Log Activity
            UseCase->>PubSub: Publish Event
            UseCase-->>Controller: Department Created
            Controller-->>Client: 201 Created
        end
    end

4.3. Department Update Process

The update process ensures data consistency across department and index records:

flowchart TB
    A[Update Request] --> B{Validate Input}
    B -->|Invalid| C[Return Error]
    B -->|Valid| D[Check Permissions]
    D --> E{Has Access?}
    E -->|No| F[403 Forbidden]
    E -->|Yes| G[Load Department]
    G --> H[Apply Changes]
    H --> I[Update Department]
    I --> J[Update Index]
    J --> K[Log Activity]
    K --> L[Publish Event]
    L --> M[Return Success]

4.4. Department Lifecycle Management

Departments follow a defined lifecycle with status transitions:

stateDiagram-v2
    [*] --> Active: Create
    Active --> Inactive: Disable
    Inactive --> Active: Enable
    Active --> Deleted: Delete
    Inactive --> Deleted: Delete
    Deleted --> [*]
    
    note right of Active: Normal operations
    note right of Inactive: Temporarily disabled
    note right of Deleted: Soft delete

5. Department Index Management

Department indexes maintain associations between departments and other entities (users, sites, questionnaires):

5.1. Index Structure

graph TB
    subgraph "Department Index"
        A[Department ID]
        B[Organization ID]
        C[User Array]
        D[Site Array]
        E[Questionnaire Array]
        F[Status]
    end
    
    C --> G[User Service]
    D --> H[Site Service]
    E --> I[Questionnaire Service]

5.2. User Assignment Flow

sequenceDiagram
    participant Client
    participant Controller
    participant UseCase
    participant UserService
    participant DeptIndexRepo
    participant NotificationService
    
    Client->>Controller: POST /insert-user
    Controller->>UseCase: Assign User
    UseCase->>UserService: Validate User
    UserService-->>UseCase: User Details
    
    UseCase->>DeptIndexRepo: Load Indexes
    UseCase->>DeptIndexRepo: Update User Arrays
    UseCase->>NotificationService: Send Assignment Email
    UseCase-->>Controller: Assignment Complete
    Controller-->>Client: 200 OK

5.3. Site Association Management

Sites can be associated with departments for location-based operations:

flowchart LR
    A[Site Association Request] --> B[Validate Site IDs]
    B --> C[Load Department Indexes]
    C --> D[Check Existing Associations]
    D --> E[Update Site Arrays]
    E --> F[Sync with Site Service]
    F --> G[Log Changes]
    G --> H[Return Updated Indexes]

5.4. Questionnaire Mapping

Questionnaires are mapped to departments for survey distribution:

graph TB
    A[Questionnaire] --> B{Distribution Type}
    B -->|Department Level| C[Map to Departments]
    B -->|Site Level| D[Map via Sites]
    B -->|User Level| E[Map via Users]
    
    C --> F[Update Department Index]
    D --> G[Query Site Departments]
    E --> H[Query User Departments]
    
    G --> F
    H --> F
    F --> I[Questionnaire Available]

6. Department Groups

Department groups provide logical organization of related departments:

6.1. Group Management Flow

sequenceDiagram
    participant Client
    participant Controller
    participant GroupUseCase
    participant GroupRepo
    participant DeptRepo
    
    Client->>Controller: POST /group
    Controller->>GroupUseCase: Create Group
    GroupUseCase->>DeptRepo: Validate Departments
    DeptRepo-->>GroupUseCase: Department Details
    
    GroupUseCase->>GroupRepo: Save Group
    GroupRepo-->>GroupUseCase: Group Created
    GroupUseCase-->>Controller: Success
    Controller-->>Client: 201 Created

6.2. Group Structure

classDiagram
    class DepartmentGroup {
        +string id
        +string organizationID
        +string name
        +string description
        +Array~Department~ departments
        +string status
        +Date createdAt
        +Date updatedAt
        +addDepartment(dept)
        +removeDepartment(deptId)
        +toggleStatus()
    }
    
    class Department {
        +string departmentID
        +string name
    }
    
    DepartmentGroup "1" o-- "*" Department : contains

6.3. Group Operations

Groups support various operations for flexible department organization:

graph TB
    A[Department Group] --> B[Create Group]
    A --> C[Update Group]
    A --> D[Delete Group]
    A --> E[Toggle Status]
    
    B --> F[Validate Departments]
    C --> G[Update Metadata]
    C --> H[Modify Members]
    D --> I[Soft Delete]
    E --> J[Active/Inactive]
    
    F --> K[Save to Database]
    G --> K
    H --> K
    I --> K
    J --> K

7. Authentication & Authorization

7.1. Authentication Flow

sequenceDiagram
    participant Client
    participant AuthMiddleware
    participant JWT
    participant UserService
    participant Controller
    
    Client->>AuthMiddleware: Request + Token
    AuthMiddleware->>JWT: Verify Token
    
    alt Invalid Token
        JWT-->>AuthMiddleware: Invalid
        AuthMiddleware-->>Client: 401 Unauthorized
    else Valid Token
        JWT-->>AuthMiddleware: Decoded Payload
        AuthMiddleware->>UserService: Get User Details
        UserService-->>AuthMiddleware: User Object
        AuthMiddleware->>Controller: Request + User Context
        Controller-->>Client: Response
    end

7.2. Role-Based Access Control

The system implements hierarchical role-based access control:

graph TB
    A[User Roles] --> B[Auditor - Level 1]
    A --> C[Supervisor - Level 10]
    A --> D[Admin - Level 99]
    A --> E[Superadmin/GM - Level 100]
    
    B --> F[View Own Departments]
    C --> G[View/Edit Assigned Departments]
    D --> H[Manage All Departments]
    E --> I[Cross-Organization Access]

7.3. Permission Checking

flowchart TB
    A[Request] --> B{Check User Level}
    B -->|Level < 99| C[Check Department Access]
    B -->|Level >= 99| D[Organization Wide Access]
    
    C --> E{User in Department?}
    E -->|No| F[403 Forbidden]
    E -->|Yes| G[Check Operation]
    
    D --> G
    G --> H{Operation Allowed?}
    H -->|No| F
    H -->|Yes| I[Execute Operation]

7.4. Data Visibility Rules

Data visibility is determined by user role and department assignments:

graph LR
    A[User Role] --> B{Visibility Level}
    B -->|SPECIFIC_DEPT| C[Only Assigned Departments]
    B -->|SPECIFIC_DEPT_SITE| D[Assigned Departments & Sites]
    B -->|ORGANIZATION| E[All Organization Data]
    B -->|CROSS_ORG| F[Multiple Organizations]
    
    C --> G[Filter Results]
    D --> G
    E --> G
    F --> G

8. Data Models & Relationships

8.1. Entity Relationship Diagram

erDiagram
    Organization ||--o{ Department : has
    Department ||--|| DepartmentIndex : maintains
    DepartmentIndex ||--o{ User : contains
    DepartmentIndex ||--o{ Site : contains
    DepartmentIndex ||--o{ Questionnaire : contains
    DepartmentGroup ||--o{ Department : groups
    Organization ||--o{ DepartmentGroup : owns
    User }o--|| UserRole : has
    Department ||--o{ Activity : generates
    
    Organization {
        string organizationID
        string name
        string status
    }
    
    Department {
        string departmentID
        string organizationID
        string name
        string description
        string email
        string status
    }
    
    DepartmentIndex {
        string departmentID
        string organizationID
        array users
        array sites
        array questionnaires
        string status
    }
    
    DepartmentGroup {
        string id
        string organizationID
        string name
        string description
        array departments
        string status
    }
    
    User {
        string userID
        string email
        string name
        number level
    }
    
    Site {
        string siteID
        string name
        object location
    }
    
    Questionnaire {
        string questionnaireID
        string title
        string type
    }

8.2. Data Flow Architecture

graph TB
    subgraph "Client Applications"
        A[Web App]
        B[Mobile App]
        C[Admin Portal]
    end
    
    subgraph "API Gateway"
        D[Load Balancer]
        E[API Departments]
    end
    
    subgraph "Core Services"
        F[Department Service]
        G[Index Service]
        H[Group Service]
    end
    
    subgraph "Data Layer"
        I[(MongoDB)]
        J[(Redis Cache)]
        K[(Firebase)]
    end
    
    subgraph "External Services"
        L[User Service]
        M[Site Service]
        N[Questionnaire Service]
        O[Notification Service]
    end
    
    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    E --> G
    E --> H
    F --> I
    G --> I
    H --> I
    F --> J
    F --> L
    G --> M
    G --> N
    F --> O

9. Error Handling & Validation

9.1. Validation Pipeline

flowchart TB
    A[Request Data] --> B[Schema Validation]
    B --> C{Valid Schema?}
    C -->|No| D[400 Bad Request]
    C -->|Yes| E[Business Rules]
    E --> F{Rules Pass?}
    F -->|No| G[422 Unprocessable]
    F -->|Yes| H[Data Sanitization]
    H --> I[Process Request]

9.2. Error Handling Strategy

graph TB
    A[Error Occurs] --> B{Error Type}
    B -->|Validation| C[400 Response]
    B -->|Not Found| D[404 Response]
    B -->|Unauthorized| E[401 Response]
    B -->|Forbidden| F[403 Response]
    B -->|Conflict| G[409 Response]
    B -->|Server Error| H[500 Response]
    
    C --> I[Log Warning]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> J[Log Error]
    
    I --> K[Return Error Response]
    J --> K

9.3. Validation Rules

Department Validation:

  • Name: Required, 3-100 characters
  • Email: Optional, valid email format
  • Description: Optional, max 500 characters
  • Department ID: Alphanumeric with hyphens

User Assignment Validation:

  • Email: Required, valid format
  • Role: Must be valid role from enum
  • Department IDs: Must exist in organization

Bulk Upload Validation:

  • File format: Excel/CSV only
  • File size: Max 10MB
  • Row limit: 1000 records per upload
  • Required columns based on operation type

10. Conclusion

The API Departments service is a critical component of the Nimbly ecosystem, providing robust department management capabilities with a focus on scalability, security, and maintainability. The clean architecture, comprehensive error handling, and extensive monitoring ensure reliable operation in production environments.

The service’s modular design allows for easy extension and modification, while the thorough documentation and type safety reduce onboarding time for new developers. With its event-driven architecture and well-defined integration points, the service seamlessly fits into the larger microservices ecosystem.

Document Version: 1.0.0
Last Updated: 2024
Total Characters: ~35,000+

Graph View

Backlinks