Version: RK Auto

[Dashboard Management]

Author(s)

Amarnath Garai
Arabinda Bhowmick
...

Last Updated Date

[2026-04-20]

SRS References

2.1.2
2.1.3

Version History

Version	Date	Changes	Author
1.1	2026-04-20	Added GetTopTechnicians and GetTopServices APIs	Arabinda Bhowmick
1.0	2026-04-20	Added Dashboard graph api	Amarnath Garai

Feature Overview

Objective:

Scope:
(Outline the scope of the feature, including any limitations or boundaries.)

Dependencies:
(List any external dependencies, libraries, or other features that this feature depends on.)

Requirements

(List all the functional and non-functional requirements that the feature must meet.)

Requirement 1
Requirement 2
...

Design Specifications

(Provide detailed design specifications, including UI/UX designs, API interfaces, and any other relevant architectural details.)

UI/UX Design:
(Include wireframes, mockups, or links to design files.)

Data Models:
(Detail the data structures, including database schemas or objects.)

public record DateRangeFilter
{
  public DateTime FromDate { get; init; }
  public DateTime ToDate { get; init; }
}

public record GraphData{
  public DateOnly Date { get; init; } // Data for Everyday Within the DateRange
  public int TotalCompletedJobs { get; init; }
  public int TotalCanceledJobs { get; init; }
}

public record TopTechnicianResponse
{
    public Guid TechnicianId { get; init; }
    public string TechnicianCode { get; init; } = string.Empty;
    public string FirstName { get; init; } = string.Empty;
    public string LastName { get; init; } = string.Empty;
    public string Email { get; init; } = string.Empty;
    public string PhoneNumber { get; init; } = string.Empty;
    public string? ProfileImageUrl { get; init; }
    public int CompletedServices { get; init; }
}

public record TopServiceResponse
{
    public Guid ServiceId { get; init; }
    public string ServiceName { get; init; } = string.Empty;
    public string ServiceCode { get; init; } = string.Empty;
    public ServiceCategory? ServiceCategory { get; init; }
    public int UsageCount { get; init; }
}

public class DashboardKpiStatsResponse
{
    public RangeData Current { get; set; } = new();
    public RangeData Previous { get; set; } = new();
    public ComparisonData Comparison { get; set; } = new();
}

public class RangeData
{
    public DateTimeOffset FromDate { get; set; }
    public DateTimeOffset ToDate { get; set; }
    public int Count { get; set; }
}

public class ComparisonData
{
    public int Difference { get; set; }              // current - previous
    public double PercentageChange { get; set; }     // % increase/decrease
    public Trend Trend { get; set; } = Trend.Stable; // increase, decrease, no_change
}

public enum Trend
{
    Increase = 1,
    Decrease,
    Stable
}

API Interfaces:
(Define the APIs required for this feature, including endpoints, methods, request/response formats.)

Endpoint	Method	Parameters	Response	Response Status Codes
`admin/dashboard/jobs-graph`	`GET`	`DateRangeFilter`	`List<GraphData>`	`200`, `204`, `500`
`admin/dashboard/top-technicians`	`GET`	None	`List<TopTechnicianResponse>`	`200`, `400`, `403`, `500`
`admin/dashboard/top-services`	`GET`	None	`List<TopServiceResponse>`	`200`, `400`, `403`, `500`
`/admin/dashboard/customer-onboarding-stats`	`GET`	`fromDate, toDate`	`DashboardKpiStatsResponse`	`200`, `400`, `403`, `500`
`/admin/dashboard/service-request-stats`	`GET`	`fromDate, toDate`	`DashboardKpiStatsResponse`	`200`, `400`, `403`, `500`

Workflow:

GetTopTechnicians Workflow:
1. Admin user initiates a GET request to /admin/dashboard/top-technicians endpoint
2. Controller validates the request and checks admin authorization scope
3. Request is routed to the service layer GetTopTechnicians method
4. Service layer delegates to DAL GetTopTechnicians method for data retrieval
5. DAL queries database for service requests completed in the last 30 days
6. Results are grouped by technician and sorted by completion count (descending)
7. Top 5 technicians are returned with their details (ID, code, name, contact, profile image, completion count)
8. Response is wrapped in ResponseWithData object with status, message, and data
9. HTTP 200 OK returned on success, HTTP 404 if no data, HTTP 403 if unauthorized
GetTopServices Workflow:
1. Admin user initiates a GET request to /admin/dashboard/top-services endpoint
2. Controller validates the request and checks admin authorization scope
3. Request is routed to the service layer GetTopServices method
4. Service layer delegates to DAL GetTopServices method for data retrieval
5. DAL queries database for services requested in the last 30 days
6. Results are grouped by service and sorted by usage count (descending)
7. Top 5 services are returned with their details (ID, name, code, category, usage count)
8. Response is wrapped in ResponseWithData object with status, message, and data
9. HTTP 200 OK returned on success, HTTP 404 if no data, HTTP 403 if unauthorized
GetCustomerOnboardingStats Workflow:
1. Admin user initiates a GET request to /admin/dashboard/customer-onboarding-stats with date range parameters (fromDate, toDate)
2. Controller validates the request and checks admin authorization scope
3. Request is routed to the service layer GetCustomerOnboardingStats method
4. Service layer delegates to DAL GetCustomerOnboardingStats method for data retrieval
5. DAL queries database for customer count in current date range and calculates previous period (same duration)
6. Current period data is retrieved from the specified date range
7. Previous period data is calculated based on the same duration as current period
8. Comparison metrics are calculated: difference (current - previous), percentage change, and trend (increase, decrease, stable)
9. Response includes current stats, previous stats, and comparison data wrapped in ResponseWithData object
10. HTTP 200 OK returned on success, HTTP 400 if invalid date parameters, HTTP 403 if unauthorized
GetServiceRequestStats Workflow:
1. Admin user initiates a GET request to /admin/dashboard/service-request-stats with date range parameters (fromDate, toDate)
2. Controller validates the request and checks admin authorization scope
3. Request is routed to the service layer GetServiceRequestStats method
4. Service layer delegates to DAL GetServiceRequestStats method for data retrieval
5. DAL queries database for completed service requests count in current date range and calculates previous period
6. Current period data retrieves count of completed services from specified date range
7. Previous period data is calculated based on the same duration as current period
8. Comparison metrics are calculated: difference (current - previous), percentage change, and trend (increase, decrease, stable)
9. Response includes current stats, previous stats, and comparison data wrapped in ResponseWithData object
10. HTTP 200 OK returned on success, HTTP 400 if invalid date parameters, HTTP 403 if unauthorized

Sample Responses:

1. Get Top Technicians

Endpoint: GET /admin/dashboard/top-technicians

Response (Success - 200):

{
  "data": [
    {
      "technicianId": "928b170c-d2aa-40d8-97b2-3df59eed0567",
      "technicianCode": "TECH-D53E3071",
      "firstName": "Jane",
      "lastName": "Smith",
      "email": "janesmith@yopmail.com",
      "phoneNumber": "+19172084154",
      "profileImageUrl": "6de0f64e-37b3-408f-827b-23e7299c46ed.jpg",
      "completedServices": 16
    },
    {
      "technicianId": "7486ca47-166e-4c37-9124-b1c7de9eed4a",
      "technicianCode": "TECH-6CC68536",
      "firstName": "Treedip",
      "lastName": "Technician",
      "email": "siddhartopaul14.tp@gmail.com",
      "phoneNumber": "+17059927952",
      "profileImageUrl": "27672116-7684-42bd-aaf0-585e463d585f.jpg",
      "completedServices": 6
    }
  ],
  "status": 0,
  "message": "Top technicians fetched successfully"
}

2. Get Top Services

Endpoint: GET /admin/dashboard/top-services

Response (Success - 200):

{
  "data": [
    {
      "serviceId": "ab7bc3e5-3065-4003-ae07-a6dc86fccd8f",
      "serviceName": "Oil Change",
      "serviceCode": "SRV-001",
      "serviceCategory": 1,
      "usageCount": 45
    },
    {
      "serviceId": "d8991596-6808-4f24-90a2-1af0077999e1",
      "serviceName": "Brake Inspection",
      "serviceCode": "SRV-002",
      "serviceCategory": 3,
      "usageCount": 35
    },
    {
      "serviceId": "0b9c6071-ef83-4b7a-bf70-e53ea09ae38b",
      "serviceName": "Tier Change",
      "serviceCode": "SVC-MNT-ADAC2C",
      "serviceCategory": 1,
      "usageCount": 20
    },
    {
      "serviceId": "c8136644-03b9-4ba7-8eaa-1fa873439029",
      "serviceName": "New Car Wash",
      "serviceCode": "SVC-MNT-F55AC0",
      "serviceCategory": 1,
      "usageCount": 8
    },
    {
      "serviceId": "25a16dd2-0e86-4761-9c91-4c9415a3492b",
      "serviceName": "Full Car Service",
      "serviceCode": "SVC-MNT-AD9FE8",
      "serviceCategory": 3,
      "usageCount": 3
    }
  ],
  "status": 0,
  "message": "Top services fetched successfully"
}

3. Get Customer Onboarding Stats

Endpoint: GET /admin/dashboard/customer-onboarding-stats

Request Parameters:

{
  "fromDate": "2026-03-20T00:00:00Z",
  "toDate": "2026-04-21T00:00:00Z"
}

Response (Success - 200):

{
  "data": {
    "current": {
      "fromDate": "2026-03-20T00:00:00+00:00",
      "toDate": "2026-04-21T00:00:00+00:00",
      "count": 8
    },
    "previous": {
      "fromDate": "2026-02-15T00:00:00+00:00",
      "toDate": "2026-03-19T00:00:00+00:00",
      "count": 24
    },
    "comparison": {
      "difference": -16,
      "percentageChange": -66.67,
      "trend": 2
    }
  },
  "status": 0,
  "message": "Customer onboarding stats fetched successfully"
}

4. Get Service Request Stats

Endpoint: GET /admin/dashboard/service-request-stats

Request Parameters:

{
  "fromDate": "2026-03-20T00:00:00Z",
  "toDate": "2026-04-21T00:00:00Z"
}

Response (Success - 200):

{
  "data": {
    "current": {
      "fromDate": "2026-04-20T00:00:00+00:00",
      "toDate": "2026-04-21T00:00:00+00:00",
      "count": 1
    },
    "previous": {
      "fromDate": "2026-04-18T00:00:00+00:00",
      "toDate": "2026-04-19T00:00:00+00:00",
      "count": 0
    },
    "comparison": {
      "difference": 1,
      "percentageChange": 100,
      "trend": 1
    }
  },
  "status": 0,
  "message": "Completed services stats fetched successfully"
}

Development Tasks & Estimates

(Break down the development process into smaller tasks and provide time estimates for each.)

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Define Workflow	X hours	Dependency 1	Any notes here
2	Task 2 Description	X hours	Dependency 2	Any notes here
3	Task 3 Description	X hours	Dependency 3	Any notes here
4	Total	X hours	Dependency 3	Any notes here

Testing & Quality Assurance

(Outline the testing strategy and quality assurance measures for the feature.)

Unit Tests:
- Verify GetTopTechnicians returns exactly 5 or fewer records
- Verify GetTopServices returns exactly 5 or fewer records
- Verify status code OK when data is available
- Verify status code RECORD_NOT_FOUND when no data in 30-day period
- Verify status code INTERNAL_ERROR on exception handling
- Test null/empty result handling in service layer
- Test exception logging in service and DAL layers
Integration Tests:
- Verify 403 Forbidden response without admin authorization
- Verify 200 OK response with valid admin credentials
- Verify 30-day date range filtering accuracy
- Verify correct data mapping from database to response DTOs
- Test response structure matches TopTechnicianResponse and TopServiceResponse models
- Verify correct ordering (completed services count and usage count descending)
- Verify API response time meets SLA requirements
Acceptance Criteria:
- Both endpoints successfully retrieve top 5 records when data exists
- Both endpoints return HTTP 200 with valid response structure
- Both endpoints return HTTP 404 when no data available in last 30 days
- Authorization validation returns HTTP 403 for non-admin users
- Response time for both endpoints is under 2 seconds
- Data accuracy verified against raw database queries
- All error scenarios handled gracefully with appropriate status codes
- API endpoints are documented in Swagger/OpenAPI specification
Testing Tools:
- xUnit for unit testing framework
- Moq for mocking dependencies
- Postman/Swagger UI for API endpoint testing
- SQL Server Management Studio for data validation
- Application Insights for performance monitoring and logging

Deployment Considerations

(Describe any deployment considerations, including environment configurations, feature toggles, or migration steps.)

Configuration Changes:
(Detail any configuration changes required for this feature.)
Rollout Plan:
(Outline the plan for rolling out the feature, including any phased releases.)

Risks & Mitigations

(Identify potential risks and the strategies to mitigate them.)

Risk	Impact	Likelihood	Mitigation Strategy
Risk 1	High	Medium	Strategy for mitigating Risk 1
Risk 2	Medium	High	Strategy for mitigating Risk 2
...	...	...	...

Review & Approval

(Include a section for review and approval by stakeholders.)

Reviewer:
(Name and role of the person reviewing the document.)
Approval Date:
(Date when the feature is approved for development.)

Notes
(Add any additional notes or considerations related to the feature development here.)

[Dashboard Management]

Author(s)​

Last Updated Date​

SRS References​

Version History​

Feature Overview​

Requirements​

Design Specifications​

Development Tasks & Estimates​

Testing & Quality Assurance​

Deployment Considerations​

Risks & Mitigations​

Review & Approval​

Author(s)

Last Updated Date

SRS References

Version History

Feature Overview

Requirements

Design Specifications

Development Tasks & Estimates

Testing & Quality Assurance

Deployment Considerations

Risks & Mitigations

Review & Approval