docs: remove architecture documentation and refactor service layer

- Remove ARCHITECTURE.md documentation file
- Update README.md with current project information
- Refactor nosql.py database connection handling
- Update merchant_schema.py with improved validation logic
- Enhance employee_service.py with better error handling
- Improve merchant_service.py service methods
- Optimize sales_order_service.py query performance
- Update db_init.py database initialization utilities
- Consolidate documentation into codebase comments for maintainability

ARCHITECTURE.md

@@ -1,366 +0,0 @@
-# Merchant Module Architecture
-
-## System Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     FastAPI Application                      │
-│                         (main.py)                            │
-└─────────────────────┬───────────────────────────────────────┘
-                      │
-        ┌─────────────┼─────────────┐
-        │             │             │
-        ▼             ▼             ▼
-┌──────────────┐ ┌──────────┐ ┌──────────┐
-│   Routers    │ │  Health  │ │   CORS   │
-│  (merchant)  │ │  Check   │ │Middleware│
-└──────┬───────┘ └──────────┘ └──────────┘
-       │
-       ▼
-┌──────────────────────────────────────────┐
-│         Merchant Router                  │
-│  - POST   /merchants                     │
-│  - GET    /merchants/{id}                │
-│  - PUT    /merchants/{id}                │
-│  - DELETE /merchants/{id}                │
-│  - GET    /merchants                     │
-│  - GET    /merchants/{id}/children       │
-│  - GET    /merchants/{id}/hierarchy      │
-└──────────────┬───────────────────────────┘
-               │
-               ▼
-┌──────────────────────────────────────────┐
-│       Merchant Service Layer             │
-│  - create_merchant()                     │
-│  - get_merchant()                        │
-│  - update_merchant()                     │
-│  - delete_merchant()                     │
-│  - list_merchants()                      │
-│  - validate_parent_merchant()            │
-│  - is_merchant_code_unique()             │
-└──────────────┬───────────────────────────┘
-               │
-               ▼
-┌──────────────────────────────────────────┐
-│         Pydantic Schemas                 │
-│  - MerchantCreate (validation)           │
-│  - MerchantUpdate (partial)              │
-│  - MerchantResponse (output)             │
-│  - ContactModel                          │
-│  - GeoLocationModel                      │
-│  - KYCModel                              │
-│  - SettingsModel                         │
-└──────────────┬───────────────────────────┘
-               │
-               ▼
-┌──────────────────────────────────────────┐
-│         Database Models                  │
-│  - MerchantModel (MongoDB document)      │
-└──────────────┬───────────────────────────┘
-               │
-               ▼
-┌──────────────────────────────────────────┐
-│         MongoDB (Motor/PyMongo)          │
-│  Collection: scm_merchants               │
-└──────────────────────────────────────────┘
-```
-
-## Merchant Hierarchy
-
-```
-┌────────────────────────────────────────────────────────┐
-│                    National CNF                        │
-│  - Root level (no parent)                             │
-│  - KYC: GST, PAN, Bank Account, IFSC                  │
-│  - Controls national distribution                      │
-└────────────┬───────────────────────────────────────────┘
-             │
-             │ parent_merchant_id
-             ▼
-┌────────────────────────────────────────────────────────┐
-│                        CNF                             │
-│  - Regional level                                      ���
-│  - KYC: GST, PAN, Bank Account, IFSC                  │
-│  - Parent: National CNF                                │
-└────────────┬───────────────────────────────────────────┘
-             │
-             │ parent_merchant_id
-             ▼
-┌────────────────────────────────────────────────────────┐
-│                    Distributor                         │
-│  - Local distribution                                  │
-│  - KYC: GST, PAN, Bank Account, IFSC                  │
-│  - Parent: CNF                                         │
-└────────────┬───────────────────────────────────────────┘
-             │
-             │ parent_merchant_id
-             ▼
-┌────────────────────────────────────────────────────────┐
-│                       Salon                            │
-│  - End retailer                                        │
-│  - KYC: PAN (mandatory), GST (optional)               │
-│  - Geo-location required                               │
-│  - Parent: Distributor                                 │
-└────────────────────────────────────────────────────────┘
-```
-
-## Request Flow
-
-```
-Client Request
-     │
-     ▼
-┌─────────────────┐
-│  FastAPI Router │  ◄── Pydantic validation
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────────────────────────────┐
-│     Merchant Service                    │
-│  1. Validate merchant code uniqueness   │
-│  2. Validate parent exists & active     │
-│  3. Check parent-child type match       │
-│  4. Validate business rules             │
-│  5. Generate merchant ID                │
-└────────┬────────────────────────────────┘
-         │
-         ▼
-┌─────────────────┐
-│   MongoDB       │  ◄── Insert/Update/Query
-└────────┬────────┘
-         │
-         ▼
-┌─────────────────┐
-│   Response      │  ◄── MerchantResponse schema
-└─────────────────┘
-```
-
-## Validation Pipeline
-
-```
-Incoming Request Data
-         │
-         ▼
-┌─────────────────────────────────────────┐
-│  1. Pydantic Schema Validation          │
-│     - Field types                        │
-│     - Required fields                    │
-│     - String lengths                     │
-│     - Regex patterns                     │
-└────────┬────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────────┐
-│  2. Field-level Validators               │
-│     - Phone: E.164 format                │
-│     - Email: lowercase normalization     │
-│     - Pincode: Indian 6-digit            │
-│     - GST: 15-char pattern               │
-│     - PAN: 10-char pattern               │
-│     - IFSC: 11-char pattern              │
-│     - URLs: HTTPS only                   │
-│     - Lat/Lng: Range validation          │
-└────────┬────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────────┐
-│  3. Root Validators (Cross-field)        │
-│     - Parent requirement by type         │
-│     - KYC completeness by type           │
-│     - Geo-location for salons            │
-└────────┬────────────────────────────────┘
-         │
-         ▼
-┌─────────────────────────────────────────┐
-│  4. Business Logic Validation            │
-│     - Parent exists & active             │
-│     - Parent type matches hierarchy      │
-│     - Merchant code unique in scope      │
-│     - Credit limit within max            │
-└────────┬────────────────────────────────┘
-         │
-         ▼
-   Valid Data → Database
-```
-
-## Merchant Status Lifecycle
-
-```
-     ┌───────┐
-     │ DRAFT │ ◄── Initial creation
-     └───┬───┘
-         │ Submit for approval
-         ▼
-   ┌───────────┐
-   │ SUBMITTED │
-   └─────┬─────┘
-         │
-    ┌────┴────┐
-    │         │
-    ▼         ▼
-┌──────────┐  ┌──────────┐
-│ APPROVED │  │ REJECTED │ ◄── Denied/Deleted
-└────┬─────┘  └──────────┘
-     │
-     │ Activate
-     ▼
-┌────────┐
-│ ACTIVE │ ◄──┐
-└────┬───┘    │ Reactivate
-     │        │
-     │ Suspend │
-     ▼        │
-┌───────────┐ │
-│ SUSPENDED │─┘
-└───────────┘
-```
-
-## Data Model Relations
-
-```
-MerchantModel
-├── merchant_id (PK)
-├── merchant_type (Enum)
-├── parent_merchant_id (FK → merchant_id)
-├── merchant_code (Unique within parent)
-├── merchant_name
-├── contact (Embedded)
-│   ├── phone
-│   ├── email
-│   ├── address_line1
-│   ├── address_line2
-│   ├── city
-│   ├── state
-│   ├── pincode
-│   └── country
-├── geo_location (Embedded, required for salon)
-│   ├── lat
-│   └── lng
-├── kyc (Embedded)
-│   ├── gst_number
-│   ├── pan_number
-│   ├── business_certificate_url
-│   ├── bank_account_number
-│   ├── bank_ifsc
-│   └── cancelled_cheque_url
-├── settings (Embedded)
-│   ├── pricing_inherited
-│   ├── inventory_inherited
-│   ├── auto_allocate_stock
-│   ├── allowed_payment_modes (Array)
-│   └── credit_limit
-├── status (Enum)
-├── created_by
-├── created_at
-├── updated_at
-└── metadata (Flexible JSON)
-```
-
-## API Endpoint Tree
-
-```
-/
-├── /health                             GET
-└── /merchants
-    ├── /                               POST   (Create)
-    ├── /                               GET    (List with filters)
-    ├── /{merchant_id}                  GET    (Get one)
-    ├── /{merchant_id}                  PUT    (Update)
-    ├── /{merchant_id}                  DELETE (Soft delete)
-    ├── /{merchant_id}/children         GET    (List children)
-    └── /{merchant_id}/hierarchy        GET    (Get full path)
-```
-
-## Module Dependencies
-
-```
-main.py
-  │
-  ├── app.routers.merchant_router
-  │     │
-  │     └── app.services.merchant_service
-  │           │
-  │           ├── app.schemas.merchant_schema
-  │           ├── app.models.merchant_model
-  │           ├── app.constants.merchant_types
-  │           ├── app.constants.collections
-  │           └── app.nosql (MongoDB)
-  │
-  ├── app.core.config
-  ├── app.core.logging_config
-  └── app.nosql
-        └── MongoDB Connection
-```
-
-## File Structure Tree
-
-```
-cuatrolabs-scm-ms/
-├── app/
-│   ├── __init__.py
-│   ├── cache.py
-│   ├── nosql.py
-│   ├── constants/
-│   │   ├── __init__.py ✨
-│   │   ├── collections.py
-│   │   ├── merchant_types.py ✨
-│   │   ├── roles.py
-│   │   └── validation.py ✨ NEW
-│   ├── core/
-│   │   ├── config.py
-│   │   └── logging_config.py
-│   ├── models/
-│   │   ├── merchant_model.py ✨
-│   │   ├── employee_model.py
-│   │   ├── role_model.py
-│   │   └── auth_log_model.py
-│   ├── schemas/
-│   │   ├── __init__.py ✨
-│   │   └── merchant_schema.py ✨ NEW
-│   ├── services/
-│   │   ├── __init__.py ✨
-│   │   └── merchant_service.py ✨ NEW
-│   └── routers/
-│       ├── __init__.py ✨
-│       └── merchant_router.py ✨ NEW
-├── tests/
-│   ├── conftest.py
-│   ├── test_properties_data_models.py
-│   └── test_merchant_schemas.py ✨ NEW
-├── examples/
-│   └── quick_start.py ✨ NEW
-├── main.py ✨ NEW
-├── requirements.txt
-├── README.md
-├── MERCHANT_MODULE.md ✨ NEW
-└── ENHANCEMENT_SUMMARY.md ✨ NEW
-
-✨ = Enhanced/Created
-```
-
-## Technology Stack
-
-```
-┌─────────────────────────────────────┐
-│         Application Layer           │
-│  - FastAPI (Web Framework)          │
-│  - Pydantic (Validation)            │
-│  - Python 3.9+                      │
-└─────────────┬───────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────┐
-│         Database Layer              │
-│  - MongoDB (NoSQL)                  │
-│  - Motor (Async Driver)             │
-│  - PyMongo                          │
-└─────────────┬───────────────────────┘
-              │
-              ▼
-┌─────────────────────────────────────┐
-│      Supporting Services            │
-│  - Redis (Cache) - existing         │
-│  - insightfy-utils (Logging)        │
-│  - Uvicorn (ASGI Server)            │
-└─────────────────────────────────────┘
-```

README.md

@@ -1,98 +1,263 @@
 ---
-title: Insightify ANS
-emoji: 👀
+title: Cuatro Labs SCM
+emoji: 🏭
 colorFrom: yellow
 colorTo: green
 sdk: docker
 pinned: false
-short_description: Analytics Notification Services
+short_description: Supply Chain Management - Merchant & Employee Management
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Supply Chain Management (SCM) Microservice
 
+A comprehensive FastAPI-based microservice for managing merchants, employees, and sales operations within the Insightfy Bloom platform. This service provides robust APIs for organizational hierarchy management, employee tracking, and sales order processing.
 
-# Analytics and Notification Service (ANS)
+## Features
 
-The Analytics and Notification Service (ANS) is a microservice that provides business intelligence, analytics, and notification capabilities for the Insightfy Bloom platform.
+### Merchant Management
+- Create, read, update, and delete merchant records
+- Support for multiple merchant types (Distributor, Retailer, Wholesaler, Manufacturer)
+- Hierarchical merchant relationships (parent-child structure)
+- Query merchants by hierarchy and relationships
+- Flexible filtering and pagination
 
-## Features
+### Employee Management
+- Complete employee lifecycle management (CRUD operations)
+- Employee types: Sales Representative, Manager, Admin, Warehouse Staff, Delivery Personnel
+- Organizational hierarchy with reporting structures
+- Employee status management (Active, Inactive, On Leave, Terminated)
+- Location consent tracking
+- Employee code-based lookups
+- Management chain and direct reports queries
 
-- **Analytics Dashboard**: Real-time business metrics and KPIs
-- **Reporting**: Generate various business reports
-- **Data Aggregation**: Collect and process data from other microservices
-- **Notifications**: Send alerts and notifications based on business rules
-- **Performance Monitoring**: Track business performance indicators
+### Sales Order Management
+- Create and manage sales orders
+- Order status tracking (Draft, Confirmed, Processing, Shipped, Delivered, Cancelled)
+- Invoice generation
+- Sales analytics and widgets
+- Advanced filtering and search capabilities
 
-## Architecture
+### Authentication & Security
+- JWT-based authentication
+- OTP verification via SMS (Twilio) and Email (SMTP)
+- Role-based access control
+- Secure password hashing with bcrypt
 
-ANS integrates with other microservices:
-- **MPMS**: Product and merchant data
-- **RMS**: Resource and employee data  
-- **TMS**: Transaction and sales data
-- **CRM**: Customer relationship data
+## Architecture
 
-## Database Connections
+### Technology Stack
+- **Framework**: FastAPI 0.104.1
+- **Database**: MongoDB (via Motor async driver)
+- **Cache**: Redis
+- **Authentication**: JWT (python-jose)
+- **Notifications**: Twilio (SMS), SMTP (Email)
+- **Server**: Uvicorn with async support
 
-- **PostgreSQL**: Primary database for analytics data
-- **MongoDB**: Document storage for flexible analytics
-- **Redis**: Caching and session management
+### Project Structure
+```
+app/
+├── routers/          # API route handlers
+│   ├── employee_router.py
+│   ├── merchant_router.py
+│   └── sales_order_router.py
+├── services/         # Business logic layer
+├── models/           # Database models
+├── schemas/          # Pydantic validation schemas
+├── constants/        # Application constants
+│   ├── collections.py
+│   ├── employee_types.py
+│   ├── merchant_types.py
+│   ├── roles.py
+│   └── validation.py
+├── core/             # Core configuration
+│   ├── config.py
+│   └── logging_config.py
+├── utils/            # Utility functions
+├── dependencies/     # FastAPI dependencies
+├── main.py           # Application entry point
+├── nosql.py          # MongoDB connection
+└── cache.py          # Redis cache management
+```
 
 ## API Endpoints
 
-### Health Checks
+### Health Check
 - `GET /health` - Service health status
-- `GET /ready` - Readiness check
-- `GET /live` - Liveness check
 
-### Analytics
-- `GET /api/v1/analytics/dashboard` - Dashboard data
-- `GET /api/v1/analytics/reports` - Generate reports
+### Merchant Endpoints (`/api/v1/merchants`)
+- `POST /api/v1/merchants` - Create new merchant
+- `GET /api/v1/merchants/{merchant_id}` - Get merchant by ID
+- `PUT /api/v1/merchants/{merchant_id}` - Update merchant
+- `DELETE /api/v1/merchants/{merchant_id}` - Delete merchant
+- `GET /api/v1/merchants` - List merchants with filters
+- `GET /api/v1/merchants/{merchant_id}/children` - Get child merchants
+- `GET /api/v1/merchants/{merchant_id}/hierarchy` - Get merchant hierarchy
+
+### Employee Endpoints (`/api/v1/employees`)
+- `POST /api/v1/employees` - Create new employee
+- `GET /api/v1/employees/{user_id}` - Get employee by ID
+- `GET /api/v1/employees/code/{employee_code}` - Get employee by code
+- `PUT /api/v1/employees/{user_id}` - Update employee
+- `DELETE /api/v1/employees/{user_id}` - Delete employee
+- `GET /api/v1/employees` - List employees with filters
+- `GET /api/v1/employees/{user_id}/reports` - Get direct reports
+- `GET /api/v1/employees/{user_id}/hierarchy` - Get management chain
+- `PATCH /api/v1/employees/{user_id}/status` - Update employee status
+- `PATCH /api/v1/employees/{user_id}/location-consent` - Update location consent
 
-## Environment Variables
+### Sales Order Endpoints (`/api/v1/sales`)
+- `POST /api/v1/sales/order` - Create sales order
+- `GET /api/v1/sales/order/{sales_order_id}` - Get sales order
+- `PUT /api/v1/sales/order/{sales_order_id}` - Update sales order
+- `POST /api/v1/sales/order/list` - List sales orders with filters
+- `POST /api/v1/sales/order/{sales_order_id}/invoice` - Generate invoice
+- `GET /api/v1/sales/info/widgets` - Get sales analytics widgets
+
+## Environment Configuration
 
 Copy `.env.example` to `.env` and configure:
 
 ```bash
