feat: Implement System Users module for authentication and user management

- Added `system_users` package with controllers, models, schemas, and services.
- Created API endpoints for user login, registration, user management, and password change.
- Implemented JWT authentication and user role management.
- Added database management utilities for creating indexes and default roles.
- Updated requirements.txt with necessary dependencies for FastAPI, MongoDB, and JWT handling.
- Created a startup script to set up the environment and run the FastAPI server.

.env

@@ -0,0 +1,46 @@
+# Auth Microservice Environment Configuration
+
+# Application Settings
+APP_NAME=Auth Microservice
+APP_VERSION=1.0.0
+DEBUG=false
+
+# MongoDB Configuration
+MONGODB_URI=mongodb://localhost:27017
+MONGODB_DB_NAME=auth_db
+
+# Redis Configuration (for caching and session management)
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# JWT Configuration
+SECRET_KEY=your-super-secret-jwt-key-change-in-production-please-make-it-very-long-and-random
+ALGORITHM=HS256
+TOKEN_EXPIRATION_HOURS=8
+
+# OTP Configuration
+OTP_TTL_SECONDS=600
+OTP_RATE_LIMIT_MAX=10
+OTP_RATE_LIMIT_WINDOW=600
+
+# Twilio Configuration (for SMS OTP)
+TWILIO_ACCOUNT_SID=
+TWILIO_AUTH_TOKEN=
+TWILIO_PHONE_NUMBER=
+
+# SMTP Configuration (for email notifications)
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_USERNAME=
+SMTP_PASSWORD=
+SMTP_FROM_EMAIL=
+SMTP_USE_TLS=true
+
+# Logging Configuration
+LOG_LEVEL=INFO
+
+# CORS Settings
+CORS_ORIGINS=["http://localhost:3000","http://localhost:8000","http://localhost:8002"]
+

app/__init__.py

@@ -0,0 +1,3 @@
+"""
+Auth Microservice Application Package
+"""

app/auth/__init__.py

@@ -0,0 +1,3 @@
+"""
+Authentication module for Auth microservice
+"""

app/auth/controllers/__init__.py

@@ -0,0 +1,3 @@
+"""
+Authentication controllers module
+"""

app/auth/controllers/router.py

