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