docs/UserManual.md

# User Manual

Guide for non-technical stakeholders: accessing portals, using features, understanding roles, languages, and AI capabilities.

## 1. Accessing the Application
Open the production URL: `https://<your-domain-or-default-hostname>/`.
Use the navigation bar to select core areas. The "Portals" link aggregates specialized portals.

## 2. Authentication & Roles
| Role | Typical Email Pattern | Capabilities |
|------|-----------------------|-------------|
| Admin | `admin@...` | Manage all portals, view analytics, training oversight |
| Volunteer | `volunteer@...` | Access volunteer tasks, mobile interface, training modules |
| Resource / Staff | other formats | Resource coordination, request processing |

Demo credentials (if enabled):
- Admin: `admin@miraclesinmotion.org` / `demo123`
- Volunteer: `volunteer@miraclesinmotion.org` / `demo123`

## 3. Portals Overview
| Portal | Path (Hash) | Purpose |
|--------|-------------|---------|
| Portals Hub | `/#/portals` | Directory of all specialized portals |
| Admin Portal | `/#/admin-portal` | System oversight, approvals, metrics |
| Volunteer Portal | `/#/volunteer-portal` | Tasks, assignments, status updates |
| Resource Portal | `/#/resource-portal` | Match and fulfill student resource needs |
| AI Portal | `/#/ai-portal` | AI recommendations, confidence scores |
| Staff Training | `/#/staff-training` | Training modules, progress tracking |
| Analytics Dashboard | `/#/analytics` | KPIs, trends, predictive insights |
| Mobile Volunteer | `/#/mobile-volunteer` | Mobile-friendly volunteer workflow |

All portals are SPA hash routes; bookmarking preserves direct access.

## 4. Multi-Language Support
Languages: EN, ES, FR, DE, ZH, AR (RTL), PT, RU.
- Language selector in UI (location varies by layout).
- Detection: Browser language + persisted preference (localStorage).
- Right-to-left layout auto-applies for Arabic.

## 5. AI Assistance
The AI engine analyzes incoming student assistance requests, scoring potential resource matches by:
1. Text semantic analysis (NLP vectorization)
2. Urgency and logistical complexity
3. Confidence scoring (auto-approve above threshold)
4. Impact prediction (beneficiaries, timeline)

In the AI Portal you can:
- View live recommendations
- See confidence percentage bars
- Approve or modify recommended match
- Monitor performance metrics (accuracy, processing time)

## 6. Real-Time Features
WebSockets (or SignalR) provide:
- Live updates on requests
- AI insight feed
- Volunteer assignment status changes
- Dashboard metric refreshing

If connectivity drops, the system attempts reconnection; offline tasks queue until connection resumes.

## 7. Staff Training System
Components:
- Module list with completion tracking
- Progress indicators & badges
- Mentorship assignments (optional)
Users complete modules sequentially; admins view aggregate performance.

## 8. Mobile Volunteer Experience
Optimized for touchscreen:
- Task list
- Location (GPS) integration (privacy prompts apply)
- Offline caching; tasks sync when online
Add to Home Screen (PWA) on mobile for app-like launch.

## 9. Performance & PWA
Features:
- Offline caching of static assets & key pages
- Installable (prompt may appear or use browser menu)
- Background sync for queued actions
- Push notifications (if permission granted)

Troubleshooting:
- If stale content appears, perform a hard refresh (Ctrl+Shift+R).
- Ensure browser allows notifications for real-time alerts.

## 10. Analytics Dashboard
Sections may include:
- Donations, volunteers, student requests, predictions
- Trend & anomaly indicators
- Export options (CSV/JSON) if enabled
Interpretation:
- Confidence or forecast ranges show expected variability.
- Anomalies flagged for manual review.

## 11. Security & Privacy Basics
- Data access governed by role.
- Sensitive keys stored server-side / Key Vault (not visible in UI).
- Use strong, unique passwords; enable MFA when available.
- Log out on shared devices.

## 12. Common User Actions
| Action | Steps |
|--------|-------|
| Submit a student request | Navigate Resource Portal → Fill request form → Submit |
| Approve AI recommendation | AI Portal → Select request → Approve AI recommendation |
| Complete training module | Staff Training → Select module → Read/watch → Mark complete |
| Switch language | Use language selector (persists automatically) |
| Install as PWA | Browser menu → "Install App" / "Add to Home Screen" |

## 13. Troubleshooting FAQ
| Issue | Fix |
|-------|-----|
| Portal route shows blank | Ensure hash fragment present (`/#/portal-name`) |
| Language didn’t switch | Clear localStorage or reselect; check network for translation file |
| AI metrics not updating | Connection dropped; refresh or check WebSocket permissions |
| Push notifications missing | Verify browser permission & service worker active |
| GPS not working (mobile) | Grant location permission or enter location manually |

## 14. Support & Feedback
For operational issues contact: `contact@mim4u.org`
For technical escalations notify system administrator via Admin Portal.

## 15. Roadmap Awareness
Upcoming (indicative):
- Enhanced voice assistance
- Advanced predictive modeling
- Extended multi-tenant capabilities

---
Last updated: 2025-11-11