jlframework 1.0.15

A complete Python framework for full-stack development with Azure integration, SMS, SharePoint, and automation capabilities

JLFramework

A complete Python framework for full-stack development with FastAPI and Vue.js, plus comprehensive automation utilities for Azure, SMS, SharePoint, SQL, and more. Create production-ready applications in minutes with Django-like scaffolding and importable utilities.

✨ Features

🚀 Rapid Development

• Rapid Scaffolding - Create full-stack projects in under 5 minutes
• Production-Ready Templates - FastAPI backend + Vue.js frontends with best practices
• Django-like Experience - Clean imports and intuitive CLI commands

🏗️ Full-Stack Templates

• Multiple Frontend Options - Embedded, features, and marketplace templates
• Flexible & Modular - Use only what you need, mix and match templates
• Docker Ready - Dockerfiles included for all templates

🔧 Automation Utilities (New in v1.0.7!)

• SMS Integration - Send SMS via Twilio with delivery tracking
• SharePoint/Email - Microsoft Graph API integration for emails and file operations
• SQL Management - Connection pooling, async/sync queries, retry logic
• Notifications - Automatic Slack and Teams notifications with decorators
• Azure Integration - App Configuration, Blob Storage, and more
• No Hardcoded Credentials - All config from Azure App Configuration or .env files

🔒 Security & Enterprise Features

• Security First - Tenant isolation, OIDC auth, audit logging built-in
• Batteries Included - Database, auth, logging, middleware, and more
• Multi-Environment - Dev, UAT, Prod configuration support

📦 Installation

# Install the framework
pip install jlframework

# Install with all optional dependencies
pip install jlframework[all]

# Install with dev dependencies
pip install jlframework[dev]

🚀 Quick Start

1. Create a Full-Stack Project

# Initialize a new project
jlframework init my-awesome-app
cd my-awesome-app

# Add backend
jlframework add backend

# Add frontend
jlframework add frontend-embedded

# List available templates
jlframework list

2. Use Automation Utilities

from jlframework import (
    # SMS Integration
    SMSHandler,
    
    # SharePoint & Email
    SharePointManager,
    
    # SQL Management
    SqlManager,
    
    # Notifications
    slack_notification,
    teams_notification,
    
    # Azure Integration
    AzureAppConfig,
    BlobStorageManager,
    
    # Utilities
    ExecutionResult,
    ReportStatus,
)

# Send SMS
sms = SMSHandler()
sms.send_sms(to_number="[phone]", message="Hello!")

# Send Email via SharePoint
sp = SharePointManager()
await sp.send_email(
    subject="Test Email",
    body="Hello from jlframework!",
    recipient="[e-mail]"
)

# Query Database with Connection Pooling
sql = SqlManager()
df = await sql.get_async("SELECT * FROM users", "users_data")

# Automatic Notifications
@slack_notification()
async def my_automation(self):
    # Your automation logic
    return ExecutionResult(
        status=ReportStatus.SUCCEEDED,
        records_processed=100
    )

3. Use FastAPI Utilities

from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    AuditManager,
    restrict_access_middleware,
)

app = FastAPI()

# Add middleware
app.middleware("http")(restrict_access_middleware)

@app.get("/api/v1/items")
async def get_items(
    request: Request,
    db: Session = Depends(get_db)
):
    # Get tenant ID from request
    tenant_id = CommonManager.get_tenant_id(request)
    
    # Query database
    items = db.query(Item).filter_by(tenant_id=tenant_id).all()
    
    return {"items": items}

🎯 New Automation Modules (v1.0.7)

SMS Handler

Send SMS messages via Twilio with delivery tracking:

from jlframework import SMSHandler

sms = SMSHandler()

# Send single SMS
sms.send_sms(
    to_number="[phone]",
    message="Your verification code is 123456"
)

# Send bulk SMS
sms.send_bulk_sms(
    to_numbers=["[phone]", "+0987654321"],
    message="Bulk notification"
)

# Check delivery status
status = sms.get_message_status(message_sid)

SharePoint Manager

Microsoft Graph API integration for emails and file operations:

from jlframework import SharePointManager, ContentType

sp = SharePointManager()

# Send email with attachments
await sp.send_email(
    subject="Monthly Report",
    body="<h1>Report</h1><p>Please find attached...</p>",
    recipient="[e-mail]",
    attachments=["report.pdf"],
    content_type=ContentType.Html
)

# Upload file to SharePoint/OneDrive
await sp.upload_file_to_drive(
    folder_path="/Shared Documents/Reports",
    file_name="report.pdf",
    file_path="./report.pdf"
)

# Search SharePoint
results = await sp.search_items_in_drive("quarterly report")

SQL Manager

Singleton SQL manager with connection pooling and retry logic:

from jlframework import SqlManager
import pandas as pd

