# VPN Access Server - Code Style and Conventions

## Python Version and Requirements
- **Python version**: 3.13+ (minimum requirement)
- **Type hints**: Required for all function parameters and return values
- **Docstrings**: Mandatory for all functions, classes, and modules
- **Encoding**: UTF-8 for all files

## Naming Conventions
- **Functions and variables**: snake_case (e.g., `validate_mac_address`, `user_id`)
- **Classes**: PascalCase (e.g., `ClientRequest`, `DatabaseConnection`)
- **Constants**: UPPER_CASE (e.g., `DEFAULT_SESSION_LIMIT`)
- **Modules**: snake_case (e.g., `auth.py`, `session.py`)

## Import Organization
```python
# Standard library imports
import os
import sys
import logging
from typing import Optional, Dict, Any

# Third-party imports
import mysql.connector
from fastapi import FastAPI

# Local imports
from config import config
from utils import setup_logging
```

## Error Handling
- Use try/except blocks for all database operations and external API calls
- Custom exit codes: 0=success, 1=authentication failure, 2=configuration error
- Log all errors with appropriate log levels
- Use `safe_exit()` utility for graceful error termination

## Logging
- Use `setup_logging()` from `access.utils` for consistent logging
- Structured log format with timestamps, logger name, level, and message
- Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
- File and console handlers supported

## Security Practices
- **SQL**: Always use parameterized queries to prevent injection
- **Credentials**: Store in environment variables, never in code
- **Passwords**: Hash using secure algorithms (bcrypt/scrypt)
- **Configuration**: Validate all configuration before use
- **Access**: Principle of least privilege for database accounts

## Code Structure
- **Functions**: Small, focused, single responsibility
- **Classes**: When needed for related functionality
- **Modules**: Logical grouping of related functions
- **Error messages**: Clear, actionable, and secure (no sensitive data)

## Database Design
- Use foreign keys and constraints
- Index frequently queried columns
- Use appropriate data types
- Handle connection pooling for performance