Compass - Nimbly Documentation

Sites Backend

8 min read

1. Overview

The site management system is a core component of the Nimbly Web API that handles the creation, retrieval, update, and management of physical locations (sites) where audits are performed. The system includes sophisticated features for site supervisor management, department associations, [bulk operationss](../Bulk Operation/BulkOperationOverview.md), and integration with [schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) management systems. Sites serve as the primary organizational unit for audit activities and are deeply integrated with user [permissions](../Settings/Access control/AccessControlOverview.md), departments, and reporting functionalities.

2. Libraries and Dependencies

The following libraries and modules are utilized throughout the site management implementation:

Core Framework & Middleware

  • Express.js: Web framework for routing and middleware management
  • jsonwebtoken: JWT token validation and authentication
  • firebase-admin: Firebase Realtime Database integration for site data persistence

Nimbly Internal Packages

  • @nimbly-technologies/nimbly-common: Shared types, interfaces, and enumerators including:
    • Permission and RoleResources enums for [access control](../Settings/Access control/AccessControlOverview.md)
    • Core entity types (Site, User, Department, etc.)
    • Error codes and utility functions
  • @nimbly-technologies/nimbly-backend-utils: Backend utilities including:
    • Logging utilities
    • Pagination and query options
    • Middleware handlers (AuthMiddleware, validatorHandler, expressMiddlewareHandler)
    • MongoDB query utilities
  • @nimbly-technologies/entity-node: Repository interfaces for data access:
    • ISiteRepository
    • IDepartmentRepository
    • IDepartmentIndexRepository
    • IUserRepository
    • IPubsubRepository
    • ISiteScheduleIndexRepository

Utility Libraries

  • moment & moment-timezone: Date/time manipulation and timezone handling
  • ramda: Functional programming utilities (particularly uniq function)
  • xlsx parsing utilities: Custom parseXlsx helper for bulk upload functionality

Domain-Specific Dependencies

  • Google Timezone API: Integration for timezone validation and management
  • Activity System: Site activity tracking and audit logging
  • [Schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) Management: Integration with [schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) creation and management
  • SKU [Schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) APIs: Product [schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) management integration

3. API Endpoints

Site Management Endpoints

MethodEndpointDescriptionAuth Required[Permissions](../Settings/Access control/AccessControlOverview.md)
GET/sites/Retrieve all accessible sitesYesBased on user role/department
GET/sites/paginatePaginated site listing with searchYesBased on user role/department
GET/sites/site-ownersGet unique site ownersYesBased on user role/department
GET/sites/:siteIDGet specific site detailsYesSite access validation
GET/sites/:siteID/populatedGet site with populated referencesYesSite access validation
POST/sites/Create new siteYesADMIN_SITES_ALL.Create
POST/sites/bulk-uploadBulk site creation via ExcelYesAdmin role required
POST/sites/internal/multi-siteInternal: Get multiple sitesYesSUPERADMIN only
POST/sites/internal/Internal: Get all sitesYesSUPERADMIN only
POST/sites/update-site-side-effectHandle site update side effectsYesBased on user role
PUT/sites/:siteIDUpdate existing siteYesSite edit permission
GET/sites/internal/:siteIDInternal: Get site by IDYesSUPERADMIN only

Site Supervisors Endpoints

MethodEndpointDescriptionAuth Required[Permissions](../Settings/Access control/AccessControlOverview.md)
GET/site-supervisors/Get site supervisorsYesBased on department access

4. Architecture and Flow Analysis

4.1 Request Flow Overview

graph TD
    A[Client Request] --> B[Express Router]
    B --> C[Auth Middleware]
    C --> D[Permission Check]
    D --> E[Validation]
    E --> F[Controller]
    F --> G[Use Case]
    G --> H[Repository]
    H --> I[Database]
    G --> J[Side Effects]
    J --> K[Pubsub Events]
    J --> L[Schedule Updates]
    F --> M[Response]

4.2 Site Creation Flow

The site creation process involves multiple validation steps and integrations:

sequenceDiagram
    participant Client
    participant Router
    participant Controller
    participant UseCase
    participant Repository
    participant DeptIndex
    participant Pubsub
    
    Client->>Router: POST /sites/
    Router->>Controller: create(data)
    Controller->>UseCase: create(ctx, orgID, data)
    UseCase->>UseCase: validateSiteName()
    UseCase->>UseCase: validateLocation()
    UseCase->>UseCase: isSiteValidated()
    UseCase->>Repository: create(site, orgID)
    Repository-->>UseCase: siteID
    UseCase->>DeptIndex: insertToDepartmentIndex()
    UseCase->>Pubsub: publish('activity:create')
    UseCase-->>Controller: siteID
    Controller-->>Client: Response