sql = SqlManager()

# Async query (returns DataFrame)
df = await sql.get_async(
    query="SELECT * FROM customers WHERE region = ?",
    header="customers",
    params=("North",)
)

# Sync query
df = sql.get_sync(
    query="SELECT * FROM orders",
    header="orders"
)

# Execute non-query
await sql.execute_async(
    query="UPDATE customers SET status = ? WHERE id = ?",
    params=("active", 123)
)

# Health check
is_healthy = await sql.check_health()

Notification Decorators

Automatic Slack and Teams notifications:

from jlframework import slack_notification, teams_notification, ExecutionResult, ReportStatus

class MyAutomation:
    @slack_notification()
    async def process_data(self):
        # Your automation logic
        records = await self.fetch_data()
        await self.process_records(records)
        
        # Return execution result
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            records_processed=len(records),
            records_failed=0,
            execution_time=120.5
        )
    
    @teams_notification()
    async def generate_report(self):
        # Automatically sends Teams notification on success/failure
        report = await self.create_report()
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            message="Report generated successfully"
        )

Azure Integration

Azure App Configuration and Blob Storage:

from jlframework import AzureAppConfig, BlobStorageManager

# Load configuration from Azure App Configuration
config = AzureAppConfig()
db_connection = config.get_config_value("DatabaseConnectionString")
api_key = config.get_config_value("ApiKey")

# Use Blob Storage
blob = BlobStorageManager()

# Upload file
await blob.upload_file(
    container_name="reports",
    blob_name="monthly-report.pdf",
    data=file_content
)

# Download file
content = await blob.download_file(
    container_name="reports",
    blob_name="monthly-report.pdf"
)

# List blobs
blobs = await blob.list_blobs(container_name="reports")

📚 Available Templates

Backend

FastAPI backend with:

• Domain-driven design structure
• SQLAlchemy ORM with multiple database support
• Tenant-based access control middleware
• Audit logging with MongoDB
• Azure integration (optional)
• Docker support
• Environment-based configuration

Frontend - Embedded

Vue.js 3 embedded application with:

• Vite build system
• TypeScript support
• Vue Router
• OIDC authentication (optional)
• API service layer
• Tailwind CSS
• Docker + Nginx deployment

Frontend - Features

Vue.js 3 micro-frontend features:

• Modular component architecture
• Custom event system
• Shared state management
• Independent deployment

Frontend - Marketplace

Vue.js 3 marketplace application:

• Full marketplace UI
• Product catalog
• User management
• OIDC authentication

🎯 CLI Commands

jlframework init

Initialize a new project with configuration files.

jlframework init my-project
jlframework init my-project --no-git  # Skip git initialization

jlframework add

Add a template to your project.

jlframework add backend
jlframework add frontend-embedded
jlframework add frontend-features
jlframework add frontend-marketplace
jlframework add backend --skip-install  # Skip dependency installation

jlframework list

List all available templates.

jlframework list

📖 Complete Import Reference

Automation Modules

from jlframework import (
    # SMS Integration
    SMSHandler,
    
    # SharePoint & Email
    SharePointManager,
    ContentType,
    GraphMethod,
    
    # SQL Management
    SqlManager,
    
    # Notifications
    slack_notification,
    teams_notification,
    
    # Azure Integration
    AzureAppConfig,
    BlobStorageManager,
    
    # Utilities
    ExecutionResult,
    ReportStatus,
    ReportRequestError,
    ReportStatusError,
    get_iana_timezone,
)

FastAPI Utilities

from jlframework import (
    # Database
    get_db,
    get_db_session,
    database_middleware,
    initialize_database,
    
    # Handlers
    CommonManager,
    AuditManager,
    AuditData,
    
    # Enums
    AuditStatus,
    AuditAction,
    EntityType,
    
    # Middleware
    restrict_access_middleware,
    get_tenant_id,
    
    # Configuration
    Settings,
    get_settings,
    
    # API Client
    MainSubSysApiManager,
    RequestType,
    ApiError,
    retry_with_backoff,
)

🔧 Configuration

Environment Variables

Create a .env file or use Azure App Configuration:

# Azure App Configuration (Recommended)
APP_CONFIGURATION_CONNECTION_STRING=Endpoint=https://...
APPLICATION_ENVIRONMENT=Dev  # or Uat, Prod

# Or use individual environment variables
# Twilio SMS
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_MESSAGING_SERVICE_SID=your_service_sid

# Microsoft Graph (SharePoint/Email)
MICROSOFT_TENANT_ID=your_tenant_id
MICROSOFT_CLIENT_ID=your_client_id
MICROSOFT_CLIENT_SECRET=your_client_secret

# SQL Database
SQL_CONNECTION_STRING=mssql+pyodbc://...

