# 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.