4.3 Site Update Flow with Side Effects

Site updates trigger complex side effects affecting schedules and department associations:

graph LR
    A[Site Update Request] --> B[Validation]
    B --> C[Update Site Data]
    C --> D[Check Side Effects]
    D --> E{Site Disabled?}
    E -->|Yes| F[Disable Schedules]
    E -->|No| G{Team Changed?}
    G -->|Yes| H[Update Schedule Auditors]
    G -->|No| I[Complete Update]
    F --> J[Disable SKU Schedules]
    H --> K[Clone/Modify Schedules]
    K --> L[Update Statistics]
    I --> M[Publish Events]
    J --> M
    L --> M

5. Detailed Implementation Analysis

5.1 Site Controller (src/controllers/siteController.ts)

The SiteController class serves as the primary interface between HTTP requests and business logic:

Key Methods:

findAll: Retrieves all sites accessible to the requesting user

public async findAll({ context, payload }: findAllParams) {
    const sites = await this.siteUsecase.findAll(
        context, 
        payload.query?.with_disabled === 'true'
    );
    return response(sites, null);
}

findAllPaginate: Provides paginated site listing with search capabilities

  • Supports filtering by status (active/disabled)
  • Implements full-text search across site names, team members, and departments
  • Returns total counts for active and disabled sites

create: Handles new site creation with comprehensive validation

  • Validates site name uniqueness
  • Ensures location data consistency
  • Creates department associations
  • Publishes activity events

bulkUpload: Processes Excel files for bulk site creation

  • Parses Excel data using custom middleware
  • Validates each row before processing
  • Returns detailed error information for failed entries

update: Manages site modifications with side effect handling

  • Tracks changes for activity logging
  • Handles site enable/disable operations
  • Triggers side effect processing for schedule updates

updateSiteSideEffect: Processes cascading effects of site updates

  • Manages schedule modifications when team changes
  • Handles department association updates
  • Updates SKU schedules when sites are disabled

5.2 Site Use Case (src/domains/site/usecase/site.usecase.ts)

The SiteUsecase class implements complex business logic for site management:

Core Validation Logic:

isSiteValidated: Comprehensive validation ensuring data integrity

public async isSiteValidated(
    ctx: Context<UserAuth>,
    site: Partial<Site_Firebase> | Partial<CreateSiteRequest>
): Promise<boolean> {
    // Validates:
    // - Assigned auditor exists in organization
    // - Created/updated by users exist
    // - Team members are valid users
    // - Supervisors exist and have proper associations
    // - Departments are valid and active
}

Access Control Implementation:

findAll: Implements role-based site filtering

  • Account holders and superadmins see all organization sites
  • Other users see sites based on department associations
  • Falls back to owner-based filtering when no department access

findAllPaginate: Advanced querying with MongoDB

  • Constructs complex queries based on user permissions
  • Implements regex-based search with special character escaping
  • Provides separate counts for active and disabled sites

Side Effect Management:

updateSiteSideEffect: Orchestrates complex state changes

public async updateSiteSideEffect(
    context: Context<UserAuth>,
    preUpdateSite: Partial<Site>,
    postUpdateSite: Partial<Site>
): Promise<void> {
    // Handles:
    // 1. Schedule disabling when site is disabled
    // 2. Schedule auditor updates when team changes
    // 3. Department synchronization
    // 4. SKU schedule management
    // 5. Activity logging for all changes
}

The implementation includes sophisticated logic for:

  • Determining which schedules need updates
  • Calculating proper end dates based on timezone
  • Creating new schedules when team composition changes
  • Maintaining schedule statistics accuracy

5.3 Site Supervisors Use Case (src/domains/siteSupervisors/usecase.ts)

Manages the retrieval of site supervisors with department-based access control:

findSiteSupervisors: Retrieves supervisors with proper visibility

  • Filters supervisors based on department access
  • Populates user and department information
  • Handles multi-site supervisor queries efficiently

5.4 Repository Layer

Firebase Repository (src/services/site.service.ts)

Provides direct Firebase Realtime Database operations:

  • CRUD operations for site entities
  • Questionnaire association management
  • Global site queries for cross-organization operations

MongoDB Repository Integration

The system uses MongoDB repositories through the entity-node package:

  • ISiteRepository: Core site data operations
  • IDepartmentIndexRepository: Department-site associations
  • IUserRepository: User validation and retrieval

6. Data Models and Interfaces

6.1 Core Site Models

Site Interface (src/models/site.ts):

