igny8/docs/00-SYSTEM/ARCHITECTURE-OVERVIEW.md

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.