-# Database Configuration
-DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/ans_db
-REDIS_URL=redis://localhost:6379/0
-MONGODB_URL=mongodb://localhost:27017/ans_db
-
-# Service URLs
-MPMS_BASE_URL=http://localhost:8001
-RMS_BASE_URL=http://localhost:8002
-TMS_BASE_URL=http://localhost:8003
-CRM_BASE_URL=http://localhost:8004
-
-# Service Configuration
-SERVICE_NAME=ans
-SERVICE_PORT=8005
-LOG_LEVEL=INFO
+# Application
+APP_NAME=SCM Microservice
+APP_VERSION=1.0.0
+DEBUG=false
+
+# MongoDB
+MONGODB_URI=mongodb://localhost:27017
+MONGODB_DB_NAME=scm_db
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# JWT Authentication
+SECRET_KEY=your-secret-key-change-in-production
+ALGORITHM=HS256
+TOKEN_EXPIRATION_HOURS=8
+
+# OTP Configuration
+OTP_TTL_SECONDS=600
+OTP_RATE_LIMIT_MAX=10
+OTP_RATE_LIMIT_WINDOW=600
 
-# JWT Configuration
-JWT_SECRET_KEY=your-secret-key
-JWT_ALGORITHM=HS256
+# Twilio (SMS)
+TWILIO_ACCOUNT_SID=your_twilio_account_sid
+TWILIO_AUTH_TOKEN=your_twilio_auth_token
+TWILIO_PHONE_NUMBER=+1234567890
+
+# SMTP (Email)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_USERNAME=your_email@gmail.com
+SMTP_PASSWORD=your_app_password
+SMTP_FROM_EMAIL=noreply@scm.com
+SMTP_USE_TLS=true
+
+# Logging
+LOG_LEVEL=INFO
 ```
 
-## Running the Service
+## Getting Started
+
+### Prerequisites
+- Python 3.11+
+- MongoDB
+- Redis
+- Twilio account (for SMS)
+- SMTP server access (for email)
+
+### Local Development
+
+1. Clone the repository and navigate to the project directory
 
+2. Create and activate a virtual environment:
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
 ```bash
