Member Management

Overview

This directory contains comprehensive documentation for the Member Management module of the Bee O'clock panel service. The member management system handles team member lifecycle, permissions, service assignments, and user relationships within the multi-tenant SaaS platform.

Documentation Structure

API Documentation

Complete REST API reference including all endpoints, request/response schemas, authentication requirements, and usage examples for member management operations.

Key Topics Covered:

• Member CRUD operations

• Pagination and search

• Avatar management

• Assignment management

• Role and permission handling

• Error responses and status codes

Interface Documentation

Detailed documentation of TypeScript interfaces, DTOs, enums, and contracts used throughout the member management module.

Key Topics Covered:

• Data Transfer Objects (DTOs)

• Domain interfaces and entities

• Enum definitions

• Type definitions and contracts

• Request/response models

Use Case Documentation

Business logic and use case implementations following Clean Architecture principles and CQRS pattern.

Key Topics Covered:

• Core business use cases

• Permission validation

• Error handling strategies

• Event publishing

• Transaction management

• Performance considerations

Database Schema Documentation

MongoDB schema definitions, relationships, indexes, and data integrity rules for the member management module.

Key Topics Covered:

• Entity schemas and relationships

• Sub-document structures

• Index strategies

• Multi-tenancy considerations

• Data validation rules

• Migration guidelines

Module Architecture

Technology Stack

• Framework: NestJS with TypeScript

• Database: MongoDB with Mongoose ODM

• Architecture: Clean Architecture + CQRS

• Patterns: Repository Pattern, Domain-Driven Design

• Caching: Redis for performance optimization

• Event System: AMQP for async processing

Core Features

Member Lifecycle Management

• Member creation with invitation system

• Profile updates and status management

• Soft deletion with audit trails

• Avatar upload and management

Permission System

• Role-based access control (RBAC)

• Service-level assignments

• Owner protection mechanisms

• Permission inheritance

Multi-Tenancy

• Tenant-isolated member data

• Tenant-aware operations

• Cross-tenant prevention

• Scalable tenant management

Integration Points

• Authentication via member context

• Notification system integration

• Cache management

• Event-driven architecture

Business Rules

Member Creation

1. Tariff Plan Validation: Active plan required for new members

2. Specialist Limits: Enforced based on tenant's plan

3. Email Uniqueness: Per tenant constraint

4. Invitation System: Automatic code generation and linking

5. Default Assignments: Configurable service access

Member Updates

1. Role Protection: Owners cannot remove own owner role

2. Permission Validation: Role changes require proper permissions

3. Assignment Control: Service access management

4. Avatar Management: File upload and storage handling

Member Deletion

1. Safety Checks: Prevent deletion of members with active events

2. Owner Restrictions: Only owners can delete members

3. Self-Protection: Cannot delete own account

4. Soft Delete: Preserve data for compliance and audit

Permission Model

1. Hierarchical Roles: Support for complex role structures

2. Service Assignments: Granular service-level permissions

3. Inheritance: Permission inheritance from roles

4. Validation: Real-time permission checking

API Integration Examples

Creating a Member

POST /api/member
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Doe", 
  "email": "[email protected]",
  "phone": "[phone]",
  "roles": [{ "name": "SPECIALIST", "isOwner": false }],
  "assignments": {
    "service": {
      "full": false,
      "include": [{ "service": "service-id" }]
    }
  }
}

Updating Member Assignments

PUT /api/member/{id}/assignment
Authorization: Bearer <token>
Content-Type: application/json

{
  "service": {
    "full": true,
    "include": []
  }
}

Paginated Member List

GET /api/member?page=1&size=10&search=john&profileStatus=active
Authorization: Bearer <token>

Development Guidelines

Testing Strategy

• Unit Tests: Business logic and validation

• Integration Tests: Database and external services

• E2E Tests: Complete API workflows

• Performance Tests: Load and stress testing

Error Handling

• Domain-specific exceptions

• Consistent error response format

• Proper HTTP status codes

• Detailed error messages for debugging

Performance Considerations

• Database indexing strategy

• Caching for frequently accessed data

• Optimized queries with population

• Event-driven async processing

Security Best Practices

• Input validation and sanitization

• Role-based access control

• Audit logging for sensitive operations

• PII data protection

Related Modules

Dependencies

• Identity Module: Authentication and account management

• Permission Module: Role and permission definitions

• Client Module: Tenant management

• Tariff Plan Module: Subscription and limits

• Notification Module: Event notifications

• Media Module: Avatar storage

Integration Points

• Member Context: Links members to authentication

• Cache Module: Performance optimization

• Event Bus: Async processing and notifications

• File Storage: Avatar and media management

Monitoring and Observability

Logging

• Structured logging with context

• Error tracking and alerting

• Performance metrics

• Business event logging

Metrics

• Member creation/deletion rates

• Permission validation performance

• Cache hit rates

• Database query performance

Health Checks

• Database connectivity

• Cache availability

• External service dependencies

• Business rule validation

Contributing

Code Standards

• TypeScript strict mode

• ESLint and Prettier configuration

• Comprehensive test coverage

• Clean Architecture principles

Documentation

• Update documentation with changes

• Include examples in API docs

• Maintain schema documentation

• Document business rule changes

Review Process

• Code review requirements

• Testing validation

• Documentation updates

• Performance impact assessment

Support and Troubleshooting

Common Issues

• Permission validation failures

• Tariff plan limit exceeded

• Email uniqueness violations

• Role change restrictions

Debugging Tools

• Structured error messages

• Audit trail investigation

• Cache inspection utilities

• Database query analysis

Performance Optimization

• Index optimization

• Query performance analysis

• Cache strategy tuning

• Event processing optimization