igny8/docs/10-BACKEND/SERVICES.md

Services and Modules

Purpose

Describe the backend service layer and module wiring that orchestrate domain models, AI/automation, billing, integration, and publishing.

Code Locations (exact paths)

• Automation services: backend/igny8_core/business/automation/services/automation_service.py, automation_logger.py
• Billing services: backend/igny8_core/business/billing/services/credit_service.py, invoice_service.py, payment_service.py
• Integration service: backend/igny8_core/business/integration/services/integration_service.py
• Additional service directories (see module-specific docs for details):
  • Planner: backend/igny8_core/business/planning/services/*
  • Content/Writer: backend/igny8_core/business/content/services/*
  • Automation tasks: backend/igny8_core/business/automation/tasks.py
  • Integration sync: backend/igny8_core/business/integration/services/*
  • Publishing: backend/igny8_core/business/publishing/services/*
  • Optimization: backend/igny8_core/business/optimization/services/*
  • Linking: backend/igny8_core/business/linking/services/*

High-Level Responsibilities

• Orchestrate multi-stage automation that chains planner and writer operations using AI and credits.
• Manage credit pricing, balance checks, deductions, and ledger logging.
• Generate invoices and handle billing documents.
• Create, update, test, and list site integrations for external platforms.
• Provide domain-specific service hooks for planner, writer, publishing, linking, and optimization flows (behavior documented in module-specific files).

Detailed Behavior

Automation

• AutomationService enforces single concurrent run per site via cache lock, estimates required credits, checks account balance (with buffer), and creates an AutomationRun. It sequences stages (keywords→clusters, clusters→ideas, ideas→tasks/content, image prompt generation, image generation queue) using AI functions (AutoClusterFunction, GenerateIdeasFunction, GenerateContentFunction, GenerateImagePromptsFunction) through AIEngine, and the Celery image queue (process_image_generation_queue). It supports pause/cancel checks mid-stage, records partial progress, and advances current_stage with per-stage result JSON and credit tallies. Batch sizes and delays respect AutomationConfig.
• AutomationLogger creates per-run directories (and optional shared mirrors), generates run IDs, writes main/stage logs, mirrors to shared folders when configured, and emits structured JSONL trace events for run start, progress, completion, and errors.

Billing

• CreditService computes credit cost by first consulting CreditCostConfig (unit-aware for words/items/images) and falling back to constants. It checks balances, deducts credits atomically, updates account balance, writes CreditTransaction, and logs usage in CreditUsageLog with optional model/token metadata. It can also add credits and provides legacy check helpers.
• InvoiceService generates invoice numbers per account/month, creates invoices for subscriptions or credit packages (adding line items and computing totals), supports custom invoices, and marks invoices paid or void. PDF generation is currently a placeholder.
• PaymentService (see file) processes payments against invoices and updates statuses; details are documented in the module file.

Integration

• IntegrationService creates, updates, deletes, fetches, and lists SiteIntegration records, setting account/site automatically. It can test connections per platform (WordPress, Shopify) and delegates to platform-specific test helpers inside the service; unimplemented platforms raise NotImplementedError. Credentials are set via set_credentials, which currently stores JSON as-is.
• Additional sync services (content_sync_service.py, sync_service.py, sync_metadata_service.py, sync_health_service.py) coordinate publish/sync flows and health checks; see module docs for specifics.

Other Service Areas (structure)

• Planner services (clustering_service.py, ideas_service.py) handle clustering/idea logic.
• Content services (content_generation_service.py, content_pipeline_service.py, metadata_mapping_service.py, validation_service.py) manage content generation, pipelines, metadata mapping, and validation.
• Publishing services (publisher_service.py, deployment_service.py, adapters/) manage publishing/deployment flows and destination adapters.
• Optimization services (analyzer.py, optimizer_service.py) analyze and optimize content.
• Linking services (candidate_engine.py, injection_engine.py, linker_service.py) prepare and apply link suggestions.
• Automation tasks (business/automation/tasks.py) provide Celery entrypoints for automation runs.

Execution Flow

• Automation: AutomationService.start_automation acquires lock → credit estimate/check → create AutomationRun → stage methods query planner/writer models, call AI functions via AIEngine, respect batch sizes/delays, and update run state/logs → credits are tallied from AITaskLog differences.
• Billing: operations call CreditService.check_*/deduct_* before AI or content operations; invoices are created through InvoiceService and payments processed via PaymentService.
• Integration: API endpoints invoke IntegrationService to persist integrations, retrieve lists, and run connection tests; sync services handle subsequent data movement.
• Other domains: planner/content/publishing/linking/optimization services orchestrate their models and, where applicable, AI or external adapters; see domain docs for invocation points.

Cross-Module Interactions

• Automation stages consume planner (Keywords/Clusters/ContentIdeas) and writer (Tasks/Content/Images) data and rely on credit usage logs from AI tasks.
• Billing services are used by automation/AI flows to enforce credit availability and record deductions.
• Integration services connect site data and publishing/sync flows to external platforms; publishing services depend on integration metadata when targeting destinations.
• Planner/content services feed data used by publishing and optimization tasks.

State Transitions (if applicable)

• Automation runs move through stages, can pause/cancel, and record partial progress with stage result JSON.
• Credit balances mutate through add/deduct operations; transactions/usage logs capture each change.
• Invoices progress through draft/pending/paid/void and payments through their status lifecycle.
• Integrations toggle active/sync flags and update sync status/errors.

Error Handling

• Automation: checks for concurrent runs; validates minimum keywords; pauses/cancels mid-stage; writes stage error messages; releases locks on failures.
• Billing: raises when credit cost unknown or balance insufficient; wraps changes in atomic transactions.
• Integration: platform test errors are logged and returned with success=false; unsupported platforms raise NotImplementedError.
• Invoice service prevents voiding paid invoices and returns placeholder PDF until implemented.

Tenancy Rules

• Services operate on tenant-scoped models; constructors typically receive account/site or derive them from models. Integration creation sets account from site; credit operations mutate Account.credits.
• Privileged role bypass applies at the viewset layer; persisted records maintain account/site ownership.

Billing Rules (if applicable)

• Costs resolved via CreditCostConfig (preferred) or constants; units can be per request, words (100/200), item, or image.
• Deduct operations both adjust Account.credits and log to CreditTransaction and CreditUsageLog.
• Invoice creation links to subscriptions or credit packages and uses account billing email/plan pricing.

Background Tasks / Schedulers (if applicable)

• Automation uses Celery for image generation and may be triggered by scheduled runs (frequency/time in AutomationConfig).
• Other long-running tasks (publishing, optimization, sync) are handled via their Celery tasks/adapters in respective service modules.

Key Design Considerations

• Automation enforces exclusivity per site and accounts for credit sufficiency before starting.
• Logging (AutomationLogger) produces per-run artifacts and structured traces for observability.
• Credit handling is centralized to keep ledger and usage logs consistent and atomic.
• Integration services abstract platform handling and allow per-platform test logic.

How Developers Should Work With This Module

• Reuse AutomationService for running/continuing automation; respect locks and stage APIs.
• Use CreditService before AI/content-heavy operations to check/deduct/add credits and to log usage.
• Create invoices via InvoiceService helpers rather than constructing manually; update invoice/payment status through service methods.
• Manage integrations through IntegrationService (create/update/test/list) and extend platform-specific tests as needed.
• For domain-specific flows (planner/content/publishing/linking/optimization), place orchestration in the existing service modules and keep tenant context explicit.