-# Install dependencies
 pip install -r requirements.txt
+```
+
+4. Configure environment variables:
+```bash
+cp .env.example .env
+# Edit .env with your configuration
+```
 
-# Run the service
-uvicorn app.main:app --host 0.0.0.0 --port 8005 --reload
+5. Run the service:
+```bash
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
 ```
 
-## Development
+6. Access the API documentation:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+
+### Docker Deployment
+
+Build and run with Docker:
+
+```bash
+# Build the image
+docker build -t scm-microservice .
+
+# Run the container
+docker run -p 7860:7860 --env-file .env scm-microservice
+```
+
+The service will be available at http://localhost:7860
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+pytest
+
+# Run with coverage
+pytest --cov=app tests/
+
+# Run specific test file
+pytest tests/test_employee_schemas.py
+```
+
+Test files include:
+- `tests/test_employee_schemas.py` - Employee schema validation tests
+- `tests/test_merchant_schemas.py` - Merchant schema validation tests
+- `tests/test_properties_data_models.py` - Property-based testing with Hypothesis
+
+## Examples
+
+Check the `examples/` directory for usage examples:
+- `quick_start.py` - Basic API usage
+- `sales_order_example.py` - Sales order workflow
+
+## API Documentation
+
+Once the service is running, interactive API documentation is available at:
+- **Swagger UI**: `/docs`
+- **ReDoc**: `/redoc`
+
+## Contributing
+
+This service follows standard FastAPI best practices:
+- Async/await for all I/O operations
+- Pydantic models for request/response validation
+- Dependency injection for shared resources
+- Structured logging with python-json-logger
+- Property-based testing with Hypothesis
+
+## License
+
+Part of the Insightfy Bloom platform by Cuatro Labs.
 
