igny8/old-docs/backend/IGNY8-BACKEND-ARCHITECTURE.md

IGNY8 Backend Architecture (code-sourced, Dec 2025)

Purpose: backend-only view based on current code under backend/. No legacy docs or assumptions.

1) Stack & Cross-Cutting

• Django + DRF; Celery present via backend/igny8_core/celery.py and tasks/.
• Multi-tenancy: models inherit AccountBaseModel (tenant FK tenant_id) or SiteSectorBaseModel for site/sector scoping (backend/igny8_core/auth/models.py). Account carries billing fields (email/address/tax_id).
• Project URLs wired in backend/igny8_core/urls.py.

2) API Namespaces (as routed)

• /api/v1/auth/ → igny8_core.auth.urls (auth + CSV admin helpers).
• /api/v1/account/ → igny8_core.api.urls (account settings, team, usage analytics).
• /api/v1/planner/ → igny8_core.modules.planner.urls (keywords, clusters, ideas ViewSets).
• /api/v1/writer/ → igny8_core.modules.writer.urls (tasks, images, content, taxonomies ViewSets).
• /api/v1/system/ → igny8_core.modules.system.urls (prompts, author profiles, strategies, settings: system/account/user/modules/ai, module-enable toggle, health/status/metrics, Gitea webhook, integration settings save/test/generate/progress).
• /api/v1/billing/ → igny8_core.business.billing.urls (tenant billing: invoices, payments, credit-packages, credit-transactions, payment-methods CRUD/default, credits balance/usage/transactions; manual payment submit; available methods).
• /api/v1/admin/ → igny8_core.modules.billing.admin_urls (billing admin: stats, user credit adjustments, credit costs, invoices/payments/pending approvals, approve/reject, payment-method configs, account payment methods CRUD/default).
• /api/v1/automation/ → igny8_core.business.automation.urls (automation ViewSet).
• /api/v1/linker/ → igny8_core.modules.linker.urls (linker ViewSet).
• /api/v1/optimizer/ → igny8_core.modules.optimizer.urls (optimizer ViewSet).
• /api/v1/publisher/ → igny8_core.modules.publisher.urls (publishing records, deployments, root publisher actions, public site definition).
• /api/v1/integration/ → igny8_core.modules.integration.urls (integrations ViewSet + WordPress status/metadata webhooks).
• OpenAPI docs: /api/schema/, /api/docs/, /api/redoc/.

3) Key Domain Models (code references)

• Billing (business/billing/models.py):
  • Invoice: subtotal, tax, total, currency, status (draft|pending|paid|void|uncollectible), dates, line_items, stripe_invoice_id, payment_method, billing period, helpers subtotal_amount|tax_amount|total_amount.
  • Payment: statuses include pending_approval, processing, completed/succeeded, failed/refunded/cancelled; methods stripe|paypal|bank_transfer|local_wallet|manual; intent/charge ids, manual references, approvals, timestamps, failure_reason.
  • CreditPackage: slugged packages with price, credits, discount_percentage, stripe/paypal ids, is_active, is_featured, sort_order, features.
  • CreditTransaction: transaction_type, amount, balance_after, metadata, reference_id.
  • CreditUsageLog: operation_type, credits_used, tokens/model, related object refs, metadata.
  • CreditCostConfig: per-operation configurable costs (admin-editable).
  • AccountPaymentMethod: CRUD + default toggle; PaymentMethodConfig for availability by country/method.
• Account (auth/models.py): Account with billing fields, credits balance, status, owner, stripe_customer_id; base models enforce tenant scoping.
• Other business areas (content, planning, optimization, publishing, integration) define models/services under backend/igny8_core/business/* (models present in content, planning, optimization, publishing, integration; linking uses services).

4) Services & Admin Surfaces

• Billing services: business/billing/services/invoice_service.py, payment_service.py (used by InvoiceViewSet/PaymentViewSet/admin aliases).
• Admin billing aliases in modules/billing/admin_urls.py map to AdminBillingViewSet plus legacy stats/credit-cost endpoints.
• Module enable and settings handled in modules/system/settings_views.py and integration settings in modules/system/integration_views.py.

5) Automation & Tasks

• Automation API exposed via business/automation/urls.py (AutomationViewSet).
• Celery tasks scaffolded under igny8_core/tasks and tasks.py; workers started via standard Celery entrypoints (see repo root README for commands).

6) Integration & Webhooks

• WordPress webhooks: /api/v1/integration/webhooks/wordpress/status/, /metadata/.
• Gitea webhook: /api/v1/system/webhook/.
• Public site definition: /api/v1/publisher/sites/<site_id>/definition/.

7) Observations / gaps for follow-up

• docs/user-flow/ lacks flows; backend routes above should anchor those docs.
• Ensure billing/admin docs use the namespaces and models listed here (avoid legacy paths). Data shape examples still need to be added alongside serializers.