Skip to main content

Business Module Documentation

Overview​

The Business Module provides comprehensive functionality for managing business entities, their locations, and operating hours within the Alethian API system. This module handles all business-related operations including CRUD operations, location management, provider affiliations, and operating hours scheduling.

Architecture​

The module follows a layered architecture pattern:

  • Controller Layer: Handles HTTP requests and responses
  • Service Layer: Contains business logic and data operations
  • Entity Layer: Defines data models and database relationships
  • DTO Layer: Provides data transfer objects for API communication

Dependencies​

  • TypeORM: Database ORM for entity management
  • NestJS: Framework for building scalable applications
  • Azure Blob Storage: File storage service for business logos
  • Swagger: API documentation and testing
  • Prometheus: Metrics collection and monitoring

Business Controller​

Base URL​

/business

Authentication​

All endpoints require authentication via AuthGuard and include:

  • Bearer Token: JWT authentication token
  • User Type Header: user-type: business

Endpoints​

1. Get Business Details​

GET /business/:id

Description: Retrieve detailed information about a specific business by ID.

Parameters:

  • id (string): Business ID

Response:

{
  "message": "Business Information fetched successfully",
  "status": "success",
  "data": {
    "id": 1,
    "name": "Example Business",
    "email": "contact@example.com",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001"
  }
}

Error Handling: Returns undefined and logs error if business not found.

2. Get Business Locations​

GET /business/locations/:id

Description: Retrieve all locations associated with a specific business.

Parameters:

  • id (string): Business ID

Response:

{
  "message": "Business locations fetched successfully",
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Main Office",
      "address": "123 Main St",
      "city": "New York",
      "state": "NY"
    }
  ]
}

Error Handling: Returns undefined and logs error if locations not found.

3. Update Business Details​

PATCH /business/:id

Description: Update information for a specific business.

Parameters:

  • id (string): Business ID

Request Body (EditBusinessDto):

{
  "name": "Updated Business Name",
  "email": "updated@business.com",
  "npiLicense": "1234567890",
  "taxId": "12-3456789",
  "website": "https://updatedbusiness.com",
  "description": "Updated business description",
  "address": "456 Updated St",
  "city": "Updated City",
  "state": "CA",
  "zipCode": "54321",
  "twitterLink": "https://twitter.com/updatedbusiness",
  "instagramLink": "https://instagram.com/updatedbusiness",
  "youtubeLink": "https://youtube.com/updatedbusiness"
}

Response:

{
  "message": "Business updated successfully",
  "status": "success",
  "data": {
    "id": 1,
    "name": "Updated Business Name"
  }
}

Error Handling: Returns undefined and logs error if update fails.

4. Create Business Location​

POST /business/location/:businessId/

Description: Create a complete business location with all information in one request.

Parameters:

  • businessId (string): Business ID

Request Body (CompleteBusinessLocationDto):

{
  "generalInfo": {
    "name": "New Location",
    "timezone": "America/New_York",
    "npi": "1234567890",
    "taxId": "12-3456789",
    "stateLicense": "MD12345",
    "phone": "(555) 123-4567",
    "fax": "(555) 123-4568",
    "email": "info@example.com",
    "website": "https://example.com",
    "adminName": "John Doe",
    "adminPhone": "(555) 123-4569",
    "adminEmail": "admin@example.com"
  },
  "address": {
    "address": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA",
    "suite": "Suite 100"
  }
}

File Upload: Supports logo upload via multipart/form-data

Response:

{
  "message": "Complete business location created successfully",
  "status": "success",
  "data": {
    "locationId": 1,
    "isComplete": true,
    "logoBlobId": 123
  }
}

Error Handling: Returns undefined and logs error if creation fails.

5. Update Business Location​

PUT /business/location/:locationId/update

Description: Update an existing business location.

Parameters:

  • locationId (string): Location ID

Request Body: Form data with location information

File Upload: Supports logo upload via multipart/form-data

Response:

{
  "message": "Business location updated successfully",
  "status": "success",
  "data": {
    "id": 1,
    "name": "Updated Location Name"
  }
}

Error Handling: Returns undefined and logs error if update fails.

6. Get Business Location Providers​

GET /business/location/:locationId/providers

Description: Retrieve all providers affiliated with a specific business location.

Parameters:

  • locationId (string): Location ID

Response:

