turash/bugulma/FRONTEND_UX_REFACTORING_PLAN.md

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

// 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:

export type ResourceFlow = z.infer<typeof ResourceFlowSchema>;
export type Match = z.infer<typeof MatchSchema>;

---

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

// 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)

// 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