docs re-org
This commit is contained in:
IGNY8 VPS (Salman)
@@ -0,0 +1,59 @@
|
||||
# Site Dashboard
|
||||
|
||||
## Purpose
|
||||
Provide a per-site overview showing basic site info, stats (pages/content/integrations/deployments), and quick actions for navigation. Serves as the landing view for a specific site id.
|
||||
|
||||
## Code Locations (exact paths)
|
||||
- Page: `frontend/src/pages/Sites/Dashboard.tsx`
|
||||
- API: `frontend/src/services/api` (`fetchAPI` for `/v1/auth/sites/{id}/`; `fetchSiteStats` placeholder)
|
||||
- UI: `frontend/src/components/common/{PageMeta,PageHeader,ComponentCard}`, `frontend/src/components/dashboard/EnhancedMetricCard`, `frontend/src/components/sites/SiteProgressWidget`, `frontend/src/components/ui/{card,button}`
|
||||
|
||||
## High-Level Responsibilities
|
||||
- Load a single site’s record (name/slug/type/hosting/domain/status) and display a card-based dashboard.
|
||||
- Show metric cards for pages, integrations, deployments, and content counts (placeholder stats until backend endpoint exists).
|
||||
- Provide quick actions to manage pages, sync, publish, or open settings.
|
||||
|
||||
## Detailed Behavior
|
||||
- Routing: expects `:id` param; uses `useParams` and `fetchAPI(/v1/auth/sites/{id}/)` to load site.
|
||||
- Stats: `fetchSiteStats` currently returns placeholder structure (zeros); TODO noted to back with a real endpoint.
|
||||
- If site not found: shows “Site not found” with Back to Sites button.
|
||||
- Metric cards (EnhancedMetricCard) link to pages list, published filter, draft filter, integrations tab, deployments preview, and content list.
|
||||
- Quick actions: buttons for Manage Pages, View Integrations, View Content, Deployments (navigations).
|
||||
- Header shows site name, slug, type, hosting, optional domain, and Settings button linking to `/sites/{id}/settings`.
|
||||
- Loading state: spinner until data fetch completes.
|
||||
|
||||
## Data Structures / Models Involved (no code)
|
||||
- Site DTO: `id`, `name`, `slug`, `site_type`, `hosting_type`, `status`, `is_active`, `domain`.
|
||||
- Stats DTO (placeholder): counts for pages/content/integrations/deployments/views/visitors.
|
||||
|
||||
## Execution Flow
|
||||
- `useEffect` on `siteId` → `loadSiteData` (Promise.all for site + stats) → set `site` + `stats`.
|
||||
- Renders cards and actions with derived links.
|
||||
|
||||
## Cross-Module Interactions
|
||||
- Integrations quick action routes to Site Settings integrations tab.
|
||||
- Content and pages links route to module pages that rely on planner/writer data scoped by site.
|
||||
|
||||
## State Transitions
|
||||
- `loading` gates initial fetch; absent site shows fallback card.
|
||||
|
||||
## Error Handling
|
||||
- Errors during fetch show toast (`Failed to load site data`) and stop loading spinner.
|
||||
|
||||
## Tenancy Rules
|
||||
- Site fetch is account-scoped server-side; client only supplies the site id from the router.
|
||||
|
||||
## Billing Rules (if applicable)
|
||||
- None on this page.
|
||||
|
||||
## Background Tasks / Schedulers (if applicable)
|
||||
- None; no polling.
|
||||
|
||||
## Key Design Considerations
|
||||
- Uses placeholder stats until backend supplies real site analytics; structure prepared for drop-in replacement.
|
||||
- Quick navigation shortcuts reduce hops for site-level operations.
|
||||
|
||||
## How Developers Should Work With This Module
|
||||
- Replace `fetchSiteStats` with a real endpoint and map returned fields into `statCards`.
|
||||
- Add new quick actions by extending the ComponentCard grid with navigation handlers.
|
||||
- Keep links consistent with router paths in `App.tsx` to avoid broken navigation.
|
||||
@@ -0,0 +1,61 @@
|
||||
# Site Flow (Listing & Management)
|
||||
|
||||
## Purpose
|
||||
Provide the tenant-facing list and management surface for all sites, including creation, navigation to settings/integrations, viewing, editing, and deletion. This is the primary entry point before drilling into site dashboard or settings.
|
||||
|
||||
## Code Locations (exact paths)
|
||||
- Page: `frontend/src/pages/Sites/Manage.tsx` (titled “Site Management”)
|
||||
- API: `frontend/src/services/api` (`fetchAPI` for sites collection and integration checks)
|
||||
- UI: `frontend/src/components/ui/{card,button,badge}`, `frontend/src/components/sites/SiteTypeBadge`, `frontend/src/components/ui/badge/Badge`
|
||||
|
||||
## High-Level Responsibilities
|
||||
- List all account sites with status, type, hosting, and integration hints.
|
||||
- Offer actions per site: view, edit, settings, delete, manage WordPress integration.
|
||||
- Provide entry point for creating new sites (routes to builder).
|
||||
|
||||
## Detailed Behavior
|
||||
- On mount: `loadSites()` → GET `/v1/auth/sites/`; if hosting_type is `wordpress`, performs an additional call to `/v1/integration/integrations/?site={id}&platform=wordpress` to flag `has_wordpress_integration`.
|
||||
- Renders grid of cards:
|
||||
- Shows name, slug, active badge, hosting badge, site type, optional WP integration button (“Connect WordPress” / “Manage Integration”).
|
||||
- Footer actions: View (`/sites/{id}`), Edit (`/sites/{id}/edit`), Settings (`/sites/{id}/settings`), Delete (DELETE `/v1/auth/sites/{id}/` after confirm).
|
||||
- Empty state: if no sites, shows CTA to create first site (`/sites/builder`).
|
||||
- Create button in header also routes to `/sites/builder`.
|
||||
|
||||
## Data Structures / Models Involved (no code)
|
||||
- Site list DTO: id, name, slug, site_type, hosting_type, status, is_active, page_count, integration_count.
|
||||
- Integration probe response: `results` length indicates WP connection presence.
|
||||
|
||||
## Execution Flow
|
||||
- `useEffect` → `loadSites` → set `sites`.
|
||||
- Per-site integration check executed inside `Promise.all` when hosting_type is `wordpress`.
|
||||
- Action buttons call navigation or delete; delete triggers reload.
|
||||
|
||||
## Cross-Module Interactions
|
||||
- Integrations tab reachable via settings link; integration existence probed via integration module API.
|
||||
- Builder route (`/sites/builder`) ties into site creation flow (outside this component).
|
||||
|
||||
## State Transitions
|
||||
- `loading` gates initial render; after deletion, reload resets state.
|
||||
- WP integration flag stored per site for button labeling.
|
||||
|
||||
## Error Handling
|
||||
- Load errors show toast (`Failed to load sites`); delete errors show toast.
|
||||
- Integration probe failures fall back to `has_wordpress_integration: false` without blocking list.
|
||||
|
||||
## Tenancy Rules
|
||||
- Backend scopes `/v1/auth/sites/` to current account; page does not switch tenants.
|
||||
|
||||
## Billing Rules (if applicable)
|
||||
- None on this page; plan limits enforced server-side when creating/managing sites.
|
||||
|
||||
## Background Tasks / Schedulers (if applicable)
|
||||
- None; no polling.
|
||||
|
||||
## Key Design Considerations
|
||||
- Integration probe is conditional to reduce extra calls for non-WordPress hosting.
|
||||
- Delete confirmation prevents accidental site removal.
|
||||
|
||||
## How Developers Should Work With This Module
|
||||
- When adding new hosting types or platforms, adjust integration probe logic and `SiteTypeBadge`.
|
||||
- Keep routes aligned with `App.tsx`; ensure permissions enforced server-side for edit/delete.
|
||||
- If adding pagination/filtering, wire through `fetchAPI` params and preserve integration detection per page.
|
||||
@@ -0,0 +1,76 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user