docs re-org

docs/90-ARCHIVED/master-docs-original/40-product/SITE-LIFECYCLE.md

@@ -0,0 +1,82 @@
+ # 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.