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.