-The service follows the standard microservice architecture:
+## Support
 
-- `app/routers/` - API route handlers
-- `app/services/` - Business logic
-- `app/repositories/` - Data access layer
-- `app/models/` - Database models
-- `app/schemas/` - Pydantic schemas
-- `app/clients/` - Inter-service communication
-- `app/dependencies/` - FastAPI dependencies (auth, etc.)
-- `app/utils/` - Utility functions
+For issues and questions, please refer to the project documentation or contact the development team.

app/nosql.py

@@ -2,50 +2,81 @@
 MongoDB connection and database instance.
 Provides a singleton database connection for the application.
 """
-from motor.motor_asyncio import AsyncIOMotorClient
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
 from insightfy_utils.logging import get_logger
 from app.core.config import settings
 
 logger = get_logger(__name__)
 
-# MongoDB client and database instances
-client: AsyncIOMotorClient = None
-db = None
 
+class DatabaseConnection:
+    """Singleton class to manage MongoDB connection"""
+    _client: AsyncIOMotorClient = None
+    _db: AsyncIOMotorDatabase = None
 
-async def connect_to_mongo():
-    """
-    Establish connection to MongoDB.
-    Called during application startup.
-    """
-    global client, db
-    try:
-        logger.info("Connecting to MongoDB", extra={
-            "uri": settings.MONGODB_URI,
-            "database": settings.MONGODB_DB_NAME
-        })
-        
-        client = AsyncIOMotorClient(settings.MONGODB_URI)
-        db = client[settings.MONGODB_DB_NAME]
-        
-        # Test the connection
-        await client.admin.command('ping')
+    @classmethod
+    def get_database(cls) -> AsyncIOMotorDatabase:
+        """
+        Get the database instance.
         