@@ -0,0 +1,408 @@
+"""
+Authentication router for login, logout, and token management endpoints.
+Provides JWT-based authentication with enhanced security features.
+"""
+from datetime import timedelta
+from typing import Optional, List, Dict
+from fastapi import APIRouter, Depends, HTTPException, status, Body, Request
+from pydantic import BaseModel, EmailStr
+import logging
+
+from app.system_users.services.service import SystemUserService
+from app.dependencies.auth import get_system_user_service, get_current_user
+from app.system_users.models.model import SystemUserModel
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+
+def _get_accessible_widgets(user_role) -> List[Dict]:
+    """Generate accessible widgets based on user role for authentication system."""
+    # Base widgets available to all roles - Authentication focused
+    base_widgets = [
+        {
+            "widget_id": "wid_login_count_001",
+            "widget_type": "kpi",
+            "title": "Login Count", 
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_active_users_001",
+            "widget_type": "kpi",
+            "title": "Active Users",
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_failed_logins_001",
+            "widget_type": "kpi", 
+            "title": "Failed Logins (24h)",
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_user_roles_001",
+            "widget_type": "chart",
+            "title": "User Roles Distribution",
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_login_trend_001",
+            "widget_type": "chart",
+            "title": "Login Trend (7 days)",
+            "accessible": True
+        }
+    ]
+    
+    # Advanced widgets for managers and above
+    advanced_widgets = [
+        {
+            "widget_id": "wid_security_events_001",
+            "widget_type": "table",
+            "title": "Recent Security Events",
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_locked_accounts_001",
+            "widget_type": "table", 
+            "title": "Locked Accounts",
+            "accessible": True
+        },
+        {
+            "widget_id": "wid_recent_registrations_001",
+            "widget_type": "table",
+            "title": "Recent User Registrations",
+            "accessible": True
+        }
+    ]
+    
+    # Return widgets based on role
+    if user_role.value in ["super_admin", "admin"]:
+        return base_widgets + advanced_widgets
+    elif user_role.value in ["manager"]:
+        return base_widgets + advanced_widgets[:2]  # Limited advanced widgets
+    else:
+        return base_widgets  # Basic widgets only
+
+
+class LoginRequest(BaseModel):
+    """Login request model."""
+    email_or_phone: str  # Can be email, phone number, or username
+    password: str
+
+
+class LoginResponse(BaseModel):
+    """Login response model."""
+    access_token: str
+    refresh_token: str
+    token_type: str = "bearer"
+    expires_in: int = 1800  # 30 minutes
+    user: dict
+    access_menu: dict
+    warnings: Optional[str] = None
+
+
+class TokenRefreshRequest(BaseModel):
+    """Token refresh request."""
+    refresh_token: str
+
+
+@router.post("/login", response_model=LoginResponse)
+async def login(
+    request: Request,
+    login_data: LoginRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Authenticate user and return JWT tokens.
+    
+    - **email_or_phone**: User email, phone number, or username
+    - **password**: User password
+    """
+    try:
+        # Get client IP and user agent for security tracking
+        client_ip = request.client.host if request.client else None
+        user_agent = request.headers.get("User-Agent")
+        
+        # Authenticate user
+        user, message = await user_service.authenticate_user(
+            login_data.email_or_phone,
+            login_data.password,
+            ip_address=client_ip,
+            user_agent=user_agent
+        )
+        
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=message,
+                headers={"WWW-Authenticate": "Bearer"}
+            )
+        
+        # Create tokens
+        access_token_expires = timedelta(minutes=30)
+        access_token = user_service.create_access_token(
+            data={"sub": user.user_id, "username": user.username, "role": user.role.value},
+            expires_delta=access_token_expires
+        )
+        
+        refresh_token = user_service.create_refresh_token(
+            data={"sub": user.user_id, "username": user.username}
+        )
+        
+        # Flatten permissions to dot notation
+        flattened_permissions = []
+        for module, actions in user.permissions.items():
+            for action in actions:
+                flattened_permissions.append(f"{module}.{action}")
+        
+        # Generate accessible widgets based on user role
+        accessible_widgets = _get_accessible_widgets(user.role)
+        
+        # Return user info without sensitive data
+        user_info = {
+            "user_id": user.user_id,
+            "username": user.username,
+            "email": user.email,
+            "first_name": user.first_name,
+            "last_name": user.last_name,
+            "role": user.role.value,
+            "permissions": user.permissions,
+            "status": user.status.value,
+            "last_login_at": user.last_login_at,
+            "metadata": user.metadata
+        }
+        
+        # Access menu structure
+        access_menu = {
+            "permissions": flattened_permissions,
+            "accessible_widgets": accessible_widgets
+        }
+        
+        logger.info(f"User logged in successfully: {user.username}")
+        
+        return LoginResponse(
+            access_token=access_token,
+            refresh_token=refresh_token,
+            user=user_info,
+            access_menu=access_menu,
+            warnings=None
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Login error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Authentication failed"
+        )
+
+
+class OAuth2LoginRequest(BaseModel):
+    """OAuth2 compatible login request."""
+    username: str  # Can be email or phone
+    password: str
+    grant_type: str = "password"
+
+
+@router.post("/login-form")
+async def login_form(
+    request: Request,
+    form_data: OAuth2LoginRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    OAuth2 compatible login endpoint for form-based authentication.
+    """
+    try:
+        # Get client IP and user agent
+        client_ip = request.client.host if request.client else None
+        user_agent = request.headers.get("User-Agent")
+        
+        # Authenticate user
+        user, message = await user_service.authenticate_user(
+            form_data.username,  # Can be email or phone
+            form_data.password,
+            ip_address=client_ip,
+            user_agent=user_agent
+        )
+        
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=message,
+                headers={"WWW-Authenticate": "Bearer"}
+            )
+        
+        # Create access token
+        access_token_expires = timedelta(minutes=30)
+        access_token = user_service.create_access_token(
+            data={"sub": user.user_id, "username": user.username, "role": user.role.value},
+            expires_delta=access_token_expires
+        )
+        
+        return {
+            "access_token": access_token,
+            "token_type": "bearer"
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Form login error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Authentication failed"
+        )
+
+
+@router.post("/refresh")
+async def refresh_token(
+    refresh_data: TokenRefreshRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Refresh access token using refresh token.
+    """
+    try:
+        # Verify refresh token
+        payload = user_service.verify_token(refresh_data.refresh_token, "refresh")
+        if payload is None:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Invalid refresh token"
+            )
+        
+        user_id = payload.get("sub")
+        username = payload.get("username")
+        
+        # Get user to verify they still exist and are active
+        user = await user_service.get_user_by_id(user_id)
+        if not user or user.status.value != "active":
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="User not found or inactive"
+            )
+        
+        # Create new access token
+        access_token_expires = timedelta(minutes=30)
+        access_token = user_service.create_access_token(
+            data={"sub": user_id, "username": username, "role": user.role.value},
+            expires_delta=access_token_expires
+        )
+        
+        return {
+            "access_token": access_token,
+            "token_type": "bearer",
+            "expires_in": 1800
+        }
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Token refresh error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Token refresh failed"
+        )
+
+
+@router.get("/me")
+async def get_current_user_info(
+    current_user: SystemUserModel = Depends(get_current_user)
+):
+    """
+    Get current user information.
+    """
+    return {
+        "user_id": current_user.user_id,
+        "username": current_user.username,
+        "email": current_user.email,
+        "first_name": current_user.first_name,
+        "last_name": current_user.last_name,
+        "role": current_user.role.value,
+        "permissions": current_user.permissions,
+        "status": current_user.status.value,
+        "last_login_at": current_user.last_login_at,
+        "timezone": current_user.timezone,
+        "language": current_user.language,
+        "metadata": current_user.metadata
+    }
+
+
+@router.post("/logout")
+async def logout(
+    current_user: SystemUserModel = Depends(get_current_user)
+):
+    """
+    Logout current user.
+    Note: In a production environment, you would want to blacklist the token.
+    """
+    logger.info(f"User logged out: {current_user.username}")
+    return {"message": "Successfully logged out"}
+
+
+@router.post("/test-login")
+async def test_login():
+    """
+    Test endpoint to verify authentication system is working.
+    Returns sample login credentials.
+    """
+    return {
+        "message": "Authentication system is ready",
+        "test_credentials": [
+            {
+                "type": "Super Admin",
+                "email": "superadmin@cuatrobeauty.com",
+                "password": "SuperAdmin@123",
+                "description": "Full system access"
+            },
+            {
+                "type": "Company Admin", 
+                "email": "admin@cuatrobeauty.com",
+                "password": "CompanyAdmin@123",
+                "description": "Company-wide management"
+            },
+            {
+                "type": "Manager",
+                "email": "manager@cuatrobeauty.com",
+                "password": "Manager@123", 
+                "description": "Team management"
+            }
+        ]
+    }
+
+
+@router.get("/access-roles")
+async def get_access_roles(
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Get available access roles and their permissions structure.
+    
+    Returns the complete role hierarchy with grouped permissions.
+    """
+    try:
+        # Get roles from database
+        roles = await user_service.get_all_roles()
+        
+        return {
+            "message": "Access roles with grouped permissions structure",
+            "total_roles": len(roles),
+            "roles": [
+                {
+                    "role_id": role.get("role_id"),
+                    "role_name": role.get("role_name"),
+                    "description": role.get("description"),
+                    "permissions": role.get("permissions", {}),
+                    "is_active": role.get("is_active", True)
+                }
+                for role in roles
+            ]
+        }
+    except Exception as e:
+        logger.error(f"Error fetching access roles: {e}")
+        return {
+            "message": "Error fetching access roles",
+            "error": str(e)
+        }

app/cache.py

@@ -0,0 +1,67 @@
+"""
+Cache module for Auth microservice - Redis connection and caching utilities
+"""
+import redis
+from typing import Optional, Any
+import json
+import logging
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class CacheService:
+    """Redis cache service for authentication system"""
+    
+    def __init__(self):
+        self._redis_client: Optional[redis.Redis] = None
+    
+    def get_client(self) -> redis.Redis:
+        """Get Redis client instance"""
+        if self._redis_client is None:
+            self._redis_client = redis.Redis(
+                host=settings.REDIS_HOST,
+                port=settings.REDIS_PORT,
+                password=settings.REDIS_PASSWORD,
+                db=settings.REDIS_DB,
+                decode_responses=True
+            )
+        return self._redis_client
+    
+    async def set(self, key: str, value: Any, ttl: int = 300) -> bool:
+        """Set a value in cache with TTL"""
+        try:
+            client = self.get_client()
+            serialized_value = json.dumps(value) if not isinstance(value, str) else value
+            return client.setex(key, ttl, serialized_value)
+        except Exception as e:
+            logger.error(f"Cache set error: {e}")
+            return False
+    
+    async def get(self, key: str) -> Optional[Any]:
+        """Get a value from cache"""
+        try:
+            client = self.get_client()
+            value = client.get(key)
+            if value:
+                try:
+                    return json.loads(value)
+                except json.JSONDecodeError:
+                    return value
+            return None
+        except Exception as e:
+            logger.error(f"Cache get error: {e}")
+            return None
+    
+    async def delete(self, key: str) -> bool:
+        """Delete a key from cache"""
+        try:
+            client = self.get_client()
+            return client.delete(key) > 0
+        except Exception as e:
+            logger.error(f"Cache delete error: {e}")
+            return False
+
+
+# Global cache instance
+cache_service = CacheService()

app/constants/__init__.py

@@ -0,0 +1,3 @@
+"""
+Constants module for Auth microservice
+"""

app/constants/collections.py

@@ -0,0 +1,11 @@
+"""
+MongoDB collection names for Auth microservice.
+"""
+
+# Collection names
+AUTH_SYSTEM_USERS_COLLECTION = "auth_system_users"
+AUTH_ACCESS_ROLES_COLLECTION = "auth_access_roles"
+AUTH_AUTH_LOGS_COLLECTION = "auth_auth_logs"
+AUTH_OTP_COLLECTION = "auth_otp"
+AUTH_PASSWORD_RESET_COLLECTION = "auth_password_reset"
+AUTH_SESSIONS_COLLECTION = "auth_sessions"

app/core/__init__.py

@@ -0,0 +1,3 @@
+"""
+Core configuration module
+"""

app/core/config.py

@@ -0,0 +1,71 @@
+"""
+Configuration settings for Auth microservice.
+Loads environment variables and provides application settings.
+"""
+import os
+from typing import Optional, List
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables"""
+
+    # Application
+    APP_NAME: str = "Auth Microservice"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = False
+
+    # MongoDB Configuration
+    MONGODB_URI: str = os.getenv("MONGODB_URI", "mongodb://localhost:27017")
+    MONGODB_DB_NAME: str = os.getenv("MONGODB_DB_NAME", "auth_db")
+
+    # Redis Configuration
+    REDIS_HOST: str = os.getenv("REDIS_HOST", "localhost")
+    REDIS_PORT: int = int(os.getenv("REDIS_PORT", "6379"))
+    REDIS_PASSWORD: Optional[str] = os.getenv("REDIS_PASSWORD")
+    REDIS_DB: int = int(os.getenv("REDIS_DB", "0"))
+
+    # JWT Configuration
+    SECRET_KEY: str = os.getenv("SECRET_KEY", "your-secret-key-change-in-production")
+    ALGORITHM: str = os.getenv("ALGORITHM", "HS256")
+    TOKEN_EXPIRATION_HOURS: int = int(os.getenv("TOKEN_EXPIRATION_HOURS", "8"))
+
+    # OTP Configuration
+    OTP_TTL_SECONDS: int = int(os.getenv("OTP_TTL_SECONDS", "600"))
+    OTP_RATE_LIMIT_MAX: int = int(os.getenv("OTP_RATE_LIMIT_MAX", "10"))
+    OTP_RATE_LIMIT_WINDOW: int = int(os.getenv("OTP_RATE_LIMIT_WINDOW", "600"))
+
+    # Twilio Configuration
+    TWILIO_ACCOUNT_SID: Optional[str] = os.getenv("TWILIO_ACCOUNT_SID")
+    TWILIO_AUTH_TOKEN: Optional[str] = os.getenv("TWILIO_AUTH_TOKEN")
+    TWILIO_PHONE_NUMBER: Optional[str] = os.getenv("TWILIO_PHONE_NUMBER")
+
+    # SMTP Configuration
+    SMTP_HOST: Optional[str] = os.getenv("SMTP_HOST")
+    SMTP_PORT: int = int(os.getenv("SMTP_PORT", "587"))
+    SMTP_USERNAME: Optional[str] = os.getenv("SMTP_USERNAME")
+    SMTP_PASSWORD: Optional[str] = os.getenv("SMTP_PASSWORD")
+    SMTP_FROM_EMAIL: Optional[str] = os.getenv("SMTP_FROM_EMAIL")
+    SMTP_USE_TLS: bool = os.getenv("SMTP_USE_TLS", "true").lower() == "true"
+
+    # Logging
+    LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
+
+    # CORS
+    CORS_ORIGINS: List[str] = [
+        "http://localhost:3000",
+        "http://localhost:8000",
+        "http://localhost:8002",
+    ]
+
+    # Pydantic v2 config
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+        extra="allow",  # allows extra environment variables without error
+    )
+
+
+# Global settings instance
+settings = Settings()

app/dependencies/__init__.py

@@ -0,0 +1,3 @@
+"""
+Dependencies module
+"""

app/dependencies/auth.py

@@ -0,0 +1,141 @@
+"""
+Authentication dependencies for FastAPI.
+"""
+from typing import Optional
+from datetime import datetime
+from fastapi import Depends, HTTPException, status
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+from app.system_users.models.model import SystemUserModel, UserRole
+from app.system_users.services.service import SystemUserService
+from app.nosql import get_database
+
+security = HTTPBearer()
+
+
+def get_system_user_service() -> SystemUserService:
+    """
+    Dependency to get SystemUserService instance.
+    
+    Returns:
+        SystemUserService: Service instance with database connection
+    """
+    # get_database() returns AsyncIOMotorDatabase directly, no await needed
+    db = get_database()
+    return SystemUserService(db)
+
+
+async def get_current_user(
+    credentials: HTTPAuthorizationCredentials = Depends(security),
+    user_service: SystemUserService = Depends(get_system_user_service)
+) -> SystemUserModel:
+    """Get current authenticated user from JWT token."""
+    
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    
+    try:
+        # Verify token
+        payload = user_service.verify_token(credentials.credentials, "access")
+        if payload is None:
+            raise credentials_exception
+        
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            raise credentials_exception
+            
+    except Exception:
+        raise credentials_exception
+    
+    # Get user from database
+    user = await user_service.get_user_by_id(user_id)
+    if user is None:
+        raise credentials_exception
+    
+    # Check if user is active
+    if user.status.value != "active":
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="User account is not active"
+        )
+    
+    return user
+
+
+async def get_current_active_user(
+    current_user: SystemUserModel = Depends(get_current_user)
+) -> SystemUserModel:
+    """Get current active user (alias for get_current_user for clarity)."""
+    return current_user
+
+
+async def require_admin_role(
+    current_user: SystemUserModel = Depends(get_current_user)
+) -> SystemUserModel:
+    """Require admin or super_admin role."""
+    if current_user.role not in [UserRole.ADMIN, UserRole.SUPER_ADMIN]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Admin privileges required"
+        )
+    return current_user
+
+
+async def require_super_admin_role(
+    current_user: SystemUserModel = Depends(get_current_user)
+) -> SystemUserModel:
+    """Require super_admin role."""
+    if current_user.role != UserRole.SUPER_ADMIN:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Super admin privileges required"
+        )
+    return current_user
+
+
+def require_permission(permission: str):
+    """Dependency factory to require specific permission."""
+    async def permission_checker(
+        current_user: SystemUserModel = Depends(get_current_user)
+    ) -> SystemUserModel:
+        if (permission not in current_user.permissions and 
+            current_user.role not in [UserRole.ADMIN, UserRole.SUPER_ADMIN]):
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Permission '{permission}' required"
+            )
+        return current_user
+    
+    return permission_checker
+
+
+async def get_optional_user(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(HTTPBearer(auto_error=False)),
+    user_service: SystemUserService = Depends(get_system_user_service)
+) -> Optional[SystemUserModel]:
+    """Get current user if token is provided, otherwise return None."""
+    
+    if credentials is None:
+        return None
+    
+    try:
+        # Verify token
+        payload = user_service.verify_token(credentials.credentials, "access")
+        if payload is None:
+            return None
+        
+        user_id: str = payload.get("sub")
+        if user_id is None:
+            return None
+            
+        # Get user from database
+        user = await user_service.get_user_by_id(user_id)
+        if user is None or user.status.value != "active":
+            return None
+        
+        return user
+        
+    except Exception:
+        return None

app/main.py

@@ -0,0 +1,78 @@
+"""
+Main FastAPI application for AUTH Microservice.
+"""
+import logging
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.core.config import settings
+
+from app.nosql import connect_to_mongo, close_mongo_connection
+from app.system_users.controllers.router import router as system_user_router
+from app.auth.controllers.router import router as auth_router
+
+logger = logging.getLogger(__name__)
+logging.basicConfig(level=logging.INFO)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifespan events"""
+    # Startup
+    logger.info("Starting AUTH Microservice")
+    await connect_to_mongo()
+    logger.info("AUTH Microservice started successfully")
+    
+    yield
+    
+    # Shutdown
+    logger.info("Shutting down AUTH Microservice")
+    await close_mongo_connection()
+    logger.info("AUTH Microservice shut down successfully")
+
+
+# Create FastAPI app
+app = FastAPI(
+    title="AUTH Microservice",
+    description="Authentication & Authorization System - User Management, Login, JWT Tokens & Security",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+    lifespan=lifespan
+)
+
+# CORS middleware
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.CORS_ORIGINS,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+# Health check endpoint
+@app.get("/health", tags=["health"])
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "service": "auth-microservice",
+        "version": "1.0.0"
+    }
+
+
+# Include routers
+app.include_router(auth_router)  # Authentication endpoints (login, logout, token refresh)
+app.include_router(system_user_router)  # User management endpoints (CRUD operations)
+
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(
+        "app.main:app",
+        host="0.0.0.0",
+        port=8002,
+        reload=True,
+        log_level="info"
+    )

