Admin & Analytics

Overview

The Admin API provides user management, role permissions, and system analytics for administrators. This includes user CRUD operations, role assignments, and dashboard metrics.

User Management

List Users

Request

GET /api/admin/users
Cookie: sAccessToken=...; sRefreshToken=...

Response

[
  {
    "id": "uuid",
    "email": "john@precisionsiteservices.com",
    "name": "John Doe",
    "role": "ESTIMATOR",
    "status": "ACTIVE",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "lastLogin": "2025-01-29T08:30:00.000Z"
  },
  ...
]

Roles: ADMIN

---

Create User

Request

POST /api/admin/users
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"email": "jane@precisionsiteservices.com",
"name": "Jane Smith",
"role": "ESTIMATOR"
}

Response

{
  "id": "uuid",
  "email": "jane@precisionsiteservices.com",
  "message": "User created successfully. Invitation email sent."
}

Roles: ADMIN

User Roles:

• ADMIN - Full system access
• ESTIMATOR - Create/edit bids
• PM - Read-only bids, manage projects
• OPS - Manage purchase orders
• ACCOUNTING - Financial reconciliation
• FOREMAN - Field operations only

---

Update User Role

Request

PATCH /api/admin/users/:id/role
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"role": "PM"
}

Response

{
  "id": "uuid",
  "role": "PM",
  "message": "User role updated"
}

Roles: ADMIN

---

Update User Status

Request

PATCH /api/admin/users/:id/status
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"status": "INACTIVE"
}

Response

{
  "id": "uuid",
  "status": "INACTIVE",
  "message": "User status updated"
}

Roles: ADMIN

Status Values:

• ACTIVE - User can sign in
• INACTIVE - User cannot sign in (soft delete)

---

Delete User

Request

DELETE /api/admin/users/:id
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "message": "User deleted successfully"
}

Roles: ADMIN

warning

Deleting a user is permanent. Consider setting status to INACTIVE instead.

Analytics

Dashboard Metrics

Request

GET /api/admin/analytics/dashboard
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "bids": {
    "total": 245,
    "draft": 42,
    "submitted": 89,
    "awarded": 67,
    "lost": 35,
    "completed": 12
  },
  "users": {
    "total": 18,
    "active": 16,
    "inactive": 2,
    "byRole": {
      "ADMIN": 2,
      "ESTIMATOR": 8,
      "PM": 5,
      "OPS": 2,
      "ACCOUNTING": 1
    }
  },
  "revenue": {
    "totalBidValue": 12500000.0,
    "awardedValue": 7800000.0,
    "winRate": 0.624
  },
  "activity": {
    "bidsCreatedThisMonth": 15,
    "bidsSubmittedThisMonth": 22,
    "bidsAwardedThisMonth": 8
  }
}

Roles: ADMIN

---

Bid Statistics

Request

GET /api/admin/analytics/bids
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "byStatus": {
    "DRAFT": 42,
    "SUBMITTED": 89,
    "NEGOTIATION": 12,
    "AWARDED": 67,
    "LOST": 35,
    "COMPLETED": 12
  },
  "byMonth": [
    {
      "month": "2025-01",
      "created": 18,
      "submitted": 15,
      "awarded": 7,
      "totalValue": 2100000.00
    },
    ...
  ],
  "topClients": [
    {
      "clientId": "uuid",
      "clientName": "ABC Construction",
      "bidCount": 25,
      "totalValue": 3500000.00,
      "winRate": 0.68
    },
    ...
  ],
  "averageBidValue": 51020.41,
  "medianBidValue": 38500.00
}

Roles: ADMIN

Query Parameters:

• startDate (ISO 8601) - Filter from date
• endDate (ISO 8601) - Filter to date
• clientId (UUID) - Filter by client

---

User Activity

Request

GET /api/admin/analytics/users
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "users": [
    {
      "userId": "uuid",
      "email": "john@precisionsiteservices.com",
      "name": "John Doe",
      "role": "ESTIMATOR",
      "bidsCreated": 42,
      "bidsSubmitted": 38,
      "lastLogin": "2025-01-29T08:30:00.000Z",
      "loginCount": 156
    },
    ...
  ],
  "summary": {
    "totalLogins": 2450,
    "averageLoginsPerUser": 136.1,
    "mostActiveUser": {
      "email": "john@precisionsiteservices.com",
      "loginCount": 245
    }
  }
}

Roles: ADMIN

Module Permissions

Get Module Permissions

Request

GET /api/module-permissions
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "concrete": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  },
  "labor": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  },
  "equipment": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  },
  "materials": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  },
  "subcontractor": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  },
  "misc": {
    "enabled": true,
    "roles": ["ADMIN", "ESTIMATOR"]
  }
}

Roles: ADMIN, ESTIMATOR, PM

---

Update Module Permissions

Request

PUT /api/module-permissions
Cookie: sAccessToken=...; sRefreshToken=...
Content-Type: application/json

{
"concrete": {
"enabled": true,
"roles": ["ADMIN", "ESTIMATOR", "PM"]
}
}

Response

{
  "message": "Module permissions updated"
}

Roles: ADMIN

Role Permissions

Get Role Permissions

Request

GET /api/role-permissions
Cookie: sAccessToken=...; sRefreshToken=...

Response

{
  "ADMIN": {
    "bids": ["create", "read", "update", "delete"],
    "users": ["create", "read", "update", "delete"],
    "pricing": ["create", "read", "update", "delete"],
    "variables": ["create", "read", "update", "delete"]
  },
  "ESTIMATOR": {
    "bids": ["create", "read", "update"],
    "users": ["read"],
    "pricing": ["read"],
    "variables": ["read"]
  },
  "PM": {
    "bids": ["read"],
    "users": ["read"],
    "pricing": ["read"],
    "variables": ["read"]
  }
}

Roles: ADMIN

Data Model

interface User {
  id: string
  email: string
  name: string
  role: UserRole
  status: UserStatus
  createdAt: DateTime
  lastLogin?: DateTime
}

enum UserRole {
  ADMIN
  ESTIMATOR
  PM
  OPS
  ACCOUNTING
  FOREMAN
}

enum UserStatus {
  ACTIVE
  INACTIVE
}

interface DashboardMetrics {
  bids: BidMetrics
  users: UserMetrics
  revenue: RevenueMetrics
  activity: ActivityMetrics
}

Related Endpoints

• Audit Logs - Track user actions
• Authentication - User sign-in and sessions