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