app/nosql.py

@@ -0,0 +1,77 @@
+"""
+MongoDB connection and database instance.
+Provides a singleton database connection for the application.
+"""
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+import logging
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseConnection:
+    """Singleton class to manage MongoDB connection"""
+    _client: AsyncIOMotorClient = None
+    _db: AsyncIOMotorDatabase = None
+
+    @classmethod
+    def get_database(cls) -> AsyncIOMotorDatabase:
+        """
+        Get the database instance.
+        
+        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(f"Connecting to MongoDB: {settings.MONGODB_URI}")
+            
+            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(f"Successfully connected to MongoDB database: {settings.MONGODB_DB_NAME}")
+        except Exception as e:
+            logger.error(f"Failed to connect to MongoDB: {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"""
+    await DatabaseConnection.close()
+
+
+def get_database() -> AsyncIOMotorDatabase:
+    """Get the database instance"""
+    return DatabaseConnection.get_database()

app/system_users/__init__.py

@@ -0,0 +1,3 @@
+"""
+System Users module for authentication and user management
+"""

app/system_users/controllers/__init__.py

@@ -0,0 +1,3 @@
+"""
+System Users controllers
+"""

app/system_users/controllers/router.py

@@ -0,0 +1,345 @@
+"""
+System User router for authentication and user management endpoints.
+"""
+from datetime import timedelta
+from typing import List, Optional
+from fastapi import APIRouter, Depends, HTTPException, status, Request
+from fastapi.security import HTTPAuthorizationCredentials
+import logging
+
+from app.system_users.services.service import SystemUserService, ACCESS_TOKEN_EXPIRE_MINUTES
+from app.system_users.schemas.schema import (
+    LoginRequest,
+    LoginResponse,
+    CreateUserRequest,
+    UpdateUserRequest,
+    ChangePasswordRequest,
+    UserInfoResponse,
+    UserListResponse,
+    StandardResponse
+)
+from app.system_users.models.model import UserStatus, SystemUserModel
+from app.dependencies.auth import (
+    get_system_user_service,
+    get_current_user,
+    require_admin_role,
+    require_super_admin_role
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(
+    prefix="/auth",
+    tags=["Authentication & User Management"]
+)
+
+
+@router.post("/login", response_model=LoginResponse)
+async def login(
+    request: Request,
+    login_data: LoginRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Authenticate user and return access token.
+    """
+    try:
+        # Get client IP and user agent
+        client_ip = request.client.host if request.client else None
+        user_agent = request.headers.get("User-Agent")
+        
+        # Authenticate user
+        user, message = await user_service.authenticate_user(
+            email_or_phone=login_data.email_or_phone,
+            password=login_data.password,
+            ip_address=client_ip,
+            user_agent=user_agent
+        )
+        
+        if not user:
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail=message,
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        # Create access token
+        access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+        if login_data.remember_me:
+            access_token_expires = timedelta(hours=24)  # Longer expiry for remember me
+        
+        access_token = user_service.create_access_token(
+            data={"sub": user.user_id, "username": user.username, "role": user.role.value},
+            expires_delta=access_token_expires
+        )
+        
+        # Convert user to response model
+        user_info = user_service.convert_to_user_info_response(user)
+        
+        logger.info(f"User logged in successfully: {user.username}")
+        
+        return LoginResponse(
+            access_token=access_token,
+            token_type="bearer",
+            expires_in=int(access_token_expires.total_seconds()),
+            user_info=user_info
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Login error: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Login failed"
+        )
+
+
+@router.get("/me", response_model=UserInfoResponse)
+async def get_current_user_info(
+    current_user: SystemUserModel = Depends(get_current_user),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Get current user information.
+    """
+    return user_service.convert_to_user_info_response(current_user)
+
+
+@router.post("/users", response_model=UserInfoResponse)
+async def create_user(
+    user_data: CreateUserRequest,
+    current_user: SystemUserModel = Depends(require_admin_role),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Create a new user account. Requires admin privileges.
+    """
+    try:
+        new_user = await user_service.create_user(user_data, current_user.user_id)
+        return user_service.convert_to_user_info_response(new_user)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error creating user: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create user"
+        )
+
+
+@router.get("/users", response_model=UserListResponse)
+async def list_users(
+    page: int = 1,
+    page_size: int = 20,
+    status_filter: Optional[UserStatus] = None,
+    current_user: SystemUserModel = Depends(require_admin_role),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    List users with pagination. Requires admin privileges.
+    """
+    try:
+        if page_size > 100:
+            page_size = 100  # Limit maximum page size
+        
+        users, total_count = await user_service.list_users(page, page_size, status_filter)
+        
+        user_responses = [
+            user_service.convert_to_user_info_response(user) for user in users
+        ]
+        
+        return UserListResponse(
+            users=user_responses,
+            total_count=total_count,
+            page=page,
+            page_size=page_size
+        )
+        
+    except Exception as e:
+        logger.error(f"Error listing users: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve users"
+        )
+
+
+@router.get("/users/{user_id}", response_model=UserInfoResponse)
+async def get_user_by_id(
+    user_id: str,
+    current_user: SystemUserModel = Depends(require_admin_role),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Get user by ID. Requires admin privileges.
+    """
+    user = await user_service.get_user_by_id(user_id)
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+    
+    return user_service.convert_to_user_info_response(user)
+
+
+@router.put("/users/{user_id}", response_model=UserInfoResponse)
+async def update_user(
+    user_id: str,
+    update_data: UpdateUserRequest,
+    current_user: SystemUserModel = Depends(require_admin_role),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Update user information. Requires admin privileges.
+    """
+    try:
+        updated_user = await user_service.update_user(user_id, update_data, current_user.user_id)
+        if not updated_user:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User not found"
+            )
+        
+        return user_service.convert_to_user_info_response(updated_user)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error updating user {user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to update user"
+        )
+
+
+@router.put("/change-password", response_model=StandardResponse)
+async def change_password(
+    password_data: ChangePasswordRequest,
+    current_user: SystemUserModel = Depends(get_current_user),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Change current user's password.
+    """
+    try:
+        success = await user_service.change_password(
+            user_id=current_user.user_id,
+            current_password=password_data.current_password,
+            new_password=password_data.new_password
+        )
+        
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Current password is incorrect"
+            )
+        
+        return StandardResponse(
+            success=True,
+            message="Password changed successfully"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error changing password for user {current_user.user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to change password"
+        )
+
+
+@router.delete("/users/{user_id}", response_model=StandardResponse)
+async def deactivate_user(
+    user_id: str,
+    current_user: SystemUserModel = Depends(require_admin_role),
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Deactivate user account. Requires admin privileges.
+    """
+    try:
+        # Prevent self-deactivation
+        if user_id == current_user.user_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Cannot deactivate your own account"
+            )
+        
+        success = await user_service.deactivate_user(user_id, current_user.user_id)
+        if not success:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="User not found"
+            )
+        
+        return StandardResponse(
+            success=True,
+            message="User deactivated successfully"
+        )
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error deactivating user {user_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to deactivate user"
+        )
+
+
+@router.post("/logout", response_model=StandardResponse)
+async def logout(
+    current_user: SystemUserModel = Depends(get_current_user)
+):
+    """
+    Logout current user.
+    Note: Since we're using stateless JWT tokens, actual logout would require 
+    token blacklisting on the client side or implementing a token blacklist on server.
+    """
+    logger.info(f"User logged out: {current_user.username}")
+    
+    return StandardResponse(
+        success=True,
+        message="Logged out successfully"
+    )
+
+
+# Create default super admin endpoint (for initial setup)
+@router.post("/setup/super-admin", response_model=UserInfoResponse)
+async def create_super_admin(
+    user_data: CreateUserRequest,
+    user_service: SystemUserService = Depends(get_system_user_service)
+):
+    """
+    Create the first super admin user. Only works if no users exist in the system.
+    """
+    try:
+        # Check if any users exist
+        users, total_count = await user_service.list_users(page=1, page_size=1)
+        if total_count > 0:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Super admin already exists or users are present in system"
+            )
+        
+        # Force super admin role
+        user_data.role = "super_admin"
+        
+        # Create super admin
+        super_admin = await user_service.create_user(user_data, "system")
+        
+        logger.info(f"Super admin created: {super_admin.username}")
+        
+        return user_service.convert_to_user_info_response(super_admin)
+        
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Error creating super admin: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create super admin"
+        )