# Slack Notifications
SLACK_SUCCESS_WEBHOOK=https://hooks.slack.com/...
SLACK_FAILURE_WEBHOOK=https://hooks.slack.com/...

# Teams Notifications
TEAMS_WEBHOOK=https://outlook.office.com/webhook/...

# Azure Storage
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;...

Centralized Configuration Manager (v1.0.13+)

New in v1.0.13: Unified configuration management with ConfigurationManager:

from jlframework.core.config_manager import ConfigurationManager

# Get singleton instance (loads from Azure App Configuration once)
config = ConfigurationManager.get_instance()

# Recommended: Use typed getters with Keys enum
api_url = config.get(config.Keys.MAIN_API_URL)
timeout = config.get_int(config.Keys.TIMEOUT, default=30)
debug = config.get_bool(config.Keys.DEBUG, default=False)

# Backward compatible: Attribute access still works
redis_url = config.Redis
storage = config.StorageConnectionString

Benefits:

• ✅ Single source of truth for all configuration
• ✅ Thread-safe singleton pattern
• ✅ Azure connection string loaded only once
• ✅ Type-safe with ConfigurationKeys enum
• ✅ Backward compatible with old code

See CONFIGURATION_MIGRATION_GUIDE.md for migration details.

Azure App Configuration (Legacy)

Deprecated in v1.0.13, use ConfigurationManager instead:

from jlframework import AzureAppConfig

# Old way (still works but deprecated)
config = AzureAppConfig()
twilio_sid = config.get_config_value("TwilioAccountSid")
db_connection = config.get_config_value("DatabaseConnectionString")

🏗️ Project Structure

After running jlframework init and adding templates:

my-project/
├── .jlframework.json      # Project configuration
├── README.md              # Project documentation
├── .gitignore            # Git ignore patterns
├── .env                  # Environment variables
├── backend/              # FastAPI backend
│   ├── main.py
│   ├── routes.py
│   ├── requirements.txt
│   ├── Dockerfile
│   ├── configs/
│   ├── domains/
│   └── shared/
└── frontend/
    ├── embedded/         # Embedded Vue.js app
    ├── features/         # Micro-frontend features
    └── marketplace/      # Marketplace Vue.js app

🐳 Docker Support

All templates include Dockerfiles for containerization:

# Backend
cd backend
docker build -t my-backend .
docker run -p 8000:8000 my-backend

# Frontend
cd frontend/embedded
docker build -t my-frontend .
docker run -p 80:80 my-frontend

🧪 Development

Running Backend

cd backend
pip install -r requirements.txt
python main.py

Running Frontend

cd frontend/embedded
npm install
npm run dev

📝 Complete Examples

Azure Function App with Automation

import azure.functions as func
from jlframework import (
    AzureAppConfig,
    SqlManager,
    SharePointManager,
    slack_notification,
    ExecutionResult,
    ReportStatus
)

# Load configuration from Azure App Configuration
config = AzureAppConfig()

class DataProcessor:
    def __init__(self):
        self.sql = SqlManager()
        self.sp = SharePointManager()
    
    @slack_notification()
    async def process_daily_report(self):
        # Fetch data from database
        df = await self.sql.get_async(
            "SELECT * FROM orders WHERE date = CAST(GETDATE() AS DATE)",
            "daily_orders"
        )
        
        # Process data
        total_orders = len(df)
        total_revenue = df['amount'].sum()
        
        # Send email report
        await self.sp.send_email(
            subject=f"Daily Report - {total_orders} orders",
            body=f"<h1>Daily Report</h1><p>Total Revenue: ${total_revenue}</p>",
            recipient="[e-mail]"
        )
        
        return ExecutionResult(
            status=ReportStatus.SUCCEEDED,
            records_processed=total_orders,
            message=f"Processed {total_orders} orders"
        )

# Azure Function
async def main(timer: func.TimerRequest) -> None:
    processor = DataProcessor()
    await processor.process_daily_report()

Core Python Application

import asyncio
from jlframework import (
    AzureAppConfig,
    SMSHandler,
    SqlManager,
    ExecutionResult,
    ReportStatus
)

async def send_customer_notifications():
    # Load config
    config = AzureAppConfig()
    
    # Initialize services
    sms = SMSHandler()
    sql = SqlManager()
    
    # Get customers to notify
    customers = await sql.get_async(
        "SELECT phone, name FROM customers WHERE notify = 1",
        "customers"
    )
    
    # Send SMS to each customer
    for _, customer in customers.iterrows():
        sms.send_sms(
            to_number=customer['phone'],
            message=f"Hello {customer['name']}, your order is ready!"
        )
    
    print(f"Sent {len(customers)} notifications")

if __name__ == "__main__":
    asyncio.run(send_customer_notifications())

FastAPI with Full Features

