turash/bugulma/frontend/DASHBOARDS_DOCUMENTATION.md

User Dashboards Documentation

Overview

The application provides different dashboard experiences based on user roles. Each role has access to specific features and views tailored to their responsibilities.

Role-Based Dashboards

1. Regular User (user) - Dashboard Page

Route: /dashboard

Access: All authenticated users with role user

Features:

Key Metrics Section

• Total Organizations: Count of all organizations in the system
• Total Sites: Count of all sites/locations
• Resource Flows: Number of active resource flows
• Matches: Number of successful matches

Impact Metrics

• CO₂ Saved: Total CO₂ emissions saved (in tonnes per year)
• Economic Value: Total economic value created annually
• Active Matches: Currently operational matches

Quick Actions

• Create Resource Flow: Navigate to resource creation page
• Find Matches: Navigate to matching dashboard
• Explore Map: Navigate to map view
• View Analytics: Navigate to analytics dashboard

Recent Activity Feed

• Last 20 system events
• Activity types: organization updates, matches, proposals
• Filterable by type and date

Active Proposals

• List of pending proposals requiring user attention
• Quick access to manage proposals
• Create new proposals

My Organizations Summary

• List of organizations owned/managed by the user
• Quick navigation to organization details
• Organization status indicators

Platform Health Indicators

• Match Success Rate: Percentage of successful matches
• Average Match Time: Average time to complete matches (in days)
• Active Resource Types: Number of different resource types in use

Navigation After Signup: Users are automatically redirected to /dashboard after successful registration.

---

2. City Administrator (admin) - Admin Dashboard

Route: /admin

Access: Users with role admin (city administrators)

Features:

Dashboard Statistics

• Total Organizations: Count with trend indicators
• Verified Organizations: Count and percentage of verified organizations
• Active Connections: Symbiotic links count
• New This Month: Count with comparison to previous month

Economic Connections Graph

• Interactive network visualization
• Sector-to-sector connections
• Filterable by sector and date range
• Export functionality (PNG/SVG)

Supply & Demand Analysis

• Top 10 most requested resources
• Top 10 most offered resources
• Bar chart visualization
• Time period selector

Organization Management

• Full organization table with filters
• Verification queue management
• Bulk operations
• Organization statistics

Additional Admin Features

User Management (/admin/users):

• List all users
• Create/edit user accounts
• Manage user roles and permissions
• View user activity logs
• User statistics

Content Management (/admin/content):

• Static pages management
• Announcements management
• Media library

Localization Management (/admin/localization/ui):

• UI translations editor
• Multi-language support (en, ru, tt)
• Translation status indicators
• Import/export functionality

Analytics (/admin/analytics):

• Organization analytics
• User activity statistics
• Matching statistics
• System health metrics

Settings (/admin/settings):

• System configuration
• Integration settings
• Email configuration
• Maintenance mode

Navigation After Signup: Administrators are automatically redirected to /admin after successful registration.

---

3. Content Manager (content_manager)

Route: /dashboard (same as regular user)

Access: Users with role content_manager

Features:

• Same dashboard as regular users
• Additional access to content management features
• Can create and edit organizations
• Can update content and localizations
• Can publish content
• Limited admin access (no user management or system settings)

Permissions:

• organizations:read, organizations:create, organizations:update
• content:read, content:create, content:update, content:publish
• localization:read, localization:update
• analytics:read

---

4. Viewer (viewer)

Route: /dashboard (same as regular user)

Access: Users with role viewer

Features:

• Read-only access to dashboard
• Can view organizations and content
• Can view analytics
• Cannot create or edit content
• Cannot manage organizations

Permissions:

• organizations:read
• content:read
• analytics:read

---

Dashboard Access Control

Protected Routes

All dashboard routes are protected by the ProtectedRoute component, which:

• Checks if user is authenticated
• Validates user role against required role
• Redirects to login if not authenticated
• Shows access denied if role doesn't match

Role Requirements

• /dashboard: Requires user role (or content_manager, viewer)
• /admin: Requires admin role
• /admin/*: All admin sub-routes require admin role

---

Signup Flow

User Registration

1. User navigates to /signup
2. Fills in registration form:
   • Full Name (required, min 2 characters)
   • Email (required, valid email format)
   • Password (required, min 8 characters)
   • Confirm Password (must match)
   • Account Type (User or City Administrator)
3. On successful registration:
   • JWT token is stored in localStorage
   • User is automatically logged in
   • Redirect based on role:
     • admin → /admin
     • user → /dashboard
     • content_manager → /dashboard
     • viewer → /dashboard

Role Selection During Signup

Users can choose between:

• Regular User: Standard access to dashboard and features
• City Administrator: Full admin access (should be used carefully)

Note: In production, admin role assignment might require additional verification or approval process.

---

Dashboard Components

Shared Components

• MainLayout: Main layout wrapper with navigation
• PageHeader: Page title and subtitle
• Card: Container for dashboard sections
• MetricItem: Display key metrics with icons
• Badge: Status indicators
• Button: Action buttons
• Spinner: Loading states

Admin-Specific Components

• DashboardStats: Admin dashboard statistics
• EconomicGraph: Network visualization
• SupplyChainAnalysis: Supply/demand charts
• OrganizationTable: Organization management table

---

Future Enhancements

Planned Features

1. Role-Specific Widgets: Customizable dashboard widgets based on role
2. Dashboard Customization: Users can arrange dashboard sections
3. Notification Center: Centralized notifications for all roles
4. Activity Timeline: Enhanced activity feed with filtering
5. Quick Stats: Real-time statistics updates
6. Export Functionality: Export dashboard data as reports

Security Considerations

• Admin role should require additional verification
• Consider implementing role approval workflow
• Add audit logging for admin actions
• Implement rate limiting on signup endpoint
• Add email verification for new accounts

---

API Endpoints

Authentication

• POST /api/v1/auth/register: Create new user account

  • Body: { email, password, name, role }
  • Returns: { token, user }

• POST /api/v1/auth/login: Login existing user

  • Body: { email, password }
  • Returns: { token, user }

• GET /api/v1/auth/me: Get current user info

  • Headers: Authorization: Bearer <token>
  • Returns: { id, email, name, role }

Dashboard Data

• GET /api/v1/analytics/dashboard: Dashboard statistics
• GET /api/v1/analytics/platform: Platform statistics
• GET /api/v1/analytics/matching: Matching statistics
• GET /api/v1/analytics/impact: Impact metrics

Admin Endpoints

• GET /api/v1/admin/dashboard/stats: Admin dashboard stats
• GET /api/v1/admin/analytics/organizations: Organization analytics
• GET /api/v1/admin/analytics/users: User activity stats
• GET /api/v1/admin/analytics/matching: Matching analytics

---

Summary

The application provides role-based dashboards that adapt to user permissions:

• Users: Focus on their organizations, proposals, and matches
• Admins: Full system management and analytics
• Content Managers: Content and organization management
• Viewers: Read-only access to information

All dashboards are responsive, accessible, and provide real-time data updates where applicable.