app/system_users/models/__init__.py

@@ -0,0 +1,3 @@
+"""
+System Users models
+"""

app/system_users/models/model.py

@@ -0,0 +1,125 @@
+"""
+System User model for authentication and authorization.
+Represents a system user with login credentials and permissions.
+"""
+from datetime import datetime
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel, Field, EmailStr
+from enum import Enum
+
+
+class UserStatus(str, Enum):
+    """User account status options."""
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+    SUSPENDED = "suspended"
+    LOCKED = "locked"
+    PENDING_ACTIVATION = "pending_activation"
+
+
+class UserRole(str, Enum):
+    """System user roles."""
+    SUPER_ADMIN = "super_admin"
+    ADMIN = "admin"
+    MANAGER = "manager"
+    USER = "user"
+    READ_ONLY = "read_only"
+
+
+class LoginAttemptModel(BaseModel):
+    """Login attempt tracking."""
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    ip_address: Optional[str] = Field(None, description="IP address of login attempt")
+    user_agent: Optional[str] = Field(None, description="User agent string")
+    success: bool = Field(..., description="Whether login was successful")
+    failure_reason: Optional[str] = Field(None, description="Reason for failure if unsuccessful")
+
+
+class SecuritySettingsModel(BaseModel):
+    """User security settings."""
+    require_password_change: bool = Field(default=False, description="Force password change on next login")
+    password_expires_at: Optional[datetime] = Field(None, description="Password expiry date")
+    failed_login_attempts: int = Field(default=0, description="Count of consecutive failed login attempts")
+    last_failed_login: Optional[datetime] = Field(None, description="Timestamp of last failed login")
+    account_locked_until: Optional[datetime] = Field(None, description="Account lock expiry time")
+    last_password_change: Optional[datetime] = Field(None, description="Last password change timestamp")
+    login_attempts: List[LoginAttemptModel] = Field(default_factory=list, description="Recent login attempts (last 10)")
+
+
+class SystemUserModel(BaseModel):
+    """
+    System User data model for authentication and authorization.
+    Represents the complete user document in MongoDB.
+    """
+    user_id: str = Field(..., description="Unique user identifier (UUID/ULID)")
+    username: str = Field(..., description="Unique username (lowercase alphanumeric)")
+    email: EmailStr = Field(..., description="User email address")
+    
+    # Authentication
+    password_hash: str = Field(..., description="Bcrypt hashed password")
+    
+    # Personal information
+    first_name: str = Field(..., description="User first name")
+    last_name: Optional[str] = Field(None, description="User last name")
+    phone: Optional[str] = Field(None, description="User phone number (E.164 format)")
+    
+    # Authorization
+    role: UserRole = Field(default=UserRole.USER, description="Primary user role")
+    permissions: Dict[str, List[str]] = Field(default_factory=dict, description="Grouped permissions by module")
+    
+    # Status and security
+    status: UserStatus = Field(default=UserStatus.PENDING_ACTIVATION, description="Account status")
+    security_settings: SecuritySettingsModel = Field(
+        default_factory=SecuritySettingsModel,
+        description="Security and login settings"
+    )
+    
+    # Session management
+    last_login_at: Optional[datetime] = Field(None, description="Last successful login timestamp")
+    last_login_ip: Optional[str] = Field(None, description="IP address of last login")
+    current_session_token: Optional[str] = Field(None, description="Current JWT token hash for session management")
+    
+    # Profile information
+    profile_picture_url: Optional[str] = Field(None, description="URL to profile picture")
+    timezone: str = Field(default="UTC", description="User timezone")
+    language: str = Field(default="en", description="Preferred language code")
+    
+    # Audit fields
+    created_by: str = Field(..., description="User ID who created this user account")
+    created_at: datetime = Field(default_factory=datetime.utcnow, description="Account creation timestamp")
+    updated_at: Optional[datetime] = Field(None, description="Last update timestamp")
+    updated_by: Optional[str] = Field(None, description="User ID who last updated this record")
+    
+    # Additional data
+    metadata: Optional[Dict[str, Any]] = Field(None, description="Additional metadata")
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "user_id": "usr_01HZQX5K3N2P8R6T4V9W",
+                "username": "john.doe",
+                "email": "john.doe@company.com",
+                "password_hash": "$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LeVMstdMT6jmDQrji",
+                "first_name": "John",
+                "last_name": "Doe",
+                "phone": "+919876543210",
+                "role": "admin",
+                "permissions": {
+                    "customers": ["view", "create", "update"],
+                    "orders": ["view", "create", "update"],
+                    "settings": ["view", "update"]
+                },
+                "status": "active",
+                "security_settings": {
+                    "require_password_change": False,
+                    "failed_login_attempts": 0,
+                    "login_attempts": []
+                },
+                "last_login_at": "2024-11-30T10:30:00Z",
+                "last_login_ip": "192.168.1.100",
+                "timezone": "Asia/Kolkata",
+                "language": "en",
+                "created_by": "system",
+                "created_at": "2024-01-15T08:00:00Z"
+            }
+        }

