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