ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/drf_structure/templates/knowledge/knowledge_design_pattern.md

@@ -0,0 +1,722 @@
+# Design Patterns - {project_name}
+
+This document outlines the design patterns, architectural decisions, and coding conventions used in this NTC-generated Django REST Framework project.
+
+## 🏗️ Architectural Patterns
+
+### **1. Service/Selector Pattern**
+
+**Purpose**: Separate business logic from views and data access logic.
+
+**Structure**:
+```
+apps/myapp/
+├── views.py          # HTTP request/response handling only
+├── services/         # Business logic and operations
+├── selectors/        # Data querying and filtering
+└── serializers/      # Data validation and transformation
+```
+
+**Example Implementation**:
+
+```python
+# selectors/user_selector.py
+from django.db.models import QuerySet
+from apps.users.models import User
+
+def get_active_users() -> QuerySet[User]:
+    """Get all active users."""
+    return User.objects.filter(is_active=True)
+
+def get_user_by_email(email: str) -> User:
+    """Get user by email address."""
+    return User.objects.get(email=email)
+
+# services/user_service.py
+from django.contrib.auth import authenticate
+from apps.users.models import User
+from apps.users.selectors.user_selector import get_user_by_email
+
+def create_user(email: str, password: str, **kwargs) -> User:
+    """Create a new user with validation."""
+    if User.objects.filter(email=email).exists():
+        raise ValueError("User with this email already exists")
+    
+    user = User.objects.create_user(
+        email=email,
+        password=password,
+        **kwargs
+    )
+    return user
+
+def authenticate_user(email: str, password: str) -> User:
+    """Authenticate user credentials."""
+    user = authenticate(email=email, password=password)
+    if not user:
+        raise ValueError("Invalid credentials")
+    return user
+
+# views.py
+from rest_framework.decorators import api_view
+from core.response_wrapper import success_response, error_response
+from .services.user_service import create_user, authenticate_user
+from .selectors.user_selector import get_active_users
+
+@api_view(['POST'])
+def create_user_view(request):
+    """Create a new user."""
+    try:
+        user = create_user(
+            email=request.data['email'],
+            password=request.data['password']
+        )
+        return success_response(
+            data={"user_id": user.id},
+            message="User created successfully"
+        )
+    except ValueError as e:
+        return error_response(message=str(e), code=400)
+```
+
+### **2. Repository Pattern (via Selectors)**
+
+**Purpose**: Abstract data access logic and provide a consistent interface for querying data.
+
+```python
+# selectors/base_selector.py
+from typing import Optional, List
+from django.db.models import Model, QuerySet
+
+class BaseSelector:
+    model = None
+    
+    @classmethod
+    def get_by_id(cls, id: int) -> Optional[Model]:
+        """Get object by ID."""
+        try:
+            return cls.model.objects.get(id=id)
+        except cls.model.DoesNotExist:
+            return None
+    
+    @classmethod
+    def get_all(cls) -> QuerySet:
+        """Get all objects."""
+        return cls.model.objects.all()
+    
+    @classmethod
+    def filter_by(cls, **kwargs) -> QuerySet:
+        """Filter objects by given criteria."""
+        return cls.model.objects.filter(**kwargs)
+
+# selectors/user_selector.py
+from .base_selector import BaseSelector
+from apps.users.models import User
+
+class UserSelector(BaseSelector):
+    model = User
+    
+    @classmethod
+    def get_active_users(cls) -> QuerySet:
+        """Get all active users."""
+        return cls.filter_by(is_active=True)
+```
+
+### **3. Factory Pattern (for Model Creation)**
+
+**Purpose**: Centralize object creation logic with proper validation.
+
+```python
+# services/factories/user_factory.py
+from apps.users.models import User
+from apps.common.models import TimeStampedModel
+
+class UserFactory:
+    @staticmethod
+    def create_user(email: str, password: str, **kwargs) -> User:
+        """Create user with proper validation."""
+        # Validation logic
+        if not email:
+            raise ValueError("Email is required")
+        
+        # Creation logic
+        user = User.objects.create_user(
+            email=email,
+            password=password,
+            **kwargs
+        )
+        
+        # Post-creation logic (send welcome email, etc.)
+        # ...
+        
+        return user
+```
+
+## 🎯 Response Pattern
+
+### **Standardized API Responses**
+
+**Purpose**: Consistent response format across all endpoints.
+
+```python
+# core/response_wrapper.py
+from rest_framework.response import Response
+
+def success_response(data=None, message='Success', status=200):
+    """Standard success response format."""
+    return Response({
+        'status': 'success',
+        'message': message,
+        'data': data
+    }, status=status)
+
+def error_response(message='Error', code=400, errors=None):
+    """Standard error response format."""
+    response_data = {
+        'status': 'error',
+        'message': message
+    }
+    if errors:
+        response_data['errors'] = errors
+    
+    return Response(response_data, status=code)
+
+# Usage in views
+@api_view(['GET'])
+def get_users(request):
+    users = get_active_users()
+    serializer = UserSerializer(users, many=True)
+    return success_response(
+        data=serializer.data,
+        message="Users retrieved successfully"
+    )
+```
+
+## 🗄️ Model Patterns
+
+### **1. Abstract Base Models**
+
+**Purpose**: Provide common fields and functionality across models.
+
+```python
+# apps/common/models.py
+from django.db import models
+
+class TimeStampedModel(models.Model):
+    """Abstract model with timestamp fields."""
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    
+    class Meta:
+        abstract = True
+
+# core/base_model.py
+from django.db import models
+
+class BaseModel(models.Model):
+    """Enhanced base model with common fields."""
+    id = models.BigAutoField(primary_key=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+    
+    class Meta:
+        abstract = True
+        
+    def __str__(self):
+        return f"{self.__class__.__name__}({self.id})"
+
+# Usage in app models
+from apps.common.models import TimeStampedModel
+
+class User(TimeStampedModel):
+    email = models.EmailField(unique=True)
+    first_name = models.CharField(max_length=100)
+    # ... other fields
+```
+
+### **2. Manager Pattern**
+
+**Purpose**: Custom query methods at the model level.
+
+```python
+# apps/users/models.py
+from django.contrib.auth.models import AbstractUser
+from django.db import models
+
+class ActiveUserManager(models.Manager):
+    """Manager for active users only."""
+    def get_queryset(self):
+        return super().get_queryset().filter(is_active=True)
+
+class User(AbstractUser):
+    email = models.EmailField(unique=True)
+    
+    # Managers
+    objects = models.Manager()  # Default manager
+    active = ActiveUserManager()  # Custom manager
+    
+    USERNAME_FIELD = 'email'
+    REQUIRED_FIELDS = []
+
+# Usage
+active_users = User.active.all()  # Only active users
+all_users = User.objects.all()    # All users
+```
+
+## 🔐 Authentication Patterns
+
+### **JWT Token Pattern**
+
+**Purpose**: Stateless authentication with refresh token support.
+
+```python
+# services/auth_service.py
+from rest_framework_simplejwt.tokens import RefreshToken
+from django.contrib.auth import authenticate
+
+class AuthService:
+    @staticmethod
+    def login_user(email: str, password: str) -> dict:
+        """Authenticate user and return tokens."""
+        user = authenticate(email=email, password=password)
+        if not user:
+            raise ValueError("Invalid credentials")
+        
+        refresh = RefreshToken.for_user(user)
+        return {
+            'refresh': str(refresh),
+            'access': str(refresh.access_token),
+            'user': {
+                'id': user.id,
+                'email': user.email,
+                'first_name': user.first_name,
+            }
+        }
+    
+    @staticmethod
+    def refresh_token(refresh_token: str) -> dict:
+        """Refresh access token."""
+        try:
+            refresh = RefreshToken(refresh_token)
+            return {
+                'access': str(refresh.access_token)
+            }
+        except Exception:
+            raise ValueError("Invalid refresh token")
+```
+
+## 📊 Serializer Patterns
+
+### **Nested Serializer Pattern**
+
+**Purpose**: Handle complex data relationships efficiently.
+
+```python
+# serializers/user_serializer.py
+from rest_framework import serializers
+from apps.users.models import User, Profile
+
+class ProfileSerializer(serializers.ModelSerializer):
+    class Meta:
+        model = Profile
+        fields = ['bio', 'avatar', 'phone']
+
+class UserSerializer(serializers.ModelSerializer):
+    profile = ProfileSerializer(read_only=True)
+    full_name = serializers.SerializerMethodField()
+    
+    class Meta:
+        model = User
+        fields = ['id', 'email', 'first_name', 'last_name', 'full_name', 'profile']
+        
+    def get_full_name(self, obj):
+        return f"{obj.first_name} {obj.last_name}".strip()
+
+class UserCreateSerializer(serializers.ModelSerializer):
+    password = serializers.CharField(write_only=True)
+    
+    class Meta:
+        model = User
+        fields = ['email', 'first_name', 'last_name', 'password']
+        
+    def create(self, validated_data):
+        password = validated_data.pop('password')
+        user = User.objects.create_user(password=password, **validated_data)
+        return user
+```
+
+## 🔄 Task Patterns (Celery)
+
+### **Background Task Pattern**
+
+**Purpose**: Handle long-running operations asynchronously.
+
+```python
+# tasks/email_tasks.py
+from celery import shared_task
+from django.core.mail import send_mail
+from django.conf import settings
+
+@shared_task
+def send_welcome_email(user_id: int):
+    """Send welcome email to new user."""
+    from apps.users.models import User
+    
+    try:
+        user = User.objects.get(id=user_id)
+        send_mail(
+            subject='Welcome to {project_name}',
+            message=f'Welcome {user.first_name}!',
+            from_email=settings.DEFAULT_FROM_EMAIL,
+            recipient_list=[user.email],
+        )
+        return f"Welcome email sent to {user.email}"
+    except User.DoesNotExist:
+        return f"User with ID {user_id} not found"
+
+# Usage in services
+from .tasks.email_tasks import send_welcome_email
+
+def create_user(email: str, password: str) -> User:
+    user = User.objects.create_user(email=email, password=password)
+    
+    # Send welcome email asynchronously
+    send_welcome_email.delay(user.id)
+    
+    return user
+```
+
+## 🧪 Testing Patterns
+
+### **Test Organization Pattern**
+
+**Purpose**: Structured testing approach with proper fixtures.
+
+```python
+# tests/test_user_service.py
+from django.test import TestCase
+from apps.users.services.user_service import create_user, authenticate_user
+from apps.users.models import User
+
+class UserServiceTest(TestCase):
+    def setUp(self):
+        """Set up test data."""
+        self.user_data = {
+            'email': 'test@example.com',
+            'password': 'testpass123',
+            'first_name': 'Test'
+        }
+    
+    def test_create_user_success(self):
+        """Test successful user creation."""
+        user = create_user(**self.user_data)
+        
+        self.assertIsInstance(user, User)
+        self.assertEqual(user.email, self.user_data['email'])
+        self.assertTrue(user.check_password(self.user_data['password']))
+    
+    def test_create_user_duplicate_email(self):
+        """Test user creation with duplicate email."""
+        create_user(**self.user_data)
+        
+        with self.assertRaises(ValueError):
+            create_user(**self.user_data)
+```
+
+## 📋 Naming Conventions
+
+### **File and Directory Naming**
+- **Apps**: `snake_case` (e.g., `user_management`)
+- **Models**: `PascalCase` (e.g., `UserProfile`)
+- **Views**: `snake_case` functions (e.g., `create_user_view`)
+- **Services**: `snake_case` functions (e.g., `create_user`)
+- **URLs**: `kebab-case` (e.g., `/api/user-profile/`)
+
+### **Variable Naming**
+- **Python**: `snake_case`
+- **Constants**: `UPPER_SNAKE_CASE`
+- **Private methods**: `_leading_underscore`
+- **Class methods**: `snake_case`
+
+## 🎯 Error Handling Patterns
+
+### **Centralized Error Handling**
+
+```python
+# core/exceptions.py
+class BusinessLogicError(Exception):
+    """Custom exception for business logic errors."""
+    def __init__(self, message, code=400):
+        self.message = message
+        self.code = code
+        super().__init__(self.message)
+
+# services/base_service.py
+from core.exceptions import BusinessLogicError
+
+class BaseService:
+    @staticmethod
+    def validate_required_fields(data: dict, required_fields: list):
+        """Validate required fields in data."""
+        missing_fields = [field for field in required_fields if not data.get(field)]
+        if missing_fields:
+            raise BusinessLogicError(
+                f"Missing required fields: {', '.join(missing_fields)}"
+            )
+```
+
+## 🌐 External Service Patterns
+
+### **Azure Communication Services Email Pattern**
+
+**Purpose**: Send emails through Azure Communication Services with template support.
+
+```python
+# core/services/azure/email/notifier.py
+from core.services.azure.email import send_template_email
+
+# Send templated email
+send_template_email(
+    subject="Welcome to {project_name}",
+    to="user@example.com",
+    template="welcome_email",  # Looks for welcome_email.html and welcome_email.txt
+    context={"name": "John", "verification_url": "https://..."},
+    sender="notification",  # or "no_reply", "support", "marketing"
+    fail_silently=False
+)
+```
+
+**Template Structure**:
+```
+templates/
+├── welcome_email.html    # Required HTML template
+└── welcome_email.txt     # Optional plain text template (auto-generated if missing)
+```
+
+**Sender Configuration**:
+- `no_reply`: For automated system emails
+- `notification`: For user notifications
+- `support`: For support emails
+- `marketing`: For marketing emails
+
+**Environment Variables**:
+```bash
+AZURE_COMMUNICATION_ENDPOINT=https://xxx.communication.azure.com
+AZURE_COMMUNICATION_ACCESS_KEY=your-access-key
+AZURE_COMMUNICATION_EMAIL_SENDER_NOTIFICATION=DoNotReply@xxx.azurecomm.net
+AZURE_COMMUNICATION_EMAIL_SENDER_NO_REPLY=DoNotReply@xxx.azurecomm.net
+```
+
+### **Cloudflare R2 Object Storage Pattern**
+
+**Purpose**: Store and manage files in Cloudflare R2 (S3-compatible storage).
+
+```python
+from core.services.object_storage import ObjectStorageService
+
+# Initialize storage service
+storage = ObjectStorageService()
+
+# Upload file
+public_url, storage_key = storage.upload_file(
+    uploaded_file=request.FILES['avatar'],
+    key=f"users/{user_id}/avatar"
+)
+
+# Upload user avatar
+public_url, key = storage.upload_user_avatar(user_id, uploaded_file)
+
+# Upload workspace logo
+public_url, key = storage.upload_workspace_logo(workspace_id, uploaded_file)
+
+# Upload workspace media
+public_url, key = storage.upload_workspace_media(workspace_id, uploaded_file)
+
+# Delete file
+storage.delete_by_key(storage_key)
+
+# Upload from URL (e.g., social media image)
+public_url, key = storage.upload_image_from_url(
+    image_url="https://example.com/image.jpg",
+    key=f"users/{user_id}/avatar"
+)
+
+# Extract storage key from URL
+storage_key = storage.key_from_url(public_url)
+```
+
+**File Validation**:
+```python
+from core.services.object_storage import (
+    validate_uploaded_file,
+    IMAGE_MIME_TYPES,
+    AVATAR_MIME_TYPES
+)
+
+# Validate file
+error = validate_uploaded_file(
+    uploaded_file,
+    allowed_mime_types=IMAGE_MIME_TYPES,
+    max_size_bytes=5 * 1024 * 1024  # 5MB
+)
+if error:
+    return error_response(message=error, code=400)
+```
+
+**Environment Variables**:
+```bash
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=your-access-key-id
+R2_SECRET_ACCESS_KEY=your-secret-access-key
+R2_BUCKET=your-bucket-name
+R2_PUBLIC_BASE_URL=https://pub-xxx.r2.dev
+R2_MEDIA_PATH=media
+```
+
+### **Sentry Error Tracking Pattern**
+
+**Purpose**: Automatic error tracking and performance monitoring.
+
+**Configuration**: Sentry is automatically initialized when `SENTRY_DSN` is set.
+
+```python
+# Environment variable
+SENTRY_DSN=https://xxx@sentry.io/xxx
+
+# Sentry automatically captures:
+# - Uncaught exceptions
+# - All log levels (if enable_logs=True)
+# - Performance traces (traces_sample_rate=1.0)
+# - Profile data (profiles_sample_rate=1.0)
+# - Request headers and IP (send_default_pii=True)
+```
+
+**Manual Error Reporting**:
+```python
+import sentry_sdk
+
+# Capture exception
+try:
+    risky_operation()
+except Exception as e:
+    sentry_sdk.capture_exception(e)
+    raise
+
+# Capture message
+sentry_sdk.capture_message("Something important happened")
+
+# Add context
+with sentry_sdk.configure_scope() as scope:
+    scope.set_user({"id": user.id, "email": user.email})
+    scope.set_tag("environment", "production")
+```
+
+## 🐳 Docker and Production Patterns
+
+### **Docker Multi-Stage Build Pattern**
+
+**Purpose**: Optimized production Docker builds with minimal image size.
+
+```dockerfile
+# Multi-stage build (already configured in Dockerfile)
+FROM python:3.12-slim as builder
+# Install build dependencies and compile packages
+
+FROM python:3.12-slim as runtime
+# Copy only compiled packages and application code
+# Result: Smaller production image
+```
+
+### **Nginx Reverse Proxy Pattern**
+
+**Purpose**: Serve static files and proxy application requests.
+
+```nginx
+# config/http.conf (already configured)
+server {
+    listen 80;
+    
+    # WebSocket support
+    location /ws/ {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+    
+    # Regular HTTP requests
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}
+```
+
+### **Gunicorn + Uvicorn Workers Pattern**
+
+**Purpose**: Production-grade ASGI server with multiple workers.
+
+```python
+# config/gunicorn_config.py (already configured)
+command = '{project_name}.asgi:application'
+pythonpath = '.'
+bind = '0.0.0.0:8000'
+workers = 4  # Auto-calculated based on CPU count
+worker_class = 'uvicorn.workers.UvicornWorker'
+```
+
+### **Entry Script Pattern**
+
+**Purpose**: Graceful service startup and shutdown.
+
+```bash
+# .entry/start_core_backend.sh (already configured)
+# Start nginx in background
+nginx -c /app/config/http.conf
+
+# Start gunicorn in background
+gunicorn config.gunicorn_config &
+
+# Handle graceful shutdown on SIGTERM/SIGINT
+trap 'kill -TERM $NGINX_PID; kill -TERM $GUNICORN_PID' TERM INT
+
+# Wait for processes
+wait $GUNICORN_PID
+```
+
+## 🔒 Production Configuration Pattern
+
+### **Environment-Based Settings Pattern**
+
+**Purpose**: Separate configurations for development and production.
+
+```python
+# settings/base.py (shared settings)
+DEBUG = env.bool('DEBUG', default=False)
+SENTRY_DSN = env('SENTRY_DSN', default='')
+AZURE_COMMUNICATION_ENDPOINT = env('AZURE_COMMUNICATION_ENDPOINT', default='')
+
+# settings/dev.py (development overrides)
+DEBUG = True
+
+# settings/prod.py (production overrides)
+DEBUG = False
+SESSION_COOKIE_SECURE = True
+CSRF_COOKIE_SECURE = True
+SECURE_SSL_REDIRECT = True
+SECURE_PROXY_SSL_HEADER = ('HTTP_X_FORWARDED_PROTO', 'https')
+```
+
+### **ASGI/WSGI Production Settings Pattern**
+
+**Purpose**: Use production settings in Docker environment.
+
+```python
+# asgi.py (uses prod settings)
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{project_name}.settings.prod')
+
+# wsgi.py (uses prod settings)
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{project_name}.settings.prod')
+```
+
+This design pattern documentation ensures consistent, maintainable, and scalable code across the entire project. AI assistants should follow these patterns when working with the codebase.