app/system_users/schemas/__init__.py

@@ -0,0 +1,3 @@
+"""
+System Users schemas
+"""

app/system_users/schemas/schema.py

@@ -0,0 +1,131 @@
+"""
+System User schemas for request/response models.
+"""
+from datetime import datetime
+from typing import Optional, List, Dict
+from pydantic import BaseModel, Field, EmailStr, validator
+from app.system_users.models.model import UserStatus, UserRole
+
+
+class LoginRequest(BaseModel):
+    """Login request schema."""
+    email_or_phone: str = Field(..., description="Email address or phone number", min_length=3, max_length=100)
+    password: str = Field(..., description="User password", min_length=6, max_length=100)
+    remember_me: bool = Field(default=False, description="Keep session active for longer period")
+
+
+class LoginResponse(BaseModel):
+    """Login response schema."""
+    access_token: str = Field(..., description="JWT access token")
+    token_type: str = Field(default="bearer", description="Token type")
+    expires_in: int = Field(..., description="Token expiry time in seconds")
+    user_info: "UserInfoResponse" = Field(..., description="Basic user information")
+
+
+class UserInfoResponse(BaseModel):
+    """User information response schema."""
+    user_id: str = Field(..., description="Unique user identifier")
+    username: str = Field(..., description="Username")
+    email: str = Field(..., description="Email address")
+    first_name: str = Field(..., description="First name")
+    last_name: Optional[str] = Field(None, description="Last name")
+    role: UserRole = Field(..., description="User role")
+    permissions: Dict[str, List[str]] = Field(default_factory=dict, description="User permissions")
+    status: UserStatus = Field(..., description="Account status")
+    last_login_at: Optional[datetime] = Field(None, description="Last login timestamp")
+    profile_picture_url: Optional[str] = Field(None, description="Profile picture URL")
+
+
+class CreateUserRequest(BaseModel):
+    """Create user request schema."""
+    username: str = Field(..., description="Unique username", min_length=3, max_length=30)
+    email: EmailStr = Field(..., description="Email address")
+    password: str = Field(..., description="Password", min_length=8, max_length=100)
+    first_name: str = Field(..., description="First name", min_length=1, max_length=50)
+    last_name: Optional[str] = Field(None, description="Last name", max_length=50)
+    phone: Optional[str] = Field(None, description="Phone number")
+    role: UserRole = Field(default=UserRole.USER, description="User role")
+    permissions: Dict[str, List[str]] = Field(default_factory=dict, description="Additional permissions")
+    
+    @validator('username')
+    def validate_username(cls, v):
+        if not v.replace('_', '').replace('.', '').isalnum():
+            raise ValueError('Username can only contain alphanumeric characters, underscores, and periods')
+        return v.lower()
+    
+    @validator('password')
+    def validate_password(cls, v):
+        if len(v) < 8:
+            raise ValueError('Password must be at least 8 characters long')
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain at least one uppercase letter')
+        if not any(c.islower() for c in v):
+            raise ValueError('Password must contain at least one lowercase letter')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain at least one digit')
+        return v
+
+
+class UpdateUserRequest(BaseModel):
+    """Update user request schema."""
+    first_name: Optional[str] = Field(None, description="First name", min_length=1, max_length=50)
+    last_name: Optional[str] = Field(None, description="Last name", max_length=50)
+    phone: Optional[str] = Field(None, description="Phone number")
+    role: Optional[UserRole] = Field(None, description="User role")
+    permissions: Optional[Dict[str, List[str]]] = Field(None, description="User permissions")
+    status: Optional[UserStatus] = Field(None, description="Account status")
+    timezone: Optional[str] = Field(None, description="User timezone")
+    language: Optional[str] = Field(None, description="Preferred language")
+
+
+class ChangePasswordRequest(BaseModel):
+    """Change password request schema."""
+    current_password: str = Field(..., description="Current password")
+    new_password: str = Field(..., description="New password", min_length=8, max_length=100)
+    
+    @validator('new_password')
+    def validate_new_password(cls, v):
+        if len(v) < 8:
+            raise ValueError('Password must be at least 8 characters long')
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain at least one uppercase letter')
+        if not any(c.islower() for c in v):
+            raise ValueError('Password must contain at least one lowercase letter')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain at least one digit')
+        return v
+
+
+class ResetPasswordRequest(BaseModel):
+    """Reset password request schema."""
+    email: EmailStr = Field(..., description="Email address")
+
+
+class UserListResponse(BaseModel):
+    """User list response schema."""
+    users: List[UserInfoResponse] = Field(..., description="List of users")
+    total_count: int = Field(..., description="Total number of users")
+    page: int = Field(..., description="Current page number")
+    page_size: int = Field(..., description="Number of items per page")
+
+
+class TokenRefreshRequest(BaseModel):
+    """Token refresh request schema."""
+    refresh_token: str = Field(..., description="Refresh token")
+
+
+class LogoutRequest(BaseModel):
+    """Logout request schema."""
+    logout_from_all_devices: bool = Field(default=False, description="Logout from all devices")
+
+
+# Response models
+class StandardResponse(BaseModel):
+    """Standard API response."""
+    success: bool = Field(..., description="Operation success status")
+    message: str = Field(..., description="Response message")
+    data: Optional[dict] = Field(None, description="Response data")
+
+
+# Update forward references
+LoginResponse.model_rebuild()

