hesabixArc/hesabixAPI/app/services/pdf/README.md

PDF Service - Modular Architecture

Overview

This is a modular PDF generation service designed for scalability and AI integration. Each module handles specific business domains and can be easily extended.

Structure

app/services/pdf/
├── __init__.py
├── base_pdf_service.py          # Base classes and main service
├── modules/                     # Business domain modules
│   ├── __init__.py
│   └── marketing/               # Marketing & referrals module
│       ├── __init__.py
│       ├── marketing_module.py  # Module implementation
│       └── templates/           # HTML templates
│           └── marketing_referrals.html
└── README.md

Adding New Modules

1. Create Module Directory

mkdir -p app/services/pdf/modules/your_module/templates

2. Implement Module Class

# app/services/pdf/modules/your_module/your_module.py
from ..base_pdf_service import BasePDFModule
from app.core.calendar import CalendarType

class YourModulePDFModule(BasePDFModule):
    def __init__(self):
        super().__init__("your_module")
    
    def generate_pdf(self, data, calendar_type="jalali", locale="fa"):
        # Your PDF generation logic
        pass
    
    def generate_excel_data(self, data, calendar_type="jalali", locale="fa"):
        # Your Excel data generation logic
        pass

3. Register Module

Add to base_pdf_service.py:

def _register_modules(self):
    from .modules.marketing.marketing_module import MarketingPDFModule
    from .modules.your_module.your_module import YourModulePDFModule
    self.modules['marketing'] = MarketingPDFModule()
    self.modules['your_module'] = YourModulePDFModule()

Usage

Generate PDF

from app.services.pdf import PDFService

pdf_service = PDFService()
pdf_bytes = pdf_service.generate_pdf(
    module_name='marketing',
    data=your_data,
    calendar_type='jalali',
    locale='fa'
)

Generate Excel Data

excel_data = pdf_service.generate_excel_data(
    module_name='marketing',
    data=your_data,
    calendar_type='jalali',
    locale='fa'
)

Features

1. Calendar Support

• Automatic Jalali/Gregorian conversion
• Configurable via calendar_type parameter

2. Internationalization

• Built-in translation support
• Template-level translation integration
• Configurable via locale parameter

3. Modular Design

• Easy to add new business domains
• Clean separation of concerns
• Reusable base classes

4. AI Integration Ready

• Function calling compatible
• Clear module boundaries
• Extensible architecture

Template Development

Using Translations

<!-- In your template -->
<h1>{{ t('yourTranslationKey') }}</h1>
<div>{{ t('anotherKey') }}</div>

Calendar Formatting

# In your module
formatted_date = self.format_datetime(datetime_obj, calendar_type)

Data Formatting

# In your module
formatted_data = self._format_data_for_template(data, calendar_type, translator)

Future Extensions

AI Integration

Each module can be exposed as a function for AI systems:

# Example AI function definition
{
    "name": "generate_marketing_pdf",
    "description": "Generate marketing referrals PDF report",
    "parameters": {
        "type": "object",
        "properties": {
            "user_id": {"type": "integer"},
            "filters": {"type": "object"},
            "calendar_type": {"type": "string", "enum": ["jalali", "gregorian"]}
        }
    }
}

Additional Modules

• invoices/ - Invoice generation
• reports/ - General reports
• analytics/ - Analytics dashboards
• notifications/ - Notification templates