from fastapi import FastAPI, Request, Depends
from sqlalchemy.orm import Session
from jlframework import (
    get_db,
    CommonManager,
    AuditManager,
    AuditData,
    AuditStatus,
    AuditAction,
    EntityType,
    restrict_access_middleware,
    database_middleware,
)

app = FastAPI(title="My API")

# Add middlewares
app.middleware("http")(database_middleware)
app.middleware("http")(restrict_access_middleware)

# Initialize audit manager
audit = AuditManager(
    app_id=1,
    tenant_id="default",
    mongo_connection_string=config.mongo_connection
)

@app.post("/api/v1/customers")
async def create_customer(
    request: Request,
    customer_data: dict,
    db: Session = Depends(get_db)
):
    tenant_id = CommonManager.get_tenant_id(request)
    client_info = CommonManager.get_client_info(request)
    
    # Create customer
    customer = Customer(**customer_data, tenant_id=tenant_id)
    db.add(customer)
    db.commit()
    
    # Log audit
    await audit.save_audit(AuditData(
        status=AuditStatus.SUCCESS,
        action=AuditAction.CREATE,
        entity_type=EntityType.Customer,
        entity_id=customer.id,
        user_id=client_info['user_id'],
        ip_address=client_info['ip_address']
    ))
    
    return {"customer": customer}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

🎯 Use Cases

Perfect For:

• ✅ Azure Function Apps (HTTP, Timer, Queue, Blob triggers)
• ✅ Core Python automation scripts
• ✅ FastAPI web applications
• ✅ Standalone data processing applications
• ✅ Microservices with Azure integration
• ✅ Full-stack web applications
• ✅ Enterprise automation workflows

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastAPI
• Frontend powered by Vue.js
• CLI built with Click
• SMS via Twilio
• Email/SharePoint via Microsoft Graph
• Azure integration via Azure SDK

📞 Support

• 📧 Email: [e-mail]
• 👨‍💻 Developer: Shamasulhaq
• 🐛 Issues: GitHub Issues
• 📦 PyPI: jlframework

🗺️ Roadmap

• SMS integration (Twilio) ✅ v1.0.7
• SharePoint/Email integration (Microsoft Graph) ✅ v1.0.7
• SQL connection pooling and management ✅ v1.0.7
• Slack and Teams notification decorators ✅ v1.0.7
• Azure App Configuration integration ✅ v1.0.7
• Additional database support (MongoDB, PostgreSQL)
• More frontend templates (React, Angular)
• Code generators for models, routes, services
• Database migration tools
• Testing utilities
• Deployment helpers (Kubernetes, Docker Compose)
• VS Code extension
• Web-based project configurator

🎉 What's New

v1.0.15 - Quality Improvements (Current)

• 🔧 Code Quality - Improved code organization and formatting
• 📝 Documentation - Enhanced docstrings and inline documentation
• ✅ Testing - Expanded test coverage and regression tests
• 🐛 Bug Fixes - Minor bug fixes and improvements
• 📊 Metrics - Improved code maintainability and reduced complexity

v1.0.14 - Configuration Consolidation ⚠️ BREAKING CHANGES

• 🔄 Unified Configuration - All configuration now uses ConfigurationManager
• ❌ Removed Deprecated Classes - appconfig_handler.py and azure_config.py removed
• ✅ Backward Compatible - Attribute access still works for smooth migration
• 📚 Migration Guide - See CONFIGURATION_MIGRATION_GUIDE.md

Migration Required: If you were using AzureAppConfig or Configurations, update to ConfigurationManager:

# Old way (v1.0.13 and earlier) - NO LONGER WORKS
from jlframework import AzureAppConfig
config = AzureAppConfig()
value = config.get_config_value("SomeKey")

# New way (v1.0.14+) - REQUIRED
from jlframework.core.config_manager import ConfigurationManager
config = ConfigurationManager.get_instance()
value = config.get("SomeKey")
# Or use attribute access (backward compatible)
value = config.SomeKey

v1.0.13 - Centralized Configuration

• ✨ ConfigurationManager - Unified configuration management
• 🔒 Thread-Safe Singleton - Single source of truth for all configuration
• 🎯 Type-Safe Access - ConfigurationKeys enum for type safety
• ⚡ Performance - Azure connection string loaded only once

v1.0.7 - Automation Modules

• ✨ SMS Handler - Send SMS via Twilio with delivery tracking
• ✨ SharePoint Manager - Microsoft Graph API for emails and file operations
• ✨ SQL Manager - Connection pooling, async/sync queries, retry logic
• ✨ Notification Decorators - Automatic Slack and Teams notifications
• ✨ Enhanced Azure Integration - Better App Configuration and Blob Storage support
• ✨ ExecutionResult - Standardized automation result tracking
• ✨ No Hardcoded Credentials - All config from Azure or environment variables

---

Made with ❤️ by the JLFramework Team