> For the complete documentation index, see [llms.txt](https://docs.beeoclock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.beeoclock.com/services/business-profile.md).

# Business Profile

## Overview

The Business Profile Management module is a comprehensive component of the Bee O'clock panel service that handles complete business information, settings, and configuration management. It provides a centralized system for businesses to manage their profile information, operational settings, media assets, and customer-facing configurations.

## Purpose

This module enables businesses to:

* **Manage Business Information**: Complete business details, descriptions, and featured content
* **Configure Operational Settings**: Booking, payment, notification, and business settings
* **Handle Media Assets**: Logo, banners, and gallery images with optimization
* **Control Public Presence**: Published profile visibility and public page settings
* **Manage Multiple Locations**: Address management with geospatial support
* **Configure Communication**: Contact information and social media integration
* **Set Operating Hours**: Regular and special schedule management
* **Customize User Experience**: Panel and public page customizations

## Key Features

### ✅ Comprehensive Profile Management

* **Business Information**: Name, description, features, and facilities
* **Contact Management**: Multiple contact types with primary designation
* **Address Management**: Multiple locations with geospatial coordinates
* **Social Integration**: Social media platform links and profiles

### ✅ Advanced Settings Configuration

* **Booking Settings**: Customer booking rules and automation
* **Business Settings**: Timezone, currency, language, and format preferences
* **Payment Settings**: Multiple payment gateway configurations
* **Notification Settings**: Communication preferences and templates
* **Panel Settings**: Administrative interface customization
* **Public Page Settings**: Customer-facing page configuration

### ✅ Professional Media Management

* **Business Logo**: Primary brand identifier with multiple sizes
* **Banner Images**: Promotional content with landscape optimization
* **Gallery Management**: Portfolio showcase with aspect ratio preservation
* **Automatic Optimization**: Image compression and thumbnail generation
* **CDN Integration**: Global delivery and performance optimization

### ✅ Flexible Schedule Management

* **Regular Schedules**: Daily operating hours with break periods
* **Special Schedules**: Holiday hours and special events
* **Timezone Support**: Multi-timezone business operations
* **Break Management**: Detailed break period configuration

### ✅ Multi-Settings Architecture

* **Hierarchical Configuration**: Organized settings by functional area
* **Validation Framework**: Comprehensive validation for all settings
* **Partial Updates**: Update specific settings without affecting others
* **Default Values**: Sensible defaults for new business profiles

### ✅ Advanced Data Management

* **Publication Control**: Manage profile visibility to customers
* **State Tracking**: Complete audit trail of all changes
* **Multi-tenant Security**: Complete tenant isolation and security
* **Reference Integrity**: Maintained relationships between profile and media

## Architecture

The module follows Clean Architecture principles with clear separation of concerns:

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   API Layer     │    │  Application    │    │   Domain        │
│                 │    │     Layer       │    │    Layer        │
│ • REST API      │───▶│ • Use Cases     │───▶│ • Entities      │
│ • Controllers   │    │ • Commands      │    │ • Value Objects │
│ • DTOs          │    │ • Queries       │    │ • Business Rules│
│ • File Upload   │    │ • Validators    │    │ • Settings      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Infrastructure  │    │   Integration   │    │  Persistence    │
│                 │    │                 │    │                 │
│ • Guards        │    │ • Media Service │    │ • MongoDB       │
│ • Decorators    │    │ • File Storage  │    │ • Repository    │
│ • Middleware    │    │ • CDN Service   │    │ • Schemas       │
│ • Validation    │    │ • Cache Service │    │ • Indexing      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

## Technology Stack

* **Framework**: NestJS with TypeScript
* **Database**: MongoDB with Mongoose ODM
* **File Storage**: Cloud storage with CDN integration
* **Caching**: Redis for performance optimization
* **Image Processing**: Automatic compression and thumbnail generation
* **Architecture**: CQRS (Command Query Responsibility Segregation)
* **Patterns**: Repository, Domain-Driven Design, Value Objects

## Quick Start

### 1. API Usage

Start with the [API Documentation](/services/business-profile/api.md) to understand available endpoints and how to interact with the business profile management system.

### 2. Integration

Review the [Interface Documentation](/services/business-profile/interface.md) to understand data structures, DTOs, and integration points.

### 3. Business Logic

Explore the [Use Case Documentation](/services/business-profile/usecase.md) to understand business rules, settings management, and workflows.

### 4. Data Layer

Check the [Database Schema](/services/business-profile/db_schema.md) for persistence implementation and query optimization details.

## Documentation Structure

| Document                                                           | Purpose                                              | Audience                              |
| ------------------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------- |
| [API Documentation](/services/business-profile/api.md)             | REST API reference, endpoints, media upload          | Frontend developers, API consumers    |
| [Interface Documentation](/services/business-profile/interface.md) | TypeScript interfaces, DTOs, settings objects        | Backend developers, integration teams |
| [Use Case Documentation](/services/business-profile/usecase.md)    | Business logic, settings management, media workflows | Backend developers, business analysts |
| [Database Schema](/services/business-profile/db_schema.md)         | Data persistence, indexing, query optimization       | Backend developers, DevOps teams      |

## Business Rules Summary

### ⚠️ Critical Constraints

1. **Profile Uniqueness**: Each tenant has exactly one business profile
2. **Username Uniqueness**: Business usernames must be globally unique (when provided)
3. **Settings Validation**: All nested settings objects must pass validation
4. **Media Format Restrictions**: Only supported image formats allowed for media uploads
5. **Publication Control**: Only published profiles are visible to customers

### 🔒 Security Features

* Tenant-based data isolation
* Role-based permission system
* Secure media file handling
* Audit trail for all changes
* State history tracking

### 📊 Performance Features

* Redis caching with intelligent invalidation
* Optimized database indexes
* CDN integration for media delivery
* Image compression and optimization
* Geospatial indexing for location queries

## Settings Architecture

### Core Settings Categories

#### 🏢 **Business Settings**

* Timezone and locale configuration
* Currency and language preferences
* Date/time format settings
* Email communication language

#### 📅 **Booking Settings**

* Customer booking rules and automation
* Advance booking time limits
* Auto-confirmation settings
* Payment requirement configuration
* Mandatory customer information fields

#### 💳 **Payment Settings**

* Multiple payment gateway support (Stripe, PayPal, Square)
* Currency configuration and exchange rates
* Tax calculation settings
* Default and accepted payment methods

#### 🔔 **Notification Settings**

* Email notification preferences
* SMS notification configuration
* Push notification settings
* Reminder and escalation rules

#### 🎨 **Panel Settings**

* Administrative interface customization
* Color schemes and themes
* Language preferences
* Display format preferences

#### 🌐 **Public Page Settings**

* Customer-facing page configuration
* Booking widget settings
* Public information display
* SEO and meta information

## Media Management

### 📸 **Media Types**

#### Logo Management

* **Purpose**: Primary business brand identifier
* **Format**: Square format (200x200px recommended)
* **Limit**: Single logo per business
* **Features**: Automatic thumbnail generation, format optimization

#### Banner Management

* **Purpose**: Promotional and marketing content
* **Format**: Landscape format (1200x400px recommended)
* **Limit**: Multiple banners supported
* **Features**: Display ordering, automatic compression

#### Gallery Management

* **Purpose**: Portfolio and work showcase
* **Format**: Variable dimensions (aspect ratio preserved)
* **Limit**: Multiple images supported
* **Features**: Thumbnail generation, optimization, CDN delivery

### 🔧 **Media Features**

* Automatic image compression and optimization
* Multiple thumbnail size generation
* CDN integration for global delivery
* Format validation and conversion
* Orphaned media cleanup
* Secure URL generation

## Integration Points

### Upstream Dependencies

* **Identity Service**: User authentication and authorization
* **Media Service**: File upload and management
* **Permission Service**: Role and permission management
* **Cache Service**: Performance optimization

### Downstream Consumers

* **Client Applications**: Public profile information
* **Booking Service**: Settings and availability information
* **Payment Service**: Payment configuration
* **Notification Service**: Communication preferences
* **Analytics Service**: Business information and metrics

### External Integrations

* **Payment Gateways**: Stripe, PayPal, Square integration
* **Cloud Storage**: AWS S3, Google Cloud Storage
* **CDN Services**: CloudFront, CloudFlare
* **Geolocation Services**: Address validation and coordinates
* **Social Platforms**: Profile verification and integration

## Common Use Cases

### 👤 **Business Owner Scenarios**

* Set up complete business profile during onboarding
* Update business information and contact details
* Configure booking and payment settings
* Upload and manage media assets (logo, banners, gallery)
* Set operating hours and special schedules
* Configure notification preferences

### 🏢 **Multi-Location Business Scenarios**

* Manage multiple business addresses
* Configure location-specific settings
* Handle timezone differences across locations
* Coordinate schedules across multiple sites

### 🎨 **Branding and Marketing Scenarios**

* Upload professional logo and branding materials
* Create promotional banner campaigns
* Showcase work portfolio in gallery
* Optimize images for web performance
* Maintain consistent brand presentation

### ⚙️ **System Administrator Scenarios**

* Bulk profile management and updates
* Settings template creation and application
* Media storage management and cleanup
* Performance monitoring and optimization
* Backup and recovery operations

## Monitoring and Maintenance

### Key Metrics

* Profile completeness rates
* Media upload success rates
* Settings update frequency
* API response times
* Cache hit ratios
* Database query performance
* Media storage utilization

### Health Checks

* Database connectivity and performance
* Media service availability
* Cache service status
* CDN delivery performance
* Payment gateway connectivity
* File upload functionality

### Maintenance Tasks

* Orphaned media cleanup
* Cache optimization and cleanup
* Database index maintenance
* Media thumbnail regeneration
* Backup verification
* Performance optimization

## Future Enhancements

### Planned Features

* **Advanced SEO Management**: Meta tags, structured data, sitemap generation
* **Multi-Brand Support**: Multiple brand identities per business
* **Template System**: Pre-configured setting templates for different business types
* **Analytics Integration**: Business profile performance metrics
* **A/B Testing**: Profile configuration testing and optimization
* **API Rate Limiting**: Enhanced rate limiting and throttling
* **Automated Backups**: Scheduled profile and media backups

### Scalability Considerations

* Database sharding strategies for large-scale deployments
* Media storage optimization and archiving
* CDN optimization for global performance
* Cache partitioning and distribution
* Microservice decomposition for specific features
* Event sourcing for audit trail optimization

## Security Considerations

### Data Protection

* **Encryption**: All sensitive data encrypted at rest and in transit
* **Access Control**: Role-based access with principle of least privilege
* **Audit Logging**: Complete audit trail of all profile changes
* **Data Validation**: Comprehensive input validation and sanitization
* **File Security**: Secure file upload with content type validation

### Privacy Compliance

* **Data Minimization**: Store only necessary business information
* **Right to Deletion**: Support for complete profile deletion
* **Data Portability**: Export capabilities for business profile data
* **Consent Management**: Privacy preference management
* **GDPR Compliance**: European data protection regulation compliance

### Business Continuity

* **Disaster Recovery**: Automated backup and recovery procedures
* **High Availability**: Redundant systems and failover mechanisms
* **Data Integrity**: Consistency checks and validation
* **Performance Monitoring**: Real-time performance and availability monitoring

***

## Getting Help

For technical questions or issues:

1. Check this documentation first
2. Review the API examples and use cases
3. Consult the interface definitions for data structures
4. Examine the database schema for data-related questions
5. Check the settings validation rules for configuration issues

For business rule clarifications:

1. Review the use case documentation
2. Check the business rules summary above
3. Consult the settings architecture section
4. Contact the product team for policy questions

For media-related issues:

1. Check file format and size requirements
2. Review media management documentation
3. Verify CDN and storage configuration
4. Contact the infrastructure team for storage issues

***

*This documentation is maintained by the Bee O'clock development team and is updated with each release.*