app/system_users/services/__init__.py

@@ -0,0 +1,3 @@
+"""
+System Users services
+"""

app/system_users/services/service.py

@@ -0,0 +1,432 @@
+"""
+System User service for authentication and user management.
+"""
+import secrets
+from datetime import datetime, timedelta
+from typing import Optional, List, Dict, Any, Tuple
+from motor.motor_asyncio import AsyncIOMotorDatabase
+from passlib.context import CryptContext
+from jose import JWTError, jwt
+from fastapi import HTTPException, status
+import logging
+
+from app.system_users.models.model import (
+    SystemUserModel, 
+    UserStatus, 
+    UserRole, 
+    LoginAttemptModel,
+    SecuritySettingsModel
+)
+from app.system_users.schemas.schema import (
+    CreateUserRequest, 
+    UpdateUserRequest,
+    ChangePasswordRequest,
+    UserInfoResponse
+)
+from app.constants.collections import AUTH_SYSTEM_USERS_COLLECTION, AUTH_ACCESS_ROLES_COLLECTION
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+# Password hashing context
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# JWT settings
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
+REFRESH_TOKEN_EXPIRE_DAYS = 7
+MAX_FAILED_LOGIN_ATTEMPTS = 5
+ACCOUNT_LOCK_DURATION_MINUTES = 15
+
+
+class SystemUserService:
+    """Service class for system user operations."""
+
+    def __init__(self, db: AsyncIOMotorDatabase):
+        self.db = db
+        self.collection = db[AUTH_SYSTEM_USERS_COLLECTION]
+
+    @staticmethod
+    def verify_password(plain_password: str, hashed_password: str) -> bool:
+        """Verify a password against its hash."""
+        try:
+            return pwd_context.verify(plain_password, hashed_password)
+        except Exception as e:
+            logger.error(f"Error verifying password: {e}")
+            return False
+
+    @staticmethod
+    def get_password_hash(password: str) -> str:
+        """Generate password hash."""
+        return pwd_context.hash(password)
+
+    @staticmethod
+    def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+        """Create JWT access token."""
+        to_encode = data.copy()
+        if expires_delta:
+            expire = datetime.utcnow() + expires_delta
+        else:
+            expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
+        
+        to_encode.update({"exp": expire, "type": "access"})
+        encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=ALGORITHM)
+        return encoded_jwt
+
+    @staticmethod
+    def create_refresh_token(data: dict) -> str:
+        """Create JWT refresh token."""
+        to_encode = data.copy()
+        expire = datetime.utcnow() + timedelta(days=REFRESH_TOKEN_EXPIRE_DAYS)
+        to_encode.update({"exp": expire, "type": "refresh"})
+        encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=ALGORITHM)
+        return encoded_jwt
+
+    @staticmethod
+    def verify_token(token: str, token_type: str = "access") -> Optional[Dict[str, Any]]:
+        """Verify JWT token and return payload."""
+        try:
+            payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[ALGORITHM])
+            if payload.get("type") != token_type:
+                return None
+            return payload
+        except JWTError as e:
+            logger.warning(f"Token verification failed: {e}")
+            return None
+
+    async def get_user_by_id(self, user_id: str) -> Optional[SystemUserModel]:
+        """Get user by user_id."""
+        try:
+            user_doc = await self.collection.find_one({"user_id": user_id})
+            if user_doc:
+                return SystemUserModel(**user_doc)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting user by ID {user_id}: {e}")
+            return None
+
+    async def get_user_by_username(self, username: str) -> Optional[SystemUserModel]:
+        """Get user by username."""
+        try:
+            user_doc = await self.collection.find_one({"username": username.lower()})
+            if user_doc:
+                return SystemUserModel(**user_doc)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting user by username {username}: {e}")
+            return None
+
+    async def get_user_by_email(self, email: str) -> Optional[SystemUserModel]:
+        """Get user by email."""
+        try:
+            user_doc = await self.collection.find_one({"email": email.lower()})
+            if user_doc:
+                return SystemUserModel(**user_doc)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting user by email {email}: {e}")
+            return None
+
+    async def get_user_by_phone(self, phone: str) -> Optional[SystemUserModel]:
+        """Get user by phone number."""
+        try:
+            user_doc = await self.collection.find_one({"phone": phone})
+            if user_doc:
+                return SystemUserModel(**user_doc)
+            return None
+        except Exception as e:
+            logger.error(f"Error getting user by phone {phone}: {e}")
+            return None
+
+    async def create_user(self, user_data: CreateUserRequest, created_by: str) -> SystemUserModel:
+        """Create a new user."""
+        try:
+            # Check if username or email already exists
+            existing_user = await self.get_user_by_username(user_data.username)
+            if existing_user:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Username already exists"
+                )
+            
+            existing_email = await self.get_user_by_email(user_data.email)
+            if existing_email:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail="Email already exists"
+                )
+            
+            # Generate user ID
+            user_id = f"usr_{secrets.token_urlsafe(16)}"
+            
+            # Hash password
+            password_hash = self.get_password_hash(user_data.password)
+            
+            # Create user model
+            user_model = SystemUserModel(
+                user_id=user_id,
+                username=user_data.username.lower(),
+                email=user_data.email.lower(),
+                password_hash=password_hash,
+                first_name=user_data.first_name,
+                last_name=user_data.last_name,
+                phone=user_data.phone,
+                role=user_data.role,
+                permissions=user_data.permissions,
+                status=UserStatus.ACTIVE,  # Set as active by default
+                created_by=created_by,
+                created_at=datetime.utcnow()
+            )
+            
+            # Insert to database
+            await self.collection.insert_one(user_model.model_dump())
+            
+            logger.info(f"User created successfully: {user_id}")
+            return user_model
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error creating user: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Failed to create user"
+            )
+
+    async def authenticate_user(self, email_or_phone: str, password: str, ip_address: Optional[str] = None, user_agent: Optional[str] = None) -> Tuple[Optional[SystemUserModel], str]:
+        """Authenticate user with email/phone/username and password."""
+        try:
+            # Get user by email, phone, or username
+            user = await self.get_user_by_email(email_or_phone)
+            if not user:
+                user = await self.get_user_by_phone(email_or_phone)
+            if not user:
+                user = await self.get_user_by_username(email_or_phone)
+            
+            # Record failed attempt if user not found
+            if not user:
+                logger.warning(f"Login attempt with non-existent email/phone/username: {email_or_phone}")
+                return None, "Invalid email, phone number, or username"
+            
+            # Check if account is locked
+            if (user.security_settings.account_locked_until and 
+                user.security_settings.account_locked_until > datetime.utcnow()):
+                return None, f"Account is locked until {user.security_settings.account_locked_until}"
+            
+            # Check account status
+            if user.status not in [UserStatus.ACTIVE]:
+                return None, f"Account is {user.status.value}"
+            
+            # Verify password
+            if not self.verify_password(password, user.password_hash):
+                await self._record_failed_login(user, ip_address, user_agent)
+                return None, "Invalid username or password"
+            
+            # Password correct - reset failed attempts and record successful login
+            await self._record_successful_login(user, ip_address, user_agent)
+            
+            return user, "Authentication successful"
+            
+        except Exception as e:
+            logger.error(f"Error during authentication: {e}")
+            return None, "Authentication failed"
+
+    async def _record_failed_login(self, user: SystemUserModel, ip_address: Optional[str], user_agent: Optional[str]):
+        """Record failed login attempt and update security settings."""
+        try:
+            failed_attempts = user.security_settings.failed_login_attempts + 1
+            now = datetime.utcnow()
+            
+            # Add login attempt to history
+            login_attempt = LoginAttemptModel(
+                timestamp=now,
+                ip_address=ip_address,
+                user_agent=user_agent,
+                success=False,
+                failure_reason="Invalid password"
+            )
+            
+            # Keep only last 10 attempts
+            attempts_history = user.security_settings.login_attempts[-9:] + [login_attempt]
+            
+            update_data = {
+                "security_settings.failed_login_attempts": failed_attempts,
+                "security_settings.last_failed_login": now,
+                "security_settings.login_attempts": [attempt.model_dump() for attempt in attempts_history],
+                "updated_at": now
+            }
+            
+            # Lock account if too many failed attempts
+            if failed_attempts >= MAX_FAILED_LOGIN_ATTEMPTS:
+                lock_until = now + timedelta(minutes=ACCOUNT_LOCK_DURATION_MINUTES)
+                update_data["security_settings.account_locked_until"] = lock_until
+                logger.warning(f"Account locked due to failed login attempts: {user.user_id}")
+            
+            await self.collection.update_one(
+                {"user_id": user.user_id},
+                {"$set": update_data}
+            )
+            
+        except Exception as e:
+            logger.error(f"Error recording failed login: {e}")
+
+    async def _record_successful_login(self, user: SystemUserModel, ip_address: Optional[str], user_agent: Optional[str]):
+        """Record successful login and reset security counters."""
+        try:
+            now = datetime.utcnow()
+            
+            # Add login attempt to history
+            login_attempt = LoginAttemptModel(
+                timestamp=now,
+                ip_address=ip_address,
+                user_agent=user_agent,
+                success=True
+            )
+            
+            # Keep only last 10 attempts
+            attempts_history = user.security_settings.login_attempts[-9:] + [login_attempt]
+            
+            await self.collection.update_one(
+                {"user_id": user.user_id},
+                {"$set": {
+                    "last_login_at": now,
+                    "last_login_ip": ip_address,
+                    "security_settings.failed_login_attempts": 0,
+                    "security_settings.last_failed_login": None,
+                    "security_settings.account_locked_until": None,
+                    "security_settings.login_attempts": [attempt.model_dump() for attempt in attempts_history],
+                    "updated_at": now
+                }}
+            )
+            
+        except Exception as e:
+            logger.error(f"Error recording successful login: {e}")
+
+    async def update_user(self, user_id: str, update_data: UpdateUserRequest, updated_by: str) -> Optional[SystemUserModel]:
+        """Update user information."""
+        try:
+            user = await self.get_user_by_id(user_id)
+            if not user:
+                return None
+            
+            update_dict = {}
+            for field, value in update_data.dict(exclude_unset=True).items():
+                if value is not None:
+                    update_dict[field] = value
+            
+            if update_dict:
+                update_dict["updated_at"] = datetime.utcnow()
+                update_dict["updated_by"] = updated_by
+                
+                await self.collection.update_one(
+                    {"user_id": user_id},
+                    {"$set": update_dict}
+                )
+            
+            return await self.get_user_by_id(user_id)
+            
+        except Exception as e:
+            logger.error(f"Error updating user {user_id}: {e}")
+            return None
+
+    async def change_password(self, user_id: str, current_password: str, new_password: str) -> bool:
+        """Change user password."""
+        try:
+            user = await self.get_user_by_id(user_id)
+            if not user:
+                return False
+            
+            # Verify current password
+            if not self.verify_password(current_password, user.password_hash):
+                return False
+            
+            # Hash new password
+            new_password_hash = self.get_password_hash(new_password)
+            
+            # Update password
+            await self.collection.update_one(
+                {"user_id": user_id},
+                {"$set": {
+                    "password_hash": new_password_hash,
+                    "security_settings.last_password_change": datetime.utcnow(),
+                    "security_settings.require_password_change": False,
+                    "updated_at": datetime.utcnow()
+                }}
+            )
+            
+            logger.info(f"Password changed for user: {user_id}")
+            return True
+            
+        except Exception as e:
+            logger.error(f"Error changing password for user {user_id}: {e}")
+            return False
+
+    async def list_users(self, page: int = 1, page_size: int = 20, status_filter: Optional[UserStatus] = None) -> Tuple[List[SystemUserModel], int]:
+        """List users with pagination."""
+        try:
+            skip = (page - 1) * page_size
+            
+            # Build query filter
+            query_filter = {}
+            if status_filter:
+                query_filter["status"] = status_filter.value
+            
+            # Get total count
+            total_count = await self.collection.count_documents(query_filter)
+            
+            # Get users - don't exclude password_hash to avoid validation errors
+            cursor = self.collection.find(query_filter).skip(skip).limit(page_size).sort("created_at", -1)
+            users = []
+            async for user_doc in cursor:
+                users.append(SystemUserModel(**user_doc))
+            return users, total_count
+            
+        except Exception as e:
+            logger.error(f"Error listing users: {e}")
+            return [], 0
+
+    async def deactivate_user(self, user_id: str, deactivated_by: str) -> bool:
+        """Deactivate user account."""
+        try:
+            result = await self.collection.update_one(
+                {"user_id": user_id},
+                {"$set": {
+                    "status": UserStatus.INACTIVE.value,
+                    "updated_at": datetime.utcnow(),
+                    "updated_by": deactivated_by
+                }}
+            )
+            
+            if result.modified_count > 0:
+                logger.info(f"User deactivated: {user_id}")
+                return True
+            return False
+            
+        except Exception as e:
+            logger.error(f"Error deactivating user {user_id}: {e}")
+            return False
+
+    def convert_to_user_info_response(self, user: SystemUserModel) -> UserInfoResponse:
+        """Convert SystemUserModel to UserInfoResponse."""
+        return UserInfoResponse(
+            user_id=user.user_id,
+            username=user.username,
+            email=user.email,
+            first_name=user.first_name,
+            last_name=user.last_name,
+            role=user.role,
+            permissions=user.permissions,
+            status=user.status,
+            last_login_at=user.last_login_at,
+            profile_picture_url=user.profile_picture_url
+        )
+
+    async def get_all_roles(self) -> List[dict]:
+        """Get all access roles from database."""
+        try:
+            cursor = self.db[AUTH_ACCESS_ROLES_COLLECTION].find({})
+            roles = await cursor.to_list(length=None)
+            return roles
+        except Exception as e:
+            logger.error(f"Error fetching access roles: {e}")
+            return []