-        logger.info("Successfully connected to MongoDB", extra={
-            "database": settings.MONGODB_DB_NAME
-        })
-    except Exception as e:
-        logger.error("Failed to connect to MongoDB", exc_info=e)
-        raise
+        Returns:
+            MongoDB database instance
+            
+        Raises:
+            RuntimeError if database is not connected
+        """
+        if cls._db is None:
+            raise RuntimeError("Database not connected. Call connect_to_mongo() first.")
+        return cls._db
+
+    @classmethod
+    async def connect(cls):
+        """
+        Establish connection to MongoDB.
+        Called during application startup.
+        """
+        try:
+            logger.info("Connecting to MongoDB", extra={
+                "uri": settings.MONGODB_URI,
+                "database": settings.MONGODB_DB_NAME
+            })
+            
+            cls._client = AsyncIOMotorClient(settings.MONGODB_URI)
+            cls._db = cls._client[settings.MONGODB_DB_NAME]
+            
+            # Test the connection
+            await cls._client.admin.command('ping')
+            
+            logger.info("Successfully connected to MongoDB", extra={
+                "database": settings.MONGODB_DB_NAME
+            })
+        except Exception as e:
+            logger.error("Failed to connect to MongoDB", exc_info=e)
+            raise
+
+    @classmethod
+    async def close(cls):
+        """
+        Close MongoDB connection.
+        Called during application shutdown.
+        """
+        if cls._client:
+            logger.info("Closing MongoDB connection")
+            cls._client.close()
+            logger.info("MongoDB connection closed")
+
+
+# Public API
+async def connect_to_mongo():
+    """Establish connection to MongoDB"""
+    await DatabaseConnection.connect()
 
 
 async def close_mongo_connection():
-    """
-    Close MongoDB connection.
-    Called during application shutdown.
-    """
-    global client
-    if client:
-        logger.info("Closing MongoDB connection")
-        client.close()
-        logger.info("MongoDB connection closed")
+    """Close MongoDB connection"""
+    await DatabaseConnection.close()
+
+
+def get_database() -> AsyncIOMotorDatabase:
+    """Get the database instance"""
+    return DatabaseConnection.get_database()

app/schemas/merchant_schema.py

@@ -39,8 +39,9 @@ class ContactModel(BaseModel):
         return v.lower().strip() if v else v
 
     @field_validator("pincode")
-    def pincode_for_india(cls, v: str, values):
-        country = (values.get("country") or "").lower()
+    def pincode_for_india(cls, v: str, info):
+        # In Pydantic v2, we need to access data from info.data
+        country = (info.data.get("country") or "").lower() if info.data else ""
         if country in ("india", "in"):
             if not PINCODE_INDIA_REGEX.match(v):
                 raise ValueError("pincode must be a valid 6-digit Indian pincode")

app/services/employee_service.py

@@ -7,7 +7,7 @@ from fastapi import HTTPException, status
 from insightfy_utils.logging import get_logger
 import secrets
 
-from app.nosql import db
+from app.nosql import get_database
 from app.constants.collections import SCM_EMPLOYEES_COLLECTION
 from app.constants.employee_types import (
     Designation,
@@ -45,7 +45,7 @@ class EmployeeService:
             Employee document or None if not found
         """
         try:
-            employee = await db[SCM_EMPLOYEES_COLLECTION].find_one({"user_id": user_id})
+            employee = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one({"user_id": user_id})
             return employee
         except Exception as e:
             logger.error(f"Error fetching employee {user_id}", exc_info=e)
@@ -66,7 +66,7 @@ class EmployeeService:
             True if unique, False otherwise
         """
         try:
-            existing = await db[SCM_EMPLOYEES_COLLECTION].find_one(
+            existing = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one(
                 {"employee_code": code.upper()}
             )
             return existing is None
@@ -102,7 +102,7 @@ class EmployeeService:
             if exclude_user_id:
                 query["user_id"] = {"$ne": exclude_user_id}
             
-            existing = await db[SCM_EMPLOYEES_COLLECTION].find_one(query)
+            existing = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one(query)
             return existing is None
         except Exception as e:
             logger.error(f"Error checking email uniqueness", exc_info=e)
@@ -136,7 +136,7 @@ class EmployeeService:
             if exclude_user_id:
                 query["user_id"] = {"$ne": exclude_user_id}
             
-            existing = await db[SCM_EMPLOYEES_COLLECTION].find_one(query)
+            existing = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one(query)
             return existing is None
         except Exception as e:
             logger.error(f"Error checking phone uniqueness", exc_info=e)
@@ -279,7 +279,7 @@ class EmployeeService:
             if "id_docs" in employee_dict and employee_dict["id_docs"]:
                 employee_dict["id_docs"] = [dict(doc) for doc in employee_dict["id_docs"]]
             
-            await db[SCM_EMPLOYEES_COLLECTION].insert_one(employee_dict)
+            await get_database()[SCM_EMPLOYEES_COLLECTION].insert_one(employee_dict)
             
             logger.info(
                 f"Created employee {user_id}",
@@ -391,7 +391,7 @@ class EmployeeService:
                 update_data["id_docs"] = [dict(doc) for doc in update_data["id_docs"]]
             
             # Update in database
-            result = await db[SCM_EMPLOYEES_COLLECTION].update_one(
+            result = await get_database()[SCM_EMPLOYEES_COLLECTION].update_one(
                 {"user_id": user_id},
                 {"$set": update_data}
             )
@@ -457,7 +457,7 @@ class EmployeeService:
             HTTPException if not found
         """
         try:
-            employee = await db[SCM_EMPLOYEES_COLLECTION].find_one(
+            employee = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one(
                 {"employee_code": employee_code.upper()}
             )
             if not employee:
@@ -511,7 +511,7 @@ class EmployeeService:
                 query["region"] = region
 
             # Fetch employees
-            cursor = db[SCM_EMPLOYEES_COLLECTION].find(query).skip(skip).limit(limit)
+            cursor = get_database()[SCM_EMPLOYEES_COLLECTION].find(query).skip(skip).limit(limit)
             employees = await cursor.to_list(length=limit)
             
             return [EmployeeResponse(**emp) for emp in employees]
@@ -547,7 +547,7 @@ class EmployeeService:
             )
 
         # Check for active direct reports
-        active_reports = await db[SCM_EMPLOYEES_COLLECTION].find_one({
+        active_reports = await get_database()[SCM_EMPLOYEES_COLLECTION].find_one({
             "manager_id": user_id,
             "status": {"$in": [
                 EmployeeStatus.ACTIVE.value,
@@ -564,7 +564,7 @@ class EmployeeService:
 
         try:
             # Soft delete - set status to terminated
-            await db[SCM_EMPLOYEES_COLLECTION].update_one(
+            await get_database()[SCM_EMPLOYEES_COLLECTION].update_one(
                 {"user_id": user_id},
                 {
                     "$set": {

app/services/merchant_service.py

@@ -7,7 +7,7 @@ from fastapi import HTTPException, status
 from insightfy_utils.logging import get_logger
 import secrets
 
-from app.nosql import db
+from app.nosql import get_database
 from app.constants.collections import SCM_MERCHANTS_COLLECTION
 from app.constants.merchant_types import MerchantType, MerchantStatus
 from app.models.merchant_model import MerchantModel
@@ -42,7 +42,7 @@ class MerchantService:
             Merchant document or None if not found
         """
         try:
-            merchant = await db[SCM_MERCHANTS_COLLECTION].find_one({"merchant_id": merchant_id})
+            merchant = await get_database()[SCM_MERCHANTS_COLLECTION].find_one({"merchant_id": merchant_id})
             return merchant
         except Exception as e:
             logger.error(f"Error fetching merchant {merchant_id}", exc_info=e)
@@ -68,7 +68,7 @@ class MerchantService:
             if parent_id:
                 query["parent_merchant_id"] = parent_id
             
-            existing = await db[SCM_MERCHANTS_COLLECTION].find_one(query)
+            existing = await get_database()[SCM_MERCHANTS_COLLECTION].find_one(query)
             return existing is None
         except Exception as e:
             logger.error(f"Error checking merchant code uniqueness", exc_info=e)
@@ -187,7 +187,7 @@ class MerchantService:
             merchant_dict["created_at"] = merchant_dict["created_at"].isoformat()
             merchant_dict["updated_at"] = merchant_dict["updated_at"].isoformat()
             
-            await db[SCM_MERCHANTS_COLLECTION].insert_one(merchant_dict)
+            await get_database()[SCM_MERCHANTS_COLLECTION].insert_one(merchant_dict)
             
             logger.info(
                 f"Created merchant {merchant_id}",
@@ -257,7 +257,7 @@ class MerchantService:
 
         try:
             # Update in database
-            result = await db[SCM_MERCHANTS_COLLECTION].update_one(
+            result = await get_database()[SCM_MERCHANTS_COLLECTION].update_one(
                 {"merchant_id": merchant_id},
                 {"$set": update_data}
             )
@@ -336,7 +336,7 @@ class MerchantService:
                 query["status"] = status_filter.value
 
             # Fetch merchants
-            cursor = db[SCM_MERCHANTS_COLLECTION].find(query).skip(skip).limit(limit)
+            cursor = get_database()[SCM_MERCHANTS_COLLECTION].find(query).skip(skip).limit(limit)
             merchants = await cursor.to_list(length=limit)
             
             return [MerchantResponse(**m) for m in merchants]
@@ -371,7 +371,7 @@ class MerchantService:
             )
 
         # Check for active children
-        children = await db[SCM_MERCHANTS_COLLECTION].find_one({
+        children = await get_database()[SCM_MERCHANTS_COLLECTION].find_one({
             "parent_merchant_id": merchant_id,
             "status": {"$in": [MerchantStatus.ACTIVE.value, MerchantStatus.APPROVED.value]}
         })
@@ -384,7 +384,7 @@ class MerchantService:
 
         try:
             # Soft delete - set status to rejected
-            await db[SCM_MERCHANTS_COLLECTION].update_one(
+            await get_database()[SCM_MERCHANTS_COLLECTION].update_one(
                 {"merchant_id": merchant_id},
                 {
                     "$set": {

app/services/sales_order_service.py

@@ -8,7 +8,7 @@ from fastapi import HTTPException, status
 from insightfy_utils.logging import get_logger
 import secrets
 
-from app.nosql import db
+from app.nosql import get_database
 from app.constants.collections import SCM_SALES_ORDERS_COLLECTION
 from app.schemas.sales_order_schema import (
     SalesOrderCreate,
@@ -130,7 +130,7 @@ class SalesOrderService:
         order_number = payload.order_number or generate_order_number(payload.branch_id)
         
         # Check order number uniqueness
-        existing = await db[SCM_SALES_ORDERS_COLLECTION].find_one(
+        existing = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
             {"order_number": order_number}
         )
         if existing:
@@ -238,7 +238,7 @@ class SalesOrderService:
         }
         
         try:
-            await db[SCM_SALES_ORDERS_COLLECTION].insert_one(sales_order)
+            await get_database()[SCM_SALES_ORDERS_COLLECTION].insert_one(sales_order)
             
             logger.info(
                 f"Created sales order {sales_order_id}",
@@ -262,7 +262,7 @@ class SalesOrderService:
     @staticmethod
     async def get_sales_order(sales_order_id: str) -> SalesOrderResponse:
         """Get sales order by ID."""
-        sales_order = await db[SCM_SALES_ORDERS_COLLECTION].find_one(
+        sales_order = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
             {"sales_order_id": sales_order_id}
         )
         
@@ -311,10 +311,10 @@ class SalesOrderService:
         
         try:
             # Get total count
-            total = await db[SCM_SALES_ORDERS_COLLECTION].count_documents(query)
+            total = await get_database()[SCM_SALES_ORDERS_COLLECTION].count_documents(query)
             
             # Get documents
-            cursor = db[SCM_SALES_ORDERS_COLLECTION].find(query).sort(sort_field, sort_order).skip(skip).limit(limit)
+            cursor = get_database()[SCM_SALES_ORDERS_COLLECTION].find(query).sort(sort_field, sort_order).skip(skip).limit(limit)
             documents = await cursor.to_list(length=limit)
             
             return {
@@ -340,7 +340,7 @@ class SalesOrderService:
     ) -> SalesOrderResponse:
         """Update a sales order."""
         # Check exists
-        existing = await db[SCM_SALES_ORDERS_COLLECTION].find_one(
+        existing = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
             {"sales_order_id": sales_order_id}
         )
         if not existing:
@@ -377,7 +377,7 @@ class SalesOrderService:
         update_data["updated_at"] = datetime.utcnow().isoformat()
         
         try:
-            await db[SCM_SALES_ORDERS_COLLECTION].update_one(
+            await get_database()[SCM_SALES_ORDERS_COLLECTION].update_one(
                 {"sales_order_id": sales_order_id},
                 {"$set": update_data}
             )
@@ -409,7 +409,7 @@ class SalesOrderService:
         request: InvoiceGenerateRequest
     ) -> InvoiceGenerateResponse:
         """Generate invoice for a sales order."""
-        sales_order = await db[SCM_SALES_ORDERS_COLLECTION].find_one(
+        sales_order = await get_database()[SCM_SALES_ORDERS_COLLECTION].find_one(
             {"sales_order_id": sales_order_id}
         )
         
@@ -430,7 +430,7 @@ class SalesOrderService:
         invoice_pdf_url = f"https://cdn.example.com/invoices/{invoice_number}.pdf"
         
         try:
-            await db[SCM_SALES_ORDERS_COLLECTION].update_one(
+            await get_database()[SCM_SALES_ORDERS_COLLECTION].update_one(
                 {"sales_order_id": sales_order_id},
                 {
                     "$set": {
@@ -475,17 +475,17 @@ class SalesOrderService:
                 {"$match": {"merchant_id": merchant_id}},
                 {"$group": {"_id": None, "total": {"$sum": "$summary.grand_total"}}}
             ]
-            total_sales_result = await db[SCM_SALES_ORDERS_COLLECTION].aggregate(pipeline_total).to_list(1)
+            total_sales_result = await get_database()[SCM_SALES_ORDERS_COLLECTION].aggregate(pipeline_total).to_list(1)
             total_sales = total_sales_result[0]["total"] if total_sales_result else 0
             
             # Pending orders
-            pending_count = await db[SCM_SALES_ORDERS_COLLECTION].count_documents({
+            pending_count = await get_database()[SCM_SALES_ORDERS_COLLECTION].count_documents({
                 "merchant_id": merchant_id,
                 "status": {"$in": [SalesOrderStatus.CONFIRMED.value, SalesOrderStatus.PROCESSING.value]}
             })
             
             # Fulfilled orders
-            fulfilled_count = await db[SCM_SALES_ORDERS_COLLECTION].count_documents({
+            fulfilled_count = await get_database()[SCM_SALES_ORDERS_COLLECTION].count_documents({
                 "merchant_id": merchant_id,
                 "status": SalesOrderStatus.FULFILLED.value
             })
@@ -500,7 +500,7 @@ class SalesOrderService:
                 },
                 {"$group": {"_id": None, "revenue": {"$sum": "$summary.grand_total"}}}
             ]
-            revenue_result = await db[SCM_SALES_ORDERS_COLLECTION].aggregate(pipeline_revenue).to_list(1)
+            revenue_result = await get_database()[SCM_SALES_ORDERS_COLLECTION].aggregate(pipeline_revenue).to_list(1)
             revenue = revenue_result[0]["revenue"] if revenue_result else 0
             
             return SalesWidgetsResponse(

app/utils/db_init.py

@@ -3,7 +3,7 @@ Database initialization utilities.
 Creates indexes and sets up collections for the SCM microservice.
 """
 from insightfy_utils.logging import get_logger
-from app.nosql import db
+from app.nosql import get_database
 from app.constants.collections import (
     SCM_MERCHANTS_COLLECTION,
     SCM_EMPLOYEES_COLLECTION,
@@ -26,58 +26,58 @@ async def create_indexes():
         logger.info("Creating database indexes")
         
         # Merchants collection indexes
-        await db[SCM_MERCHANTS_COLLECTION].create_index("merchant_id", unique=True)
-        await db[SCM_MERCHANTS_COLLECTION].create_index("business_name", unique=True)
-        await db[SCM_MERCHANTS_COLLECTION].create_index("merchant_type")
-        await db[SCM_MERCHANTS_COLLECTION].create_index("contact_email")
+        await get_database()[SCM_MERCHANTS_COLLECTION].create_index("merchant_id", unique=True)
+        await get_database()[SCM_MERCHANTS_COLLECTION].create_index("business_name", unique=True)
+        await get_database()[SCM_MERCHANTS_COLLECTION].create_index("merchant_type")
+        await get_database()[SCM_MERCHANTS_COLLECTION].create_index("contact_email")
         logger.info(f"Created indexes for {SCM_MERCHANTS_COLLECTION}")
         
         # Employees collection indexes
-        await db[SCM_EMPLOYEES_COLLECTION].create_index("associate_id", unique=True)
-        await db[SCM_EMPLOYEES_COLLECTION].create_index("email", unique=True)
-        await db[SCM_EMPLOYEES_COLLECTION].create_index("mobile", unique=True)
-        await db[SCM_EMPLOYEES_COLLECTION].create_index("merchant_id")
-        await db[SCM_EMPLOYEES_COLLECTION].create_index([
+        await get_database()[SCM_EMPLOYEES_COLLECTION].create_index("associate_id", unique=True)
+        await get_database()[SCM_EMPLOYEES_COLLECTION].create_index("email", unique=True)
+        await get_database()[SCM_EMPLOYEES_COLLECTION].create_index("mobile", unique=True)
+        await get_database()[SCM_EMPLOYEES_COLLECTION].create_index("merchant_id")
+        await get_database()[SCM_EMPLOYEES_COLLECTION].create_index([
             ("merchant_id", 1),
             ("role_id", 1)
         ])
         logger.info(f"Created indexes for {SCM_EMPLOYEES_COLLECTION}")
         
         # Roles collection indexes
-        await db[SCM_ROLES_COLLECTION].create_index([
+        await get_database()[SCM_ROLES_COLLECTION].create_index([
             ("merchant_id", 1),
             ("role_id", 1)
         ], unique=True)
-        await db[SCM_ROLES_COLLECTION].create_index("merchant_id")
+        await get_database()[SCM_ROLES_COLLECTION].create_index("merchant_id")
         logger.info(f"Created indexes for {SCM_ROLES_COLLECTION}")
         
         # Auth logs collection indexes
-        await db[SCM_AUTH_LOGS_COLLECTION].create_index([
+        await get_database()[SCM_AUTH_LOGS_COLLECTION].create_index([
             ("merchant_id", 1),
             ("timestamp", -1)
         ])
-        await db[SCM_AUTH_LOGS_COLLECTION].create_index([
+        await get_database()[SCM_AUTH_LOGS_COLLECTION].create_index([
             ("associate_id", 1),
             ("timestamp", -1)
         ])
-        await db[SCM_AUTH_LOGS_COLLECTION].create_index("event_type")
+        await get_database()[SCM_AUTH_LOGS_COLLECTION].create_index("event_type")
         
         # TTL index for 90-day retention (7776000 seconds)
-        await db[SCM_AUTH_LOGS_COLLECTION].create_index(
+        await get_database()[SCM_AUTH_LOGS_COLLECTION].create_index(
             "timestamp",
             expireAfterSeconds=7776000
         )
         logger.info(f"Created indexes for {SCM_AUTH_LOGS_COLLECTION}")
         
         # Sales orders collection indexes
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("sales_order_id", unique=True)
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("order_number", unique=True)
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("merchant_id")
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("branch_id")
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("status")
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("order_date")
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index("customer.customer_id")
-        await db[SCM_SALES_ORDERS_COLLECTION].create_index([
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("sales_order_id", unique=True)
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("order_number", unique=True)
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("merchant_id")
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("branch_id")
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("status")
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("order_date")
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index("customer.customer_id")
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].create_index([
             ("merchant_id", 1),
             ("order_date", -1)
         ])
@@ -97,11 +97,11 @@ async def drop_indexes():
     try:
         logger.warning("Dropping all database indexes")
         
-        await db[SCM_MERCHANTS_COLLECTION].drop_indexes()
-        await db[SCM_EMPLOYEES_COLLECTION].drop_indexes()
-        await db[SCM_ROLES_COLLECTION].drop_indexes()
-        await db[SCM_AUTH_LOGS_COLLECTION].drop_indexes()
-        await db[SCM_SALES_ORDERS_COLLECTION].drop_indexes()
+        await get_database()[SCM_MERCHANTS_COLLECTION].drop_indexes()
+        await get_database()[SCM_EMPLOYEES_COLLECTION].drop_indexes()
+        await get_database()[SCM_ROLES_COLLECTION].drop_indexes()
+        await get_database()[SCM_AUTH_LOGS_COLLECTION].drop_indexes()
+        await get_database()[SCM_SALES_ORDERS_COLLECTION].drop_indexes()
         
         logger.info("All database indexes dropped")