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