app/utils/__init__.py

@@ -0,0 +1,3 @@
+"""
+Utilities module for Auth microservice
+"""

manage_db.py

@@ -0,0 +1,123 @@
+"""
+Database management utilities for Auth microservice
+"""
+import asyncio
+import logging
+from motor.motor_asyncio import AsyncIOMotorClient
+from app.core.config import settings
+from app.constants.collections import (
+    AUTH_SYSTEM_USERS_COLLECTION,
+    AUTH_ACCESS_ROLES_COLLECTION
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def create_indexes():
+    """Create database indexes for better performance"""
+    try:
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        
+        # System Users indexes
+        users_collection = db[AUTH_SYSTEM_USERS_COLLECTION]
+        
+        # Create indexes for users collection
+        await users_collection.create_index("user_id", unique=True)
+        await users_collection.create_index("username", unique=True)
+        await users_collection.create_index("email", unique=True)
+        await users_collection.create_index("phone")
+        await users_collection.create_index("status")
+        await users_collection.create_index("created_at")
+        
+        # Access Roles indexes
+        roles_collection = db[AUTH_ACCESS_ROLES_COLLECTION]
+        await roles_collection.create_index("role_id", unique=True)
+        await roles_collection.create_index("role_name", unique=True)
+        
+        logger.info("Database indexes created successfully")
+        
+    except Exception as e:
+        logger.error(f"Error creating indexes: {e}")
+    finally:
+        client.close()
+
+
+async def create_default_roles():
+    """Create default system roles if they don't exist"""
+    try:
+        client = AsyncIOMotorClient(settings.MONGODB_URI)
+        db = client[settings.MONGODB_DB_NAME]
+        roles_collection = db[AUTH_ACCESS_ROLES_COLLECTION]
+        
+        default_roles = [
+            {
+                "role_id": "role_super_admin",
+                "role_name": "super_admin",
+                "description": "Super Administrator with full system access",
+                "permissions": {
+                    "users": ["view", "create", "update", "delete"],
+                    "roles": ["view", "create", "update", "delete"],
+                    "settings": ["view", "update"],
+                    "auth": ["view", "manage"],
+                    "system": ["view", "manage"]
+                },
+                "is_active": True
+            },
+            {
+                "role_id": "role_admin",
+                "role_name": "admin", 
+                "description": "Administrator with limited system access",
+                "permissions": {
+                    "users": ["view", "create", "update"],
+                    "roles": ["view"],
+                    "settings": ["view", "update"],
+                    "auth": ["view"]
+                },
+                "is_active": True
+            },
+            {
+                "role_id": "role_manager",
+                "role_name": "manager",
+                "description": "Manager with team management capabilities",
+                "permissions": {
+                    "users": ["view", "update"],
+                    "auth": ["view"]
+                },
+                "is_active": True
+            },
+            {
+                "role_id": "role_user",
+                "role_name": "user",
+                "description": "Standard user with basic access",
+                "permissions": {
+                    "auth": ["view"]
+                },
+                "is_active": True
+            }
+        ]
+        
+        for role in default_roles:
+            existing = await roles_collection.find_one({"role_name": role["role_name"]})
+            if not existing:
+                await roles_collection.insert_one(role)
+                logger.info(f"Created default role: {role['role_name']}")
+        
+        logger.info("Default roles setup completed")
+        
+    except Exception as e:
+        logger.error(f"Error creating default roles: {e}")
+    finally:
+        client.close()
+
+
+async def init_database():
+    """Initialize database with indexes and default data"""
+    logger.info("Initializing database...")
+    await create_indexes()
+    await create_default_roles()
+    logger.info("Database initialization completed")
+
+
+if __name__ == "__main__":
+    asyncio.run(init_database())

requirements.txt

@@ -0,0 +1,26 @@
+fastapi==0.104.1
+uvicorn[standard]==0.24.0
+python-multipart==0.0.6
+
+motor==3.3.2
+pymongo==4.6.0
+email-validator==2.3.0
+redis==5.0.1
+
+python-jose[cryptography]==3.3.0
+passlib[bcrypt]==1.7.4
+bcrypt==4.1.3
+pydantic>=2.12.5,<3.0.0
+pydantic-settings>=2.0.0
+
+pytest==7.4.3
+pytest-asyncio==0.21.1
+httpx==0.25.2
+hypothesis==6.92.1
+
+python-dotenv==1.0.0
+
+twilio==8.10.3
+aiosmtplib==3.0.1
+
+python-json-logger==2.0.7

start_server.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Start Auth Microservice
+
+echo "Starting Auth Microservice..."
+
+# Check if virtual environment exists
+if [ ! -d "venv" ]; then
+    echo "Creating virtual environment..."
+    python3 -m venv venv
+fi
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Install dependencies
+echo "Installing dependencies..."
+pip install -r requirements.txt
+
+# Run the application
+echo "Starting FastAPI server..."
+uvicorn app.main:app --host 0.0.0.0 --port 8002 --reload