{
  "message": "Providers fetched successfully",
  "status": "success",
  "data": {
    "providers": [
      {
        "id": 1,
        "firstName": "John",
        "lastName": "Doe",
        "email": "john.doe@example.com",
        "telehealthLink": "https://telehealth.example.com"
      }
    ]
  }
}

Error Handling: Returns undefined and logs error if providers not found.

7. Get Business Location Operating Hours​

GET /business/location/:locationId/operating-hours

Description: Retrieve operating hours for a specific business location.

Parameters:

  • locationId (string): Location ID

Response:

{
  "message": "Operating hours fetched successfully",
  "status": "success",
  "data": [
    {
      "id": 1,
      "day": "Monday",
      "start_time": "09:00",
      "end_time": "17:00"
    }
  ]
}

Error Handling: Returns undefined and logs error if operating hours not found.

8. Add Operating Hours​

POST /business/operating-hours/add

Description: Add new operating hours for a business location.

Request Body (AddOperatingHoursDto):

{
  "businessLocationId": 1,
  "operatingHours": [
    {
      "day": "Monday",
      "start_time": "09:00",
      "end_time": "17:00"
    },
    {
      "day": "Tuesday",
      "start_time": "09:00",
      "end_time": "17:00"
    }
  ]
}

Response:

{
  "message": "Operating hours added successfully",
  "status": "success",
  "data": {
    "businessLocationId": 1,
    "addedCount": 2,
    "operatingHours": [
      {
        "id": 1,
        "day": "Monday",
        "start_time": "09:00",
        "end_time": "17:00"
      }
    ]
  }
}

Validation: Prevents duplicate day entries for the same location.

Error Handling: Returns undefined and logs error if addition fails.

9. Update Operating Hours​

PUT /business/operating-hours/update

Description: Update an existing operating hours entry.

Request Body (UpdateOperatingHoursDto):

{
  "id": 1,
  "day": "Monday",
  "start_time": "08:00",
  "end_time": "18:00"
}

Response:

{
  "message": "Operating hours updated successfully",
  "status": "success",
  "data": {
    "id": 1,
    "day": "Monday",
    "start_time": "08:00",
    "end_time": "18:00"
  }
}

Validation: Prevents day conflicts with other entries at the same location.

Error Handling: Returns undefined and logs error if update fails.

10. Delete Operating Hours​

DELETE /business/operating-hours/delete

Description: Delete an existing operating hours entry.

Request Body (DeleteOperatingHoursDto):

{
  "id": 1
}

Response:

{
  "message": "Operating hours deleted successfully",
  "status": "success",
  "data": {
    "id": 1
  }
}

Error Handling: Returns undefined and logs error if deletion fails.

Business Service​

Overview​

The BusinessService class contains all business logic for the module, handling data operations, validation, and business rules.

Dependencies​

  • BusinessRepository: Manages business entity operations
  • BusinessLocationRepository: Manages location entity operations
  • AgentBusinessLocationAffiliationRepository: Manages provider affiliations
  • OperatingHoursRepository: Manages operating hours operations
  • AzureBlobService: Handles file uploads and storage

Methods​

1. getBusinessDetail(id: string)​

Retrieves business information by ID.

Parameters:

  • id (string): Business ID

Returns: Promise<GeneralResponse<BusinessResponseDto>>

Business Logic:

  • Fetches business from database by ID
  • Returns standardized response format

2. getBusinessLocations(id: string)​

Retrieves all locations for a specific business.

Parameters:

  • id (string): Business ID

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Fetches locations with business relationship
  • Returns standardized response format

3. editBusiness(id: string, data: EditBusinessDto)​

Updates business information.

Parameters:

  • id (string): Business ID
  • data (EditBusinessDto): Update data

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates business exists
  • Updates business with new data
  • Returns standardized response format

Validation:

  • Business must exist before update

4. createBusinessLocation(businessId: string, data: CompleteBusinessLocationDto)​

Creates a complete business location.

Parameters:

  • businessId (string): Business ID
  • data (CompleteBusinessLocationDto): Location data

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates business exists
  • Handles logo upload to Azure Blob Storage
  • Creates location with all required information
  • Returns standardized response format

Features:

  • Logo file upload and storage
  • Complete location information creation
  • Automatic admin name parsing

Validation:

  • Business must exist before location creation

5. updateBusinessLocation(locationId: string, data: UpdateBusinessLocationDto)​

Updates an existing business location.

Parameters:

  • locationId (string): Location ID
  • data (UpdateBusinessLocationDto): Update data

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates location exists
  • Updates location with new data
  • Returns standardized response format

