# Frontend UX/UI Refactoring Plan ## Comprehensive Plan to Support All Backend Features **Date:** November 24, 2025 **Status:** Strategic Planning Document --- ## Executive Summary The backend has grown into a sophisticated industrial symbiosis platform with: - **9 domain entities** (Organizations, Sites, ResourceFlows, Matches, Products, Services, SharedAssets, Heritage, Users) - **17 API handler groups** with 80+ endpoints - **Advanced features**: Matching engine, Analytics, Geospatial operations, Graph database, Real-time WebSockets, Financial calculations The current frontend has only **11 pages** (mostly landing/static pages) and lacks coverage for 70%+ of backend capabilities. --- ## Current State Analysis ### Current Frontend Pages (11 total) 1. **LandingPage.tsx** - Marketing landing page ✅ Well-designed 2. **MapView.tsx** - Sophisticated Leaflet map with clustering ✅ Production-ready 3. **OrganizationPage.tsx** - Detailed organization view ✅ Good UX 4. **HeritagePage.tsx** - Heritage/cultural content ✅ Complete 5. **HeritageBuildingPage.tsx** - Individual heritage building ✅ Complete 6. **UserDashboard.tsx** - Basic user dashboard ⚠️ Needs enhancement 7. **AdminPage.tsx** - Admin panel ⚠️ Needs enhancement 8. **LoginPage.tsx** - Authentication ✅ Functional 9. **AboutPage.tsx** - Static about page ✅ Complete 10. **ContactPage.tsx** - Static contact page ✅ Complete 11. **PrivacyPage.tsx** - Static privacy page ✅ Complete ### Existing Component Infrastructure ✅ **Strong Foundation Already in Place:** - **30+ memoized components** (React.memo, useMemo, useCallback) - **Reusable UI library** (Button, Card, Badge, Input, Select, etc.) - **Layout primitives** (Container, Grid, Stack, Flex) - **Form components** (react-hook-form + Zod validation) - **Map infrastructure** (Leaflet with clustering, bounds tracking) - **Resource flow components** (ResourceFlowCard, ResourceFlowList) - **Match components** (MatchCard, MatchesList) - **Wizard system** (Multi-step forms with portals) - **Error boundaries** (Global + module-specific) - **Context architecture** (Split into 5 focused map contexts) - **API hooks** (React Query with factories, automatic invalidation) - **Zod schemas** (Backend alignment with validation) - **i18n support** (Russian + English) - **Performance optimizations** (Code splitting, lazy loading, debouncing) ### Current UX/UI Best Practices ✅ Already Implemented **The frontend already follows modern UX best practices:** 1. **Performance-First Architecture** - Code splitting with React.lazy() for all routes - 30+ components with React.memo to prevent re-renders - useMemo/useCallback for expensive operations - Debouncing for search/map interactions (300ms) - WeakMap caching for map icons - Viewport-based loading for map markers 2. **Accessibility (a11y)** - ARIA labels on interactive elements - Keyboard navigation (Esc to close modals) - Focus trapping in modals - Semantic HTML structure - Error boundaries with fallback UI 3. **User Feedback & Communication** - Loading states with skeletons - Error handling with user-friendly messages - Toast notifications (via mutation callbacks) - Optimistic updates for better perceived performance - Empty states with guidance 4. **Form UX Excellence** - Multi-step wizard with progress indication - Real-time validation (Zod schemas) - Contextual error messages (react-hook-form) - Auto-save capabilities (in certain forms) - Clear required field indicators 5. **Responsive Design** - Mobile-first Tailwind CSS approach - Flexible grid layouts (Grid, Stack, Flex primitives) - Touch-friendly controls - Bottom sheets for mobile modals - Responsive map controls 6. **Data Handling Best Practices** - React Query for server state (caching, invalidation) - Placeholder data to prevent UI blocking - Stable query keys (rounded coordinates) - Automatic retry with exponential backoff - Type-safe API layer (Zod validation) 7. **Visual Hierarchy & Clarity** - Consistent design tokens (colors, spacing) - Badge system for status/categories - Icon-text combinations for scannability - Framer Motion animations (subtle, purposeful) - Clear call-to-action buttons 8. **Internationalization (i18n)** - Bilingual support (Russian/English) - Memoized translation functions - Locale-specific formatting - Easy to add new languages ### Backend Capabilities (Not Covered) #### 🔴 Critical Missing Features (Core Business Logic) - **Resource Flow Management** - No UI for creating/managing inputs/outputs - **Matching Engine Interface** - No UI for finding/viewing/managing matches - **Sites Management** - Minimal site CRUD operations - **Products & Services Catalog** - No dedicated product/service management - **Shared Assets** - No UI for shared infrastructure/equipment - **Match Negotiation** - No workflow for match status progression - **Financial Impact Analysis** - No display of NPV, IRR, payback calculations #### 🟡 Important Missing Features - **Analytics Dashboard** - No comprehensive platform analytics - **Geospatial Analysis** - Limited use of geospatial features - **Graph Visualization** - Neo4j relationships not visualized - **Real-time Updates** - WebSocket integration missing - **User Management** - No admin user management interface - **Multi-party Matches** - No support for complex matching scenarios #### 🟢 Nice-to-Have Features - **Supply/Demand Analysis** - No visualization of market gaps - **Environmental Impact Metrics** - No CO2/sustainability tracking - **Risk Assessment Display** - No risk visualization - **Transportation Planning** - No logistics optimization UI --- ## Strategic Recommendation: Focused Enhancement **Given the strong existing infrastructure, we recommend a focused approach:** ### Strategy Adjustment **Original Plan:** Add 14+ new pages (11 → 25+) **Revised Recommendation:** Add 8-10 strategically important pages, enhance 3 existing **Rationale:** - The frontend already has excellent technical foundation - Component library is production-ready and reusable - Adding too many pages risks diluting UX focus - Better to have fewer, polished features than many half-baked ones - Current map experience is sophisticated—build on its strengths ### Revised Complexity Assessment **Pages that will be Easy (use existing components):** - Resource Flow pages (components already exist!) - Match pages (MatchCard, MatchesList ready) - Sites pages (map infrastructure supports it) - Analytics (Grid, Card, MetricItem components ready) **Pages that need new work:** - Products/Services marketplace - Shared assets management - Graph network visualization (needs D3/Cytoscape) - Advanced geospatial analysis ## Proposed Page Structure (Focused: 11 → 19-21 pages) ### 1. Authentication & User Management (3 pages) **Current:** LoginPage **Add:** - **RegisterPage.tsx** - User registration - **UserProfilePage.tsx** - Profile settings, API keys - **UsersAdminPage.tsx** - Admin user management (roles, permissions) ### 2. Dashboard & Analytics (4 pages) **Current:** UserDashboard (basic) **Enhance & Add:** - **DashboardPage.tsx** ⭐ (redesign) - Comprehensive analytics hub - Platform statistics (orgs, sites, flows, matches) - Recent activity feed - Top matches - Economic impact summary - Quick actions - **AnalyticsDashboard.tsx** ⭐ - Deep analytics - Connection statistics - Supply/demand analysis - Resource flow statistics - Geographic heat maps - **ImpactMetrics.tsx** - Environmental & Economic Impact - CO2 savings visualization - Economic value created - Resource recovery rates - **SupplyDemandAnalysis.tsx** - Market gap analysis - Resource type supply/demand charts - Geographic coverage gaps - Pricing trends ### 3. Organization Management (Enhanced - 3 pages) **Current:** OrganizationPage (detail view) **Add:** - **OrganizationsListPage.tsx** - Searchable organization directory - Filters by sector, certification, size - Map/list toggle view - Bulk operations - **OrganizationEditPage.tsx** - Create/edit organizations - Multi-step wizard - Address management - Product/service association - Trust network configuration - **OrganizationAnalytics.tsx** - Per-organization analytics - Resource flow statistics - Match history - Economic performance - Network visualization ### 4. Sites Management (3 pages) ⭐ **HIGH PRIORITY** **Current:** Minimal (embedded in map) **Add:** - **SitesListPage.tsx** - Site directory - Filterable table (type, ownership, utilities) - Map view toggle - Heritage sites filter - **SiteDetailPage.tsx** - Individual site view - Location & facilities - Operating organizations - Resource flows at site - Shared assets inventory - Infrastructure details - **SiteEditPage.tsx** - Create/edit sites - Location picker (map integration) - Utilities & infrastructure - PostGIS spatial data - Photo/document upload ### 5. Resource Flow Management (4 pages) ⭐ **CRITICAL PRIORITY** **Current:** None! **Add:** - **ResourceFlowsPage.tsx** ⚡ Fast (reuse ResourceFlowList component) - List view with existing ResourceFlowCard - Filters: type, direction, organization (existing UI patterns) - "Find Matches" button per flow (already in ResourceFlowCard!) - Export to CSV (simple utility function) - **ResourceFlowWizard.tsx** ⚡ Medium (adapt existing Wizard component) - Reuse existing Wizard modal with portal rendering - Step 1: Type + Direction (simple selects) - Step 2: Quantity (Zod schema for Quantity already exists) - Step 3: Quality params (dynamic based on type) - Step 4: Economic data (optional fields) - Use existing form components (Input, Select, Button) - **ResourceFlowDetail.tsx** ⚡ Fast (compose existing components) - Reuse ResourceFlowCard for header - KeyMetrics-style layout for parameters - MatchesList component for related matches - Tabs component for organizing sections ### 6. Matching Engine (5 pages) ⭐ **CRITICAL PRIORITY** **Current:** None! **Add:** - **MatchingDashboard.tsx** - Matching hub - Quick match search - Top suggested matches - Match pipeline (suggested → live) - Filter by status, score, type - **MatchExplorer.tsx** - Advanced match finding - Search by resource type, location, quality - Distance/score sliders - Real-time results with caching indicator - Map view of potential matches - **MatchDetailPage.tsx** - Individual match view - Compatibility breakdown (quality, temporal, economic) - Distance & transportation estimate - Risk assessment visualization - Economic impact (NPV, IRR, payback) - Contract details (if formalized) - Negotiation history timeline - **MatchNegotiationPage.tsx** - Negotiation workflow - Status progression UI - Document upload - Communication history - Counter-offer management - Approval workflow - **MatchesMapView.tsx** - Geographic match visualization - Source/target flow connections on map - Filter by status, type - Cluster visualization for high-density areas ### 7. Products & Services (3 pages) **Current:** None (embedded in org data) **Add:** - **ProductsCatalog.tsx** - Searchable product directory - Filter by category, price, MOQ - Organization links - Certification badges - Comparison tool - **ServicesCatalog.tsx** - Service directory - Filter by type, domain, service area - Hourly rate comparison - On-site/remote indicators - Booking/inquiry system - **ServiceNeedsBoard.tsx** - Marketplace for service needs - Posted service requests - Match with service providers - RFQ (Request for Quote) system ### 8. Shared Assets (2 pages) **Current:** None **Add:** - **SharedAssetsPage.tsx** - Infrastructure sharing platform - Available assets (utilization < 100%) - Filter by type, location, capacity - Utilization charts - Cost sharing models - **SharedAssetDetail.tsx** - Asset management - Capacity & current users - Maintenance schedule - Cost allocation - Booking calendar - Operational status ### 9. Heritage & Cultural (Current - 2 pages) **Keep:** - **HeritagePage.tsx** - Heritage overview - **HeritageBuildingPage.tsx** - Individual heritage site ### 10. Geospatial & Mapping (Enhanced - 2 pages) **Current:** MapView **Enhance & Add:** - **MapView.tsx** (enhance existing) - Layer controls (orgs, sites, flows, matches) - Heat maps (resource density, match potential) - Clustering for performance - Drawing tools for area selection - **SpatialAnalysisPage.tsx** - Advanced geospatial tools - Proximity analysis - Cluster detection - Coverage gap analysis - Route optimization for logistics ### 11. Graph Network (2 pages) ⭐ **HIGH VALUE** **Current:** None **Add:** - **NetworkGraphPage.tsx** - Interactive network visualization - Organization relationship graph (Neo4j) - Resource flow connections - Trust network visualization - Shortest path finding - Community detection - **NetworkAnalytics.tsx** - Network metrics - Centrality measures - Network density - Clustering coefficients - Influence scores ### 12. Admin & Management (Enhanced - 3 pages) **Current:** AdminPage **Enhance & Add:** - **AdminPage.tsx** (enhance) - System health monitoring - Database statistics - Graph DB sync status - Cache management - Event bus status - **DataManagementPage.tsx** - Data operations - Bulk import/export - Data validation - Migration tools - Backup/restore - **SystemConfigPage.tsx** - Configuration - API settings - Integration toggles (Neo4j, Redis) - Feature flags - Rate limiting ### 13. Static Pages (Keep - 3 pages) - **AboutPage.tsx** - **ContactPage.tsx** - **PrivacyPage.tsx** --- ## Proposed Information Architecture ``` / ├── / (Landing) ├── /login ├── /register │ ├── /dashboard (Main hub after login) │ ├── /dashboard/analytics │ ├── /dashboard/impact │ └── /dashboard/supply-demand │ ├── /organizations │ ├── /organizations (list) │ ├── /organizations/new │ ├── /organizations/:id │ ├── /organizations/:id/edit │ └── /organizations/:id/analytics │ ├── /sites │ ├── /sites (list) │ ├── /sites/new │ ├── /sites/:id │ └── /sites/:id/edit │ ├── /resources (Resource Flows) │ ├── /resources (list) │ ├── /resources/new (wizard) │ ├── /resources/:id │ ├── /resources/:id/edit │ └── /resources/templates │ ├── /matching │ ├── /matching (dashboard) │ ├── /matching/explore │ ├── /matching/:id │ ├── /matching/:id/negotiate │ └── /matching/map │ ├── /marketplace │ ├── /marketplace/products │ ├── /marketplace/services │ └── /marketplace/service-needs │ ├── /shared-assets │ ├── /shared-assets (list) │ └── /shared-assets/:id │ ├── /heritage │ ├── /heritage │ └── /heritage/:id │ ├── /map (Enhanced map view) │ └── /map/spatial-analysis │ ├── /network │ ├── /network/graph │ └── /network/analytics │ ├── /admin │ ├── /admin (dashboard) │ ├── /admin/users │ ├── /admin/data │ └── /admin/config │ ├── /profile ├── /about ├── /contact └── /privacy ``` --- ## Implementation Priority Matrix ### Phase 1: Critical Foundation (Weeks 1-4) **Goal:** Enable core resource matching workflow 1. **Resource Flow Management** (4 pages) - Week 1-2 - ResourceFlowsPage.tsx - ResourceFlowDetail.tsx - ResourceFlowWizard.tsx - ResourceFlowTemplates.tsx 2. **Basic Matching Interface** (3 pages) - Week 2-3 - MatchingDashboard.tsx - MatchExplorer.tsx - MatchDetailPage.tsx 3. **Sites Management** (3 pages) - Week 3-4 - SitesListPage.tsx - SiteDetailPage.tsx - SiteEditPage.tsx **Deliverable:** Users can create resource flows, discover matches, and manage sites --- ### Phase 2: Enhancement & Workflow (Weeks 5-8) **Goal:** Complete matching workflow and analytics 4. **Match Negotiation** (2 pages) - Week 5 - MatchNegotiationPage.tsx - MatchesMapView.tsx 5. **Dashboard & Analytics** (4 pages) - Week 6-7 - DashboardPage.tsx (redesign) - AnalyticsDashboard.tsx - ImpactMetrics.tsx - SupplyDemandAnalysis.tsx 6. **Organization Enhancement** (2 pages) - Week 7-8 - OrganizationsListPage.tsx - OrganizationEditPage.tsx **Deliverable:** Complete matching workflow with analytics --- ### Phase 3: Marketplace & Sharing (Weeks 9-11) **Goal:** Enable product/service marketplace 7. **Products & Services** (3 pages) - Week 9-10 - ProductsCatalog.tsx - ServicesCatalog.tsx - ServiceNeedsBoard.tsx 8. **Shared Assets** (2 pages) - Week 10-11 - SharedAssetsPage.tsx - SharedAssetDetail.tsx **Deliverable:** Functional marketplace for products, services, and shared assets --- ### Phase 4: Advanced Features (Weeks 12-15) **Goal:** Leverage advanced backend capabilities 9. **Graph Network** (2 pages) - Week 12-13 - NetworkGraphPage.tsx - NetworkAnalytics.tsx 10. **Geospatial Enhancement** (1 page) - Week 13-14 - SpatialAnalysisPage.tsx 11. **Admin & Management** (3 pages) - Week 14-15 - DataManagementPage.tsx - SystemConfigPage.tsx - UsersAdminPage.tsx **Deliverable:** Full platform capabilities exposed --- ### Phase 5: Polish & Optimization (Weeks 16-18) **Goal:** Performance, UX, and real-time features 12. **Real-time Features** - Week 16 - WebSocket integration across pages - Live match notifications - Real-time analytics updates 13. **Performance Optimization** - Week 17 - Query optimization - Caching strategies - Lazy loading - Code splitting 14. **UX Polish** - Week 18 - Consistent design system - Accessibility improvements - Mobile responsiveness - User testing & refinement **Deliverable:** Production-ready platform --- ## Key UI/UX Patterns to Implement ### 1. Resource Flow Wizard Multi-step form with dynamic fields based on resource type: ``` [Type Selection] → [Quality Params] → [Quantity] → [Economic] → [Constraints] → [Review] ``` ### 2. Match Detail Layout ``` ┌─────────────────────────────────────────────┐ │ Match Score: 85% ⭐⭐⭐⭐ │ ├─────────────────────────────────────────────┤ │ Source Flow → Target Flow │ │ Heat Output Heat Input │ │ 65°C, 500 kWh/h 60-70°C req │ ├─────────────────────────────────────────────┤ │ Compatibility Breakdown │ │ ├─ Quality: 92% │ │ ├─ Temporal: 88% │ │ ├─ Economic: 75% │ │ └─ Geographic: 3.2 km │ ├─────────────────────────────────────────────┤ │ Economic Impact │ │ ├─ Annual Savings: €45,000 │ │ ├─ NPV (10y): €320,000 │ │ ├─ Payback: 2.1 years │ │ └─ CO2 Avoided: 120 tonnes/year │ ├─────────────────────────────────────────────┤ │ [Propose Match] [Download Report] │ └─────────────────────────────────────────────┘ ``` ### 3. Analytics Dashboard Grid ``` ┌──────────────┬──────────────┬──────────────┐ │ Total Orgs │ Active Sites │ Live Matches │ │ 142 │ 89 │ 23 │ ├──────────────┴──────────────┴──────────────┤ │ Resource Flow Statistics │ │ [Chart: Supply vs Demand by Type] │ ├────────────────────────────────────────────┤ │ Geographic Distribution [Map] │ ├──────────────┬────────────────────────────┤ │ Recent │ Top Matches │ │ Activity │ [Table] │ │ [Feed] │ │ └──────────────┴────────────────────────────┘ ``` ### 4. Geospatial Filters ``` Layer Controls: ☑ Organizations ☑ Sites ☑ Resource Flows (outputs only) ☐ Matches ☑ Heritage Buildings Filters: Resource Type: [Heat ▼] Max Distance: [─●────] 25 km Min Score: [──●──] 0.6 ``` --- ## Component Library Enhancements ### New Components Needed #### Data Display - **ResourceFlowCard** - Compact flow representation - **MatchScoreGauge** - Visual score indicator - **CompatibilityBreakdown** - Radar/bar chart - **EconomicImpactSummary** - NPV/IRR/Payback display - **GeographicDistanceIndicator** - Distance with map preview - **QualityParametersTable** - Dynamic quality display - **QuantityChart** - Temporal profile visualization - **RiskAssessmentMatrix** - Risk visualization - **NetworkGraph** - D3.js/Cytoscape integration - **TimelineComponent** - Negotiation history #### Input Components - **ResourceTypeSelector** - Type picker with icons - **QualityParamsForm** - Dynamic based on resource type - **QuantityInput** - Amount + unit + temporal selector - **LocationPicker** - Map-based location selection - **CertificationBadges** - Certification selector - **TemporalProfileEditor** - Weekly availability grid - **ConstraintsBuilder** - Complex constraint form #### Navigation - **TabNavigation** - For multi-section pages - **StepWizard** - Multi-step form component - **BreadcrumbNav** - Hierarchical navigation - **FilterPanel** - Collapsible filter sidebar --- ## Data Fetching Strategy ### API Services to Create/Enhance 1. **resources-api.ts** (NEW) - CRUD operations for resource flows - Filtering & pagination - Template management 2. **matching-api.ts** (ENHANCE) - Match finding with caching - Match CRUD - Status updates - Negotiation history 3. **sites-api.ts** (NEW) - Site CRUD - Geospatial queries - Heritage filtering 4. **analytics-api.ts** (NEW) - Platform statistics - Organization analytics - Impact metrics - Supply/demand analysis 5. **shared-assets-api.ts** (NEW) - Asset CRUD - Availability queries 6. **graph-api.ts** (NEW) - Network queries - Relationship traversal - Graph statistics 7. **geospatial-api.ts** (NEW) - Proximity searches - Cluster detection - Spatial statistics ### React Query Hooks Pattern ```typescript // Example: Resource Flows export const useResourceFlows = (filters?: ResourceFlowFilters) => useQuery(['resourceFlows', filters], () => resourceFlowsApi.getAll(filters) ); export const useCreateResourceFlow = () => useMutation( resourceFlowsApi.create, { onSuccess: () => { queryClient.invalidateQueries(['resourceFlows']); } } ); ``` --- ## Backend Schema Integration ### Zod Schemas to Create Based on backend domain models: 1. **ResourceFlowSchema** - Complete flow validation 2. **MatchSchema** - Match entity with nested data 3. **ProductSchema** - Product catalog item 4. **ServiceSchema** - Service offering 5. **SharedAssetSchema** - Shared infrastructure 6. **NegotiationHistorySchema** - Negotiation entry 7. **EconomicImpactSchema** - Financial calculations 8. **RiskAssessmentSchema** - Risk parameters 9. **TransportationEstimateSchema** - Logistics data ### Type Generation Use Zod's `.infer` to generate TypeScript types: ```typescript export type ResourceFlow = z.infer; export type Match = z.infer; ``` --- ## Real-time Features via WebSockets ### Events to Subscribe To - **match.created** - New match found - **match.status_updated** - Match status changed - **resource_flow.created** - New flow added - **organization.updated** - Organization data changed - **negotiation.new_message** - Negotiation activity ### UI Updates - Dashboard: Live activity feed - Matching: Real-time match notifications - Negotiation: Live chat/updates - Analytics: Live metric updates --- ## Mobile Responsiveness Strategy ### Breakpoints - **Mobile:** < 768px (single column, simplified views) - **Tablet:** 768px - 1024px (2-column grids) - **Desktop:** > 1024px (full layouts) ### Mobile-First Components - Bottom sheet modals (instead of sidebars) - Swipeable cards - Collapsible filters - Simplified tables (card view on mobile) - Touch-friendly map controls --- ## Performance Optimization ### Code Splitting ```typescript // Lazy load heavy pages const MatchingDashboard = lazy(() => import('./pages/MatchingDashboard')); const NetworkGraphPage = lazy(() => import('./pages/NetworkGraphPage')); ``` ### Data Caching - React Query cache (5-15 min TTL) - Backend cache service (match results) - Optimistic updates for mutations ### Virtualization - Large lists (react-window) - Map markers (clustering) - Table rows (react-virtual) --- ## Design System Tokens ### Color Palette (Expand) ```typescript // Resource Types resourceTypes: { heat: '#FF6B6B', water: '#4ECDC4', steam: '#95E1D3', materials: '#F9A825', waste: '#78909C', electricity: '#FFC107', // ... } // Match Scores matchScores: { excellent: '#4CAF50', // 80-100% good: '#8BC34A', // 60-79% fair: '#FFC107', // 40-59% poor: '#FF9800', // 20-39% veryPoor: '#F44336', // 0-19% } ``` --- ## Testing Strategy ### Unit Tests - Component rendering - Hook logic - Utility functions - Schema validation ### Integration Tests - API service functions - Form submissions - Navigation flows - WebSocket connections ### E2E Tests (Playwright) - Critical user journeys: 1. Create resource flow → Find matches → Negotiate 2. Register organization → Add site → Add flows 3. Admin: User management workflow --- ## Documentation Requirements ### Developer Docs 1. **Component Storybook** - All new components 2. **API Integration Guide** - Service usage examples 3. **State Management** - React Query patterns 4. **Routing Structure** - Page hierarchy ### User Docs 1. **User Guide** - Feature walkthroughs 2. **Video Tutorials** - Key workflows 3. **API Documentation** - For power users --- ## Migration Path from Current State ### Step 1: Parallel Development - Keep existing 11 pages functional - Develop new pages in `/pages/v2/` directory - Test thoroughly before cutover ### Step 2: Gradual Rollout - Feature flags for new pages - Beta users test new interface - Collect feedback and iterate ### Step 3: Cutover - Replace old pages with new - Redirect old routes - Monitor analytics for issues ### Step 4: Cleanup - Remove deprecated components - Update documentation - Archive old code --- ## Success Metrics ### User Engagement - [ ] Time to create first resource flow < 3 min - [ ] Time to find first match < 30 sec - [ ] Match conversion rate > 15% - [ ] Daily active users +50% ### Platform Health - [ ] Page load time < 2s - [ ] API response time < 500ms - [ ] Match accuracy > 80% - [ ] User satisfaction score > 4.2/5 ### Business Impact - [ ] Active matches +200% - [ ] CO2 savings tracked: 10,000+ tonnes/year - [ ] Economic value created: €1M+ annually --- ## Next Steps 1. **Review & Approval** - Stakeholder sign-off on plan 2. **Design Mockups** - Create wireframes for key pages 3. **Sprint Planning** - Break into 2-week sprints 4. **Team Allocation** - Assign developers to phases 5. **Kick-off** - Begin Phase 1 development --- ## Appendix: Backend API Coverage ### Currently Used by Frontend ✅ Organizations: GET /api/organizations, GET /api/organizations/:id ✅ Sites: GET /api/sites (minimal) ✅ Heritage: GET /api/heritage ✅ Auth: POST /auth/login ✅ Stats: GET /api/stats ### Not Used (70%+ of backend) ❌ Resource Flows (all endpoints) ❌ Matching Engine (all endpoints) ❌ Analytics (all 8 endpoints) ❌ Geospatial (all endpoints) ❌ Shared Assets (all endpoints) ❌ Graph API (all endpoints) ❌ Products/Services (embedded in orgs, no dedicated UI) ❌ WebSockets **This plan addresses this 70% gap.** --- ## Conclusion This refactoring plan provides a roadmap to transform the frontend from a basic landing page + map into a comprehensive industrial symbiosis platform that fully leverages the sophisticated backend capabilities. The phased approach ensures steady progress while maintaining existing functionality. **Estimated Timeline:** 18 weeks (4.5 months) **Required Resources:** 2-3 frontend developers, 1 UI/UX designer **Expected Outcome:** Production-ready platform with 25+ pages supporting all backend features