83 lines
6.2 KiB
Markdown
83 lines
6.2 KiB
Markdown
# 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.
|