Validation:

  • Location must exist before update

6. getBusinessLocationProviders(businessLocationId: string)​

Retrieves providers affiliated with a business location.

Parameters:

  • businessLocationId (string): Location ID

Returns: Promise<GeneralResponse<BusinessLocationProvidersResponseDto>>

Business Logic:

  • Fetches provider affiliations
  • Includes provider details and telehealth links
  • Returns standardized response format

7. getBusinessLocationOperatingHours(businessLocationId: string)​

Retrieves operating hours for a business location.

Parameters:

  • businessLocationId (string): Location ID

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Fetches operating hours by location
  • Returns standardized response format

8. addOperatingHours(data: AddOperatingHoursDto)​

Adds new operating hours for a business location.

Parameters:

  • data (AddOperatingHoursDto): Operating hours data

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates business location exists
  • Prevents duplicate day entries
  • Creates multiple operating hours entries
  • Returns standardized response format

Validation:

  • Business location must exist
  • No duplicate days allowed for same location

9. updateOperatingHours(data: UpdateOperatingHoursDto)​

Updates existing operating hours.

Parameters:

  • data (UpdateOperatingHoursDto): Update data

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates operating hours entry exists
  • Prevents day conflicts with other entries
  • Updates operating hours information
  • Returns standardized response format

Validation:

  • Operating hours entry must exist
  • No day conflicts allowed with other entries

10. deleteOperatingHours(data: any)​

Deletes operating hours entry.

Parameters:

  • data (any): Delete data with ID

Returns: Promise<GeneralResponse<any>>

Business Logic:

  • Validates operating hours entry exists
  • Deletes the entry
  • Returns standardized response format

Validation:

  • Operating hours entry must exist before deletion

Data Models​

Business Entity​

Core business information including contact details, licensing, and location data.

Business Location Entity​

Location-specific information including address, contact details, and administrative information.

Operating Hours Entity​

Scheduling information for business locations with day, start time, and end time.

Agent Business Location Affiliation Entity​

Relationship between healthcare providers and business locations.

Error Handling​

Controller Level​

  • All endpoints include try-catch blocks
  • Errors are logged with structured logging
  • Returns undefined on error (graceful degradation)

Service Level​

  • Throws NotFoundException for missing entities
  • Validates business rules before operations
  • Returns standardized error responses

Logging​

  • Structured logging with service labels
  • Error context and method information
  • Prometheus metrics integration

Security​

Authentication​

  • JWT Bearer token required
  • User type validation
  • Route-level guards

Authorization​

  • Business ownership validation
  • Location access control
  • Provider affiliation verification

Performance​

Database Optimization​

  • Efficient entity relationships
  • Indexed queries for common operations
  • Repository pattern implementation

File Handling​

  • Azure Blob Storage integration
  • Asynchronous file uploads
  • Optimized image processing

Testing​

Test Coverage​

  • Controller Tests: 20 tests covering all endpoints
  • Service Tests: 22 tests covering all business logic
  • Mock Dependencies: Comprehensive mocking strategy
  • Error Scenarios: Error handling and edge cases

Test Structure​

  • Unit tests for individual components
  • Mock repositories and external services
  • Validation of business rules
  • Error handling verification

API Documentation​

Swagger Integration​

  • Comprehensive endpoint documentation
  • Request/response schema definitions
  • Example data and validation rules
  • Interactive API testing interface

Response Format​

All endpoints return standardized responses:

{
  "message": "Operation description",
  "status": "success|error",
  "data": {}
}

Monitoring​

Prometheus Integration​

  • Method execution counters
  • Performance metrics
  • Business operation tracking

Logging​

  • Structured logging with labels
  • Error tracking and monitoring
  • Audit trail for business operations

Scalability Considerations​

  • Database query optimization
  • Caching strategies
  • Microservice architecture support
  • Horizontal scaling capabilities

Support and Maintenance​

Code Quality​

  • TypeScript strict mode
  • ESLint configuration
  • Prettier formatting
  • Comprehensive test coverage

Documentation​

  • Inline code documentation
  • API endpoint documentation
  • Business logic documentation
  • Deployment and configuration guides

Version History​

Current Version: 2.0.0​

  • Complete business location management
  • Operating hours CRUD operations
  • Provider affiliation management
  • Comprehensive error handling
  • Full test coverage

Previous Versions​

  • 1.0.0: Basic business management
  • 1.5.0: Location management added