# System Architecture Overview

## Purpose
Describe how IGNY8 is structured across backend, frontend, and integrations, grounded in the current codebase. Covers core services, middleware, and platform composition.

## Code Locations (exact paths)
- Backend project root: `backend/igny8_core/`
- Settings and service wiring: `backend/igny8_core/settings.py`
- URL routing: `backend/igny8_core/urls.py`
- Middleware: `backend/igny8_core/middleware/request_id.py`, `backend/igny8_core/middleware/resource_tracker.py`, `backend/igny8_core/auth/middleware.py`
- Auth models and tenancy bases: `backend/igny8_core/auth/models.py`
- DRF base behaviors: `backend/igny8_core/api/base.py`
- Custom auth classes: `backend/igny8_core/api/authentication.py`
- Frontend SPA: `frontend/` (Vite + React; dependencies in `frontend/package.json`)

## High-Level Responsibilities
- Django/DRF backend providing multi-tenant APIs for planner, writer, system, billing, automation, linker, optimizer, publisher, and integration modules.
- Middleware adds per-request IDs, tenant context, and optional resource tracking for admin diagnostics.
- REST API routing under `/api/v1/*` with unified response/error handling and scoped throttling.
- Celery-backed async work (configured in settings) for AI, automation, and publishing.
- React/Vite frontend consuming the API; authentication via JWT or session; API key support for WordPress bridge.

## Detailed Behavior
- Backend apps registered in `INSTALLED_APPS` include auth, AI framework, planner, writer, system, billing, automation, optimization, publishing, integration, linker, optimizer, and publisher modules; these are loaded via Django app configs in `settings.py`.
- Middleware order enforces security, CORS, session, CSRF, Django auth, then custom layers: request ID, account context, resource tracking, messages, and clickjacking protection.
- URL map (`urls.py`) exposes admin, CSV admin utilities for industries/seed keywords, and module routers for auth, account, planner, writer, system, billing (user + admin), automation, linker, optimizer, publisher, and integration. OpenAPI docs available at `/api/docs` and `/api/redoc`.
- REST framework defaults use custom pagination, filtering, search, ordering, and a custom exception handler (enabled unless `IGNY8_USE_UNIFIED_EXCEPTION_HANDLER` is false). Authentication stack orders API key, JWT, CSRF-exempt session, then basic auth. Throttle scopes are predefined per domain (AI, content, auth, planner, writer, system, billing, linker, optimizer, integration).
- CORS allows the IGNY8 domains plus local development hosts; credentials and specific debug headers are permitted, and request/resource tracking IDs are exposed in response headers.
- Celery is configured to use Redis by default for broker and result backend, with JSON serialization, task time limits, and single-prefetch workers.
- Logging writes to console and rotating files for publish/sync, WordPress API calls, and webhooks, with request IDs available via middleware.

## Data Structures / Models Involved (no code, just explanation)
- Multi-tenancy base classes (`AccountBaseModel`, `SiteSectorBaseModel`) add `account`, `site`, and `sector` scoping plus validation; defined in `auth/models.py`.
- Core tenancy entities: `Account`, `Plan`, `Subscription`, `Site`, `Sector`, `Industry`, `IndustrySector`, `SeedKeyword`, `SiteUserAccess`, `User`, and `PasswordResetToken` in `auth/models.py`.
- These bases are consumed by downstream modules (planner, writer, billing, automation, etc.) to enforce tenant, site, and sector ownership.

## Execution Flow
- Incoming HTTP requests enter Django middleware: security → WhiteNoise → CORS → session → common/CSRF → Django auth → `RequestIDMiddleware` (assigns `X-Request-ID`) → `AccountContextMiddleware` (sets `request.account` via session or JWT) → `ResourceTrackingMiddleware` (when enabled for admins) → messages → clickjacking.
- DRF viewsets inherit from base classes in `api/base.py` to auto-filter querysets by account (and site/sector where applicable) and emit unified responses.
- URL dispatch routes to module-specific routers under `/api/v1/*`. CSV admin helpers are mounted before admin to avoid routing conflicts.
- Background tasks are dispatched via Celery using Redis endpoints from `settings.py`.

## Cross-Module Interactions
- Auth middleware sets `request.account` consumed by `AccountModelViewSet` and `SiteSectorModelViewSet` to filter data.
- API key auth (WordPress bridge) sets both `request.account` and `request.site` for integration endpoints.
- Resource tracking middleware exposes metrics via cache keyed by the request-specific tracking ID added to responses.
- OpenAPI generation (drf-spectacular) documents all modules and respects unified response schemas.

## State Transitions (if applicable)
- Request lifecycle: ID assignment → tenant resolution → optional resource profiling → viewset execution → unified response with optional pagination and request/resource IDs in headers.
- Tenancy lifecycle: Account/Plan/Subscription fields in models track status and retention; soft delete support on models that implement it.

## Error Handling
- Global DRF exception handler (custom when enabled) wraps errors into unified JSON with `success=false`.
- Account middleware denies access when account or plan is missing/inactive, returning structured JSON and logging out session users.
- Viewset overrides in `api/base.py` return unified error payloads for validation and 404/500 cases.

## Tenancy Rules
- Account is injected via middleware (session or JWT). Base viewsets filter querysets by `account`, unless the user is admin/developer/system account (override path).
- `SiteSectorModelViewSet` adds site/sector filtering when models carry those fields; validation ensures site/sector belong to the same account.
- Role helpers (`User.is_admin_or_developer`, `User.is_system_account_user`) allow bypass for privileged users; otherwise, data is restricted to the resolved account (and site/sector for derived models).

## Billing Rules (if applicable)
- Plan and account billing fields live in `auth/models.py` (`Plan.included_credits`, `Account.credits`, Stripe IDs). Status enforcement occurs in `AccountContextMiddleware` by requiring an active plan; billing modules implement credit logic (covered in backend/billing docs).

## Background Tasks / Schedulers (if applicable)
- Celery configuration in `settings.py` sets Redis broker/backend, JSON serialization, time limits, and worker tuning. Task modules (AI, automation, publishing) use this setup; scheduling uses Celery Beat state.

## Key Design Considerations
- Middleware-first tenant resolution ensures consistent scoping before view logic.
- Admin/developer/system-account overrides allow cross-tenant operations for ops while protecting system accounts from deletion.
- Unified API responses and throttling scopes enforce consistent client behavior and rate safety.
- Redis-backed Celery keeps async workloads out of request path with strict time limits.

## How Developers Should Work With This Module
- Add new apps to `INSTALLED_APPS` and mount URLs under `/api/v1/*` in `urls.py`.
- Inherit from `AccountModelViewSet` or `SiteSectorModelViewSet` to automatically enforce tenant/site/sector scoping and unified responses.
- Use existing middleware; do not reorder request ID or account context layers, as downstream views rely on them.
- Configure environment via `settings.py` variables (DB, JWT, Celery, CORS, Stripe/PayPal) rather than hardcoding values.