igny8/master-docs/10-backend/00-BACKEND-ARCHITECTURE.md

Backend Architecture

Purpose

Explain how the backend is structured, wired, and executed across Django/DRF, middleware, routing, async processing, and logging.

Code Locations (exact paths)

• Settings and app wiring: backend/igny8_core/settings.py
• URL routing: backend/igny8_core/urls.py
• Middleware: backend/igny8_core/middleware/request_id.py, backend/igny8_core/auth/middleware.py, backend/igny8_core/middleware/resource_tracker.py
• Auth stack: backend/igny8_core/api/authentication.py, backend/igny8_core/auth/utils.py
• Base viewsets and unified responses: backend/igny8_core/api/base.py
• Domain models: backend/igny8_core/auth/models.py plus backend/igny8_core/business/*/models.py
• Async/Celery config: backend/igny8_core/settings.py
• Logging: backend/igny8_core/settings.py (publish/webhook logs), automation logging (backend/igny8_core/business/automation/services/automation_logger.py)

High-Level Responsibilities

• Django/DRF API surface under /api/v1/* for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
• Middleware establishes request IDs, tenant context, and optional resource tracking before views run.
• DRF configuration standardizes pagination, filtering, authentication, throttling, and exception handling.
• Celery + Redis provide async execution for AI, automation, publishing, and other long-running tasks.
• Logging and CORS/security settings are centralized in settings.

Detailed Behavior

• Apps registered in INSTALLED_APPS include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, publisher. Custom admin config is loaded first.
• Middleware order: security → WhiteNoise → CORS → session/common/CSRF → Django auth → RequestIDMiddleware → AccountContextMiddleware (tenant + plan enforcement) → ResourceTrackingMiddleware (opt-in for admin/developer with header) → messages → clickjacking.
• Routing (urls.py): admin plus CSV helpers for industries/seed keywords, then /api/v1/ routers for auth, account, planner, writer, system, billing (user/admin), automation, linker, optimizer, publisher, integration. OpenAPI served at /api/docs and /api/redoc.
• DRF defaults: unified exception handler (unless env disables), custom pagination, filtering/search/ordering, auth stack (API key → JWT → CSRF-exempt session → basic), scoped throttling per operation class, drf-spectacular schema generation with tag ordering.
• CORS: IGNY8 domains and local dev ports allowed; credentials enabled; request/resource tracking headers exposed.
• Celery: Redis broker/result; JSON serialization; task/soft time limits; single-prefetch; sentinel/SSL toggles via env.
• Logging: console plus rotating files for publish/sync, WordPress API, webhooks; request IDs from middleware surface in responses; automation has dedicated file-based logger per run.

Data Structures / Models Involved (no code)

• Tenancy/identity: Account, Plan, Subscription, Site, Sector, User, SiteUserAccess, PasswordResetToken (in auth models).
• Domain models across planner, writer, billing, automation, publishing, integration, optimization (see domain models doc).
• Middleware uses request-scoped request.account, request.site, and request.request_id.

Execution Flow

1. Request enters middleware stack; IDs and tenant context are set; plan is verified.
2. DRF auth classes authenticate user/api-key/JWT/session.
3. Base viewsets filter by tenant/site/sector and handle unified responses.
4. Serializers validate; database writes enforce tenant alignment via model bases.
5. Optional Celery tasks are enqueued for long-running work; responses remain synchronous JSON with pagination/throttle headers when applicable.
6. Logging writes to configured handlers; request/resource IDs are added to responses.

Cross-Module Interactions

• Tenant context from middleware is consumed by all module viewsets.
• AI and automation invoke Celery tasks and AI functions; billing services deduct credits used by automation/AI flows.
• Integration/publishing modules rely on API key auth to set request.site for WordPress and other platforms.

State Transitions (if applicable)

• Account/plan validity is checked per request; system accounts are protected from deletion.
• Soft-delete is available on many models via SoftDeletableModel.
• Request lifecycle includes request ID creation, optional resource tracking, and unified response formatting.

Error Handling

• Custom DRF exception handler wraps errors with success=false.
• AccountContextMiddleware blocks requests lacking account or active plan (403/402 JSON).
• Base viewsets wrap validation/404/500 errors into unified payloads.

Tenancy Rules

• Request-level account (and site/sector where applicable) is injected by middleware/auth; base viewsets enforce filtering.
• Admin/developer/system-account users bypass tenant filtering; system accounts are guarded from deletion.

Billing Rules (if applicable)

• Billing env keys configured in settings; plan enforcement occurs in middleware; credit debits handled by billing services during operations.

Background Tasks / Schedulers (if applicable)

• Celery worker/beat use Redis URLs from settings; task limits and JSON serialization enforced.
• Automation, AI, publishing, and optimization tasks run async; automation logger writes per-run files.

Key Design Considerations

• Middleware-first tenant enforcement ensures isolation.
• Unified API standards (responses, throttles, schema) keep clients consistent.
• Celery offloads expensive AI/automation/publishing work with bounded execution.
• Logging and request IDs aid observability; resource tracking is opt-in for admins.

How Developers Should Work With This Module

• Register new apps in INSTALLED_APPS and route them under /api/v1/*.
• Use existing middleware order; add new middleware only if it does not break account/request ID handling.
• Inherit from base viewsets for scoping and response consistency.
• Use Celery for long-running tasks; respect Redis/task time-limit settings.
• Keep env vars (DB, JWT, Redis, Stripe/PayPal) set per settings.py; avoid hardcoded secrets.