igny8/master-docs/40-product/SITE-LIFECYCLE.md

Site Lifecycle

Purpose

Describe how sites are created, configured, activated, integrated, and used across planner/writer/automation flows, including sector selection and WordPress connectivity.

Code Locations (exact paths)

• Models: backend/igny8_core/auth/models.py (Site, Sector, Industry, IndustrySector, SiteUserAccess)
• ViewSet: backend/igny8_core/auth/views.py (SiteViewSet)
• Routing: backend/igny8_core/auth/urls.py (paths under /api/v1/auth/sites/)
• Sector selection logic: SiteViewSet.select_sectors action
• Frontend pages: frontend/src/pages/Sites/{Manage.tsx,Dashboard.tsx,Settings.tsx}
• WordPress integration service: backend/igny8_core/business/integration/services/integration_service.py, modules/integration/views.py

High-Level Responsibilities

• Create and manage sites per account, with optional industry and sector assignments.
• Enforce plan-based sector limits and site activation.
• Provide public read-by-slug for active sites (renderer support).
• Connect to external platforms (WordPress) using API key–based integration.

Detailed Behavior

• Creation (POST /auth/sites/): Authenticated user; account auto-set from request; slug stored; no single-active constraint.
• Listing (GET /auth/sites/):
  • Unauthenticated + slug param: returns active site matching slug (public read).
  • Admin/developer: all sites.
  • Owner/admin: sites for user’s account.
  • Others: sites where SiteUserAccess exists.
• Activation (POST /auth/sites/{id}/set_active/): Marks site active; does not auto-deactivate others.
• Sector selection (POST /auth/sites/{id}/select_sectors/):
  • Requires industry_slug; optional sector_slugs.
  • Validates industry active; enforces get_max_sectors_limit from plan.
  • Deactivates sectors not provided; ensures sectors belong to industry; creates missing site sectors; returns site + sectors.
• Sectors listing (GET /auth/sites/{id}/sectors/): Active sectors for site.
• WordPress integration: Site.wp_api_key used by API key auth; SiteIntegration stores credentials/config; integration endpoints test connection and sync structure/content.
• Frontend:
  • Manage list (Sites/Manage.tsx): cards with hosting/type, WP integration button, CRUD, navigation to settings.
  • Dashboard (Sites/Dashboard.tsx): site overview, stats placeholders, quick actions.
  • Settings (Sites/Settings.tsx): edit core fields, SEO metadata, industry/sector selection, WP integration tab and content-types tab.

Data Structures / Models Involved (no code)

• Site: account FK, name, slug, domain/wordpress fields, industry, hosting_type/site_type, status, is_active, wp_api_key.
• Sector: account/site FK, name, industry_sector FK, status.
• Industry/IndustrySector: reference data for industry/sector taxonomy.
• SiteIntegration: platform, credentials_json, config_json, flags.
• SiteUserAccess: grants non-admin access to specific sites.

Execution Flow

• Create site → optionally set industry/sectors via select_sectors → activate → connect WordPress (integration endpoints) → use site across planner/writer/automation via site/sector filters.
• Renderer/public slug access: unauthenticated GET /auth/sites/?slug=... returns active site for public consumption.

Cross-Module Interactions

• Planner/Writer/Automation viewsets inherit SiteSectorModelViewSet to require site_id/sector_id filters and attach site/sector to records.
• Integration module uses Site.wp_api_key to authenticate WP plugin requests and SiteIntegration for config/credentials.
• Plan limits (max sectors) enforced during select_sectors.

State Transitions (if applicable)

• Site status/is_active set via activation endpoint.
• Sectors activated/deactivated by select_sectors; industry assignment updated.
• Integration connection status managed via integration service responses (not persisted on Site).

Error Handling

• 400 on missing industry slug or exceeding sector limits; 404 for missing site/industry; 500 if account missing on site during sector selection.
• Integration connection errors returned from integration service; frontend shows toasts.

Tenancy Rules

• SiteViewSet filters by account via AccountModelViewSet; public slug read is the only unauthenticated path and limited to active site.
• SiteUserAccess governs non-admin user visibility.

Billing Rules (if applicable)

• Sector limit enforced from plan (get_max_sectors_limit); additional sites/sectors constrained by plan.

Background Tasks / Schedulers (if applicable)

• None for site management; integration sync tasks may run via integration services but are triggered, not scheduled here.

Key Design Considerations

• Public slug read enables site renderer without auth while keeping other operations tenant-scoped.
• Sector selection centralizes industry/plan validation and avoids orphaned sectors.
• WP integration uses API key to avoid sharing user passwords.

How Developers Should Work With This Module

• When adding new hosting/platform types, extend Site model fields plus integration handling.
• Keep all site-scoped resources inheriting site/sector base models and viewsets to maintain isolation.
• If adding analytics/stats, expose a dedicated endpoint and wire to Dashboard page cards.