igny8/master-docs/30-frontend/sites/SITE-SETTINGS-PAGE.md

Site Settings Page

Purpose

Advanced site management surface to edit site metadata, SEO fields, industry/sector selection, activation, and WordPress integration. Supports site switching, tabbed sections, and content-type syncing for WP.

Code Locations (exact paths)

• Page: frontend/src/pages/Sites/Settings.tsx
• APIs: frontend/src/services/api (fetchAPI, fetchSites, fetchIndustries, dynamic imports for fetchAccountSetting, fetchSiteSectors), frontend/src/services/integration.api (integrationApi.getWordPressIntegration)
• UI: frontend/src/components/common/{PageMeta,PageHeader}, frontend/src/components/ui/{card,button,badge}, frontend/src/components/form/{Label,SelectDropdown,Checkbox,TextArea}, frontend/src/components/ui/dropdown/{Dropdown,DropdownItem}, frontend/src/components/sites/WordPressIntegrationForm

High-Level Responsibilities

• Load a specific site by id and allow editing of general fields (name, slug, URL, type, hosting, active flag).
• Manage SEO metadata (meta/OG/schema fields) per site.
• Select industry and sectors for the site; load available industries and current sector assignments.
• Manage WordPress integration (fetch existing integration, display form, load content types when tab active).
• Provide site switcher dropdown for quickly navigating between active sites.

Detailed Behavior

• Routing: uses :id param; optional tab query (general, integrations, content-types) controls active tab.
• Initial loads:
  • loadSite → GET /v1/auth/sites/{id}/; seeds formData with site fields plus SEO metadata (from seo_metadata or metadata).
  • loadIntegrations → integrationApi.getWordPressIntegration(siteId); ignores missing integration.
  • loadIndustries → fetches industries (and sectors) for selection.
  • loadSites → fetches active sites for selector; loadUserPreferences → account setting user_preferences (industry/sector defaults).
  • When site + industries loaded → loadSiteSectors to map sector slugs to selections.
• Tabs:
  • General: edits site core fields and SEO fields; save handler persists via fetchAPI PATCH/PUT (not fully shown in snippet but formData bound for submission).
  • Integrations: shows WordPress integration form, uses integrationApi to fetch/update connection; integrationLoading guards state.
  • Content-types: when tab active and WP integration exists, calls loadContentTypes to fetch available structures from WP.
• Industry/Sector selection:
  • Industries from backend; sectors filtered by selected industry; selected sector slugs stored in state.
  • loadSiteSectors pulls current site sectors; tries to infer industry from sectors if not set.
• Site switcher: dropdown using fetchSites results; navigates to new site settings route preserving tab query.

Data Structures / Models Involved (no code)

• Site DTO: id, name, slug, domain/url, site_type, hosting_type, is_active, industry_slug, seo_metadata fields.
• Industry DTO: slug, name, sectors[] (each sector has slug/name).
• WordPress integration DTO (SiteIntegration): platform, credentials/config, status (from integration.api).

Execution Flow

• useEffect on siteId → clear integration/content types → load site, integration, industries.
• useEffect on activeTab & integration → load content types when needed.
• useEffect on site+industries → load site sectors.
• Dropdown selection → navigate to other site settings URL; closes selector.

Cross-Module Interactions

• Integration tab depends on integration service; content-types fetch hits integration endpoints.
• Sector selection aligns with planner/writer scoping by site/sector.

State Transitions

• activeTab from query or state; loading, saving, integrationLoading, sitesLoading gate respective sections.
• Form data is controlled; when site changes, state resets.

Error Handling

• Toast errors for site load failure and integration load; silent handling for user preference load failures.
• Integration fetch failures simply show no integration; no hard failure.

Tenancy Rules

• All requests are account-scoped server-side; page uses site id route but does not allow cross-tenant access.
• Site selector filters to is_active sites from the same account.

Billing Rules (if applicable)

• None directly; industry/sector constraints enforced server-side (plan limits) not in this component.

Background Tasks / Schedulers (if applicable)

• None; no polling.

Key Design Considerations

• Separates tabs to avoid heavy content-type loads unless needed.
• Avoids assuming integration exists; handles absent integration gracefully.
• Keeps SEO fields in formData for a single-save payload.

How Developers Should Work With This Module

• When adding new site fields, extend formData initialization from loadSite and include inputs plus save payload.
• Back the placeholder stats/content-types with real endpoints, ensuring they key off siteId.
• Preserve query-param tab handling when adding new tabs.