docs/agent/thoughts/user-overview.md

User Overview Dashboard API

Overview

Cross-project aggregated statistics for user's landing page / home dashboard.

---

Endpoint

Get User Overview

GET /api/v1/analytics/user/overview

Purpose: Landing page dashboard showing aggregated stats across all projects user has access to.

Response:

{
  "user_info": {
    "id": "uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "project_manager"
  },
  "projects": {
    "total": 5,
    "active": 3
  },
  "team": {
    "total_members": 25
  },
  "tickets": {
    "total": 150,
    "open": 20,
    "in_progress": 15
  },
  "notifications": {
    "unread": 8
  },
  "expenses": {
    "total_amount": 125000.00,
    "pending_approval": 5
  },
  "sales_orders": {
    "total": 45,
    "pending": 8
  },
  "inventory": {
    "total_value": 500000.00,
    "active_assignments": 12
  },
  "generated_at": "2025-11-26T10:00:00Z"
}

Permissions: Any authenticated user

---

Role-Based Data

Different roles see different stats:

Platform Admin

• All stats across all projects

Client Admin / Contractor Admin

• Stats for their organization's projects
• Team members count
• Expenses, inventory, sales orders

Project Manager

• Stats for projects they manage
• Team members count
• Expenses, inventory

Field Agent / Dispatcher

• Stats for projects they're team members of
• Limited to tickets and notifications
• No expenses or inventory stats

Sales Agent / Sales Manager

• Stats for projects they're on
• Sales orders included
• Limited financial data

---

Use Cases

1. Landing Page - Show user their overall activity across all projects
2. Quick Overview - At-a-glance metrics without drilling into specific projects
3. Notification Badge - Unread count for notification bell
4. Action Items - Pending approvals, open tickets, etc.

---

Project Dashboard vs User Overview

Feature	User Overview	Project Dashboard
Scope	All projects	Single project
Endpoint	/analytics/user/overview	/projects/{id}/dashboard
Caching	No cache	5-min cache
Use Case	Landing page	Project detail page
Stats Depth	Summary only	Detailed breakdown

---

Notes

• No caching on user overview (always fresh data)
• Stats adapt based on user role
• Empty arrays/zeros for stats user doesn't have access to
• Use this for home dashboard, use project dashboard for project-specific views