interface ISite {
    key: string;
    name: string;
    subtitle: string;
    photoURL: string;
    country: string;
    province: string;
    city: string;
    locationName: string;
    address: string;
    coordinates: null | Coordinates;
    reportsPerPeriod: number;
    assignedQuestionnaire: string;
    assignedAuditor: string;
    emailTargets: string[];
    owner: string;
    departments: { [deptKey: string]: boolean };
    team: string[];
    children: SiteChild[];
    signatures: number;
    isMultiSite: boolean;
    timezone: string | null;
    utcOffset: number | null;
}

SiteBulkUpload Model (src/models/siteBulkUpload.ts): Defines the Excel import format for bulk operations with fields for all site properties.

QuerySiteSupervisors Model (src/models/querySiteSupervisors.ts): Handles flexible query parameter parsing for supervisor searches.

6.2 Request/Response Types

The system uses strongly-typed function parameters:

  • findAllParams: Query parameters for site listing
  • createParams: Site creation request structure
  • updateParams: Site modification payload
  • UpdateSiteSideEffectParam: Side effect processing data

7. Key Implementation Patterns

7.1 Permission-Based Filtering

The system implements sophisticated permission checks at multiple levels:

  1. Route Level: Middleware checks for basic authentication
  2. Controller Level: Role-based access validation
  3. Use Case Level: Department and ownership-based filtering
  4. Repository Level: Organization-scoped queries

7.2 Side Effect Management

Site updates trigger cascading effects managed through:

  • Event publishing for activity tracking
  • Schedule synchronization for team changes
  • Department index updates for association changes
  • Statistics recalculation for reporting accuracy

7.3 Bulk Operations

The bulk upload feature implements:

  • Excel parsing with validation
  • Transactional-style error handling
  • Detailed error reporting per row
  • Timezone resolution via Google API

7.4 Data Consistency

Ensures consistency through:

  • Name uniqueness validation
  • Location data completeness checks
  • User and department existence validation
  • Synchronized department associations

8. Integration Points

8.1 Schedule Management

  • Automatic schedule updates when sites are modified
  • Schedule disabling when sites are deactivated
  • Auditor reassignment for team changes

8.2 Activity Tracking

  • Comprehensive audit logging for all operations
  • Snapshot-based change tracking
  • Permission-based activity types

8.3 Department System

  • Bi-directional site-department associations
  • Department-based access control
  • Supervisor department validation

8.4 Notification System

  • Email target management for site notifications
  • Integration with report completion alerts
  • Supervisor notification capabilities

9. Error Handling and Validation

9.1 Validation Layers

  1. Request Validation: Schema-based validation using Validator class
  2. Business Logic Validation: Name uniqueness, data completeness
  3. Relationship Validation: User, department, and team member existence
  4. Permission Validation: Role and department-based access checks

9.2 Error Responses

Standardized error handling with specific error codes:

  • INVALID: Validation failures
  • NOT_FOUND: Resource not found
  • UNAUTHORIZED: Permission denied
  • INTERNAL: System errors

10. Performance Considerations

10.1 Query Optimization

  • Indexed queries for pagination
  • Aggregation pipelines for complex searches
  • Caching of frequently accessed data

10.2 [Bulk Operation](../Bulk Operation/BulkOperationOverview.md) Efficiency

  • Batch processing for bulk uploads
  • Parallel promise execution for related updates
  • Optimized department index updates

10.3 Side Effect Processing

  • Asynchronous event publishing
  • Batched [schedule](../Schedule/Schedule Listing/ScheduleListingOverview.md) updates
  • Efficient statistics recalculation

11. Security Considerations

11.1 Authentication

  • JWT-based authentication for all endpoints
  • Token validation middleware

11.2 Authorization

  • Role-based [access control](../Settings/Access control/AccessControlOverview.md) (RBAC)
  • Department-based [visibility](../Settings/Data Visibility/DataVisibilityOverview.md)
  • Owner-based [permissions](../Settings/Access control/AccessControlOverview.md) for non-admin users

11.3 Data Validation

  • Input sanitization for search queries
  • Regex escape for preventing injection
  • Strict type checking throughout

12. Conclusion

The site management system represents a sophisticated implementation of location-based resource management with comprehensive [access control](../Settings/Access control/AccessControlOverview.md), data validation, and integration capabilities. The architecture demonstrates best practices in:

  • Clean architecture with clear separation of concerns
  • Comprehensive validation and error handling
  • Event-driven side effect management
  • Performance-optimized data access patterns
  • Flexible permission-based [access control](../Settings/Access control/AccessControlOverview.md)

The system successfully handles complex business requirements while maintaining code clarity and extensibility.

Graph View

Backlinks