docs re-org

docs/90-ARCHIVED/master-docs-original/30-frontend/sites/SITE-DASHBOARD.md

@@ -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.