igny8/master-docs/20-api/ENDPOINTS/sites.md

Site Endpoints

Purpose

Document site management endpoints under the auth module, including creation, listing, sector selection, and activation.

Code Locations (exact paths)

• Routing: backend/igny8_core/auth/urls.py
• Views: backend/igny8_core/auth/views.py (SiteViewSet)
• Serializers: backend/igny8_core/auth/serializers.py (SiteSerializer, SectorSerializer)

High-Level Responsibilities

• CRUD for sites scoped to an account, with role-based access.
• Allow public read by slug for active sites (renderer support).
• Manage sector selection and activation per site.

Detailed Behavior

• Base path: /api/v1/auth/sites/
• Permissions:
  • list with slug filter: AllowAny (public read by slug, active sites only).
  • create: authenticated users (viewer+); sets site account from request/user.
  • Other actions: IsEditorOrAbove with tenant access.
• Queryset logic:
  • Unauthenticated with slug query param: returns active site by slug.
  • Authenticated admin/developer: all sites.
  • Authenticated owner/admin: sites for user’s account.
  • Other users: sites where they have SiteUserAccess.
• Actions:
  • GET /sites/ list (with filters above).
  • POST /sites/ create site; account set from request/user.
  • GET /sites/{id}/sectors/ list active sectors for the site.
  • POST /sites/{id}/set_active/ marks site active (no deactivation of others).
  • POST /sites/{id}/select_sectors/ sets industry and sectors:
    • Requires industry_slug; optional sector_slugs list.
    • Validates industry exists/active; enforces plan sector limit (get_max_sectors_limit).
    • Deactivates sectors not in provided list; ensures sectors belong to industry; creates missing site sectors as needed; returns site + sectors.
• Create/update:
  • perform_create sets account; no single-active constraint.
  • perform_update retains account; no single-active constraint.

Data Structures / Models Involved (no code)

• Site, Sector, Industry, IndustrySector, Plan (for sector limits), SiteUserAccess, Account.

Execution Flow

• Requests → DRF auth (JWT/session) → permissions → queryset scoping → serializer validation → model ops → unified response. Public slug reads bypass account filtering.

Cross-Module Interactions

• Sites link to planner/writer records via site/sector; integration uses Site.wp_api_key; plan sector limits referenced here.

State Transitions

• Site activation via set_active; sector activation/deactivation via select_sectors; industry assignment updated on selection.

Error Handling

• 400 for missing industry slug or exceeding sector limits; 404 for missing site/industry; 500 if site lacks account when selecting sectors.

Tenancy Rules

• Account-scoped except public slug read; role-based overrides for admins/developers; SiteUserAccess governs non-admin access.

Billing Rules

• Sector limit enforced from plan (max_industries via get_max_sectors_limit).

Background Tasks / Schedulers

• None in site endpoints.

Key Design Considerations

• Public slug access supports site renderer without auth.
• Sector selection enforces industry/plan constraints and deactivates unselected sectors.

How Developers Should Work With This Module

• Use select_sectors to set industry/sector with plan-aware limits.
• When extending site data, keep public slug path safe and scoped to active sites; maintain role-based access controls.