igny8/old-docs/igny8-app/IGNY8-APP-ARCHITECTURE.md

IGNY8 App Architecture (code-sourced, Dec 2025)

Authoritative snapshot derived from the current codebase (backend Django/DRF, frontend React/Vite). No legacy docs referenced.

1) Platform Overview

• Multi-tenant: All tenant-scoped models inherit AccountBaseModel; site/sector models inherit SiteSectorBaseModel (backend/igny8_core/auth/models.py).
• APIs (wired in backend/igny8_core/urls.py): /api/v1/auth/, /api/v1/account/, /api/v1/planner/, /api/v1/writer/, /api/v1/system/, /api/v1/billing/ (tenant billing), /api/v1/admin/ (billing admin + credit costs), /api/v1/automation/, /api/v1/linker/, /api/v1/optimizer/, /api/v1/publisher/, /api/v1/integration/.
• Frontend routes (in frontend/src/App.tsx): Planner, Writer, Automation, Linker, Optimizer, Thinker, Billing, Account, Admin sections; sidebar defined in frontend/src/layout/AppSidebar.tsx.

2) Backend Modules & Endpoints

• Planner (modules/planner/urls.py): /keywords, /clusters, /ideas via ViewSets.
• Writer (modules/writer/urls.py): /tasks, /images, /content, /taxonomies.
• Automation (business/automation/urls.py): root ViewSet for automation orchestration.
• Linker (modules/linker/urls.py): root ViewSet for internal linking.
• Optimizer (modules/optimizer/urls.py): root ViewSet for optimization analysis.
• Publisher (modules/publisher/urls.py): /publishing-records, /deployments, root publisher actions, plus public sites/<id>/definition/.
• Integration (modules/integration/urls.py): /integrations, WordPress webhooks at /webhooks/wordpress/status|metadata/.
• System (modules/system/urls.py): prompts, author profiles, strategies, settings (system/account/user/modules/ai), module enable toggle at /settings/modules/enable/, health/status/metrics, Gitea webhook, integration settings save/test/generate/progress routes.
• Account (api/urls.py): /settings, /team, /usage/analytics/.
• Billing (tenant) (business/billing/urls.py): invoices, payments (list + manual submit + available methods), credit-packages, credit-transactions, payment-methods (CRUD + set_default), credits balance/usage/transactions.
• Billing (admin) (modules/billing/admin_urls.py under /api/v1/admin/): stats, users credit adjustments, credit costs, plus aliases to AdminBillingViewSet for invoices, payments, pending_payments, approve/reject, payment-method-configs, account-payment-methods (CRUD + set_default).

3) Billing & Credits Data Model (key fields)

• Invoice: subtotal, tax, total, currency, status, invoice_date, due_date, paid_at, line_items, stripe_invoice_id, payment_method, billing period fields; helper properties expose subtotal_amount, tax_amount, total_amount for compatibility.
• Payment: statuses include pending_approval, processing, completed/succeeded, failed/refunded/cancelled; methods include stripe, paypal, bank_transfer, local_wallet, manual; tracks intent/charge ids, manual references, approvals, timestamps, failure_reason.
• CreditPackage: slugged packages with price, credits, stripe/paypal ids, is_active, is_featured, sort_order, features JSON.
• CreditTransaction: transaction_type, amount, balance_after, metadata, reference_id (invoice/payment), account-scoped.
• CreditUsageLog: operation_type, credits_used, tokens/model, related object refs, metadata; account-scoped.
• CreditCostConfig: per-operation configurable costs (admin editable).
• Account billing fields: billing email/address/tax_id on Account (multi-tenant).

4) Frontend Surface (routes & guards)

• Planner: /planner/keywords, /planner/clusters, /planner/clusters/:id, /planner/ideas.
• Writer: /writer/tasks, /writer/content, /writer/content/:id, /writer/drafts (redirect), /writer/images, /writer/review, /writer/published.
• Automation: /automation.
• Linker: /linker, /linker/content.
• Optimizer: /optimizer, /optimizer/content, /optimizer/analyze/:id.
• Thinker: /thinker redirect → /thinker/prompts; also /thinker/author-profiles, /thinker/profile, /thinker/strategies, /thinker/image-testing.
• Billing (tenant module): /billing/overview, /billing/credits, /billing/transactions, /billing/usage.
• Account: /account/plans, /account/billing, /account/purchase-credits, /account/settings, /account/team, /account/usage.
• Admin: /admin/dashboard, /admin/accounts, /admin/subscriptions, /admin/account-limits, /admin/billing, /admin/invoices, /admin/payments, /admin/payments/approvals, /admin/credit-packages.
• Sidebar source: frontend/src/layout/AppSidebar.tsx (Account group contains Plans & Billing, Plans, Team Management, Usage & Analytics).

5) Multi-Tenancy & Roles

• Tenant isolation via AccountBaseModel FKs (account_id/tenant_id column) with indexes; site/sector models enforce belonging to same account.
• Admin-only endpoints served under /api/v1/admin/ (developer/superuser expected; see billing admin ViewSet).
• Frontend ModuleGuard used for module-based access on feature modules (planner/writer/linker/optimizer/thinker); account/billing pages are standard routes.

6) Integration & Webhooks

• WordPress status/metadata webhooks at /api/v1/integration/webhooks/wordpress/status|metadata/.
• Gitea webhook at /api/v1/system/webhook/.
• Health: /api/v1/system/ping, /api/v1/system/status, request metrics at /api/v1/system/request-metrics/<request_id>/.

7) Known Documentation Needs (to be maintained)

• Align billing/account docs to the above code-level namespaces and models.
• Add frontend route map (kept here) to the Account/Billing docs.
• Fill docs/user-flow/ (currently empty) with end-to-end user/account/billing flows based on this architecture.