Version: MarketPulse

Records

Author(s)

Pritam Dutta

Last Updated Date

2026-03-27

SRS References

SRS Document: MarketPulse-SRS-v1.0
Section: Records and Details
Document Link: Records

Version History

Version	Date	Author	Changes
1.0	2026-03-27	Pritam Dutta	Records and details

Feature Overview

The Records feature provides a centralized view of all data fetched from multiple sources within the MarketPulse platform. It enables users to explore, filter, manage, and export records efficiently.

This module ensures that users can access detailed information for each record, including its source and listing URL, while also offering advanced filtering and export capabilities for better data handling and reporting.

Additionally, users can take actions on records such as returning them in case of issues, ensuring data accuracy and workflow integrity.

Key Features

Records Listing: Displays all fetched records in a structured and paginated format
Detailed Record View: Each record includes complete details along with its associated listing URL
Advanced Filtering: Users can filter records based on multiple criteria for precise data retrieval
Filter-Based Exporting: Export data based on applied filters to generate customized datasets
Export Functionality: Initiate data export for full or filtered records
Record Return Option: Users can return a record if any issue or inconsistency is identified
Data Source Integration: Aggregates records from multiple sources into a single view

User Types

Admin: Platform administrators with full system access
Reseller: Organization-level users managing multiple dealers
Dealer: Individual dealer users with location-specific access

Functional Requirements

ID	Requirement	Priority
FR-1	Fetch and display records from multiple data sources	High
FR-2	Display records in a paginated and structured format	High
FR-3	View detailed information for each record	High
FR-4	Show listing URL associated with each record	High
FR-5	Apply filters based on multiple criteria	High
FR-6	Support dynamic filtering with real-time updates	High
FR-7	Export all records	High
FR-8	Export filtered records based on applied filters	High
FR-9	Initiate export jobs with unique export identifiers	High
FR-10	Track export status using export code	Medium
FR-11	Allow users to return a record with a selected reason	High
FR-12	Maintain audit log for record actions (view, export, return)	Medium
FR-13	Handle empty and error states gracefully	Medium
FR-14	Support search functionality within records	Medium
FR-15	Enable sorting of records based on fields (e.g., date, source)	Low

Non-Functional Requirements

ID	Requirement	Priority
NFR-1	System must handle large volumes of records efficiently	High
NFR-2	Record fetching and filtering response time < 1 second	High
NFR-3	Export processing should be asynchronous and non-blocking	High
NFR-4	Ensure data consistency across fetched sources	High
NFR-5	Maintain 99.9% uptime for records service	High
NFR-6	Secure data handling during export and record operations	Medium
NFR-7	Scalable architecture to support increasing data sources	Medium
NFR-8	Proper error handling and logging for debugging and monitoring	Medium

Here need to include the Schema , Models , Enums

API Interfaces

Endpoint	Method	Purpose	Parameters	Request Model	Response Model	Status Codes
`/records`	GET	Fetch all records with pagination and filtering	Query params (filters, pagination)	-	`ServerPaginatedData<Record>`	200, 400, 401, 403, 404, 500
`/records/export`	POST	Initiate exporting with or withput filtering	JWT in header	-	`CommonResponse & ExportResponse`	200, 400, 401, 403, 404, 500

API Examples

1. Get Records API

Endpoint: GET /records

Request Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

Request Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body (Get Records):

{
  "dealerId": "string (optional)",
  "sourceId": "string (optional)",
  "searchKeyword": "string (optional)",
  "rowsPerPage": 10,
  "pageNumber": 1,
  "postedDateFrom": "YYYY-MM-DD (optional)",
  "postedDateTo": "YYYY-MM-DD (optional)",
  "createdAtFrom": "YYYY-MM-DD (optional)",
  "createdAtTo": "YYYY-MM-DD (optional)"
}

Success Response (200):

  "data": {
    "data": [
      {
        "refinedListingId": "uuid",
        "postedDate": "2026-03-20",
        "sourceName": "string",
        "make": "string",
        "model": "string",
        "year": 2022,
        "mileage": 15000,
        "location": "string",
        "price": 25000,
        "dealerName": "string",
        "dealerCode": "string",
        "rawListingId": "uuid",
        "enrichmentJobId": "uuid",
        "listingTitle": "string",
        "sellerType": "Dealer",
        "confidenceScore": 0.85,
        "classificationReasons": [
          "string"
        ],
        "dealerIndicators": [
          "string"
        ],
        "isQualified": true,
        "attributes": {},
        "description": "string",
        "images": [
          "string"
        ],
        "createdAt": "2026-03-21T10:00:00Z",
        "updatedAt": "2026-03-21T12:00:00Z"
      }
    ],
    "totalNumber": 1,
    "hasPreviousPage": true,
    "hasNextPage": true,
    "totalPages": 1,
    "pageNumber": 1,
    "rowsPerPage": 1
  }

Error Response (400 Bad Request):

{
  "status": -20000,
  "message": "Validation failed."
}

2 . Export Records API

Endpoint: POST /api/management/records/export

Request Headers:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Request Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Request Body (Export):

{
  "dealerId": "",
  "sourceId": null,
  "searchKeyword": null,
  "rowsPerPage": 1,
  "pageNumber": 1,
  "postedDateFrom": null,
  "postedDateTo": null,
  "createdAtFrom": null,
  "createdAtTo": null
}

Success Response (200):

{
  "status": 200,
  "message": "string",
  "exportCode": "string",
  "exportId": "string"
}

Error Response (400 Bad Request):

{
  "status": -20000,
  "message": "Validation failed."
}

Workflow

1. User Views and Manages Records

User logs into the Management Portal
User navigates to Records page
System loads and displays all records in a paginated table
User selects a dealer from the dealer dropdown/filter
User searches records using keyword (SearchKeyword)
User applies filters:
- Dealer
- Source
- Posted Date range
- Created Date range
User sorts records:
- By Created Date
- By Posted Date
Frontend prepares filter payload
GET /records is triggered with query parameters
System validates filter parameters
System fetches records from database/services
System returns paginated response
Frontend displays updated records list

2. Export Records (Filtered Data)

User selects a dealer (mandatory for export)
User optionally applies filters (date range, source, keyword)
User clicks on "Export" button
Frontend validates:
- Dealer must be selected
Frontend prepares ExportRequest payload
POST /api/management/records/export is triggered
System validates request:
- DealerId is present
- Filter parameters are valid
System initiates export job asynchronously
System generates unique exportCode
System stores export job details
System returns success response with exportCode
User is notified that export has started

Development Tasks & Estimates

No	Task Name	Estimate (Hours)	Dependencies	Notes
1	Database Schema Setup & Index Optimization	4 hours	None	Ensure records and export tables exist with proper indexing (dealerId, dates, sourceId)
2	Feature Documentation	4 hours	Task 1	Document filter models, response DTOs, and export flow
3	Feature Planning & Technical Design	5 hours	None	Define architecture, filtering logic, export workflow, and validation rules
4	C# Contract Models (ContractLibrary)	3 hours	Task 1	Create Record DTOs, filter models, pagination wrapper, and export models
5	API: Get Records - Paginated List (GET /records)	7 hours	Task 4	Implement filtering, pagination, sorting, search, and unit tests
6	API: Export Records (POST /records/export)	6 hours	Task 5	Implement export job creation, validation, async processing, and exportCode generation
7	API: Export History (GET /records/export-history)	4 hours	Task 6	Fetch export jobs with pagination and status handling
8	Background Job for Export Processing	6 hours	Task 6	Handle large dataset export asynchronously, file generation, and storage
9	Frontend Integration (Filters, Sorting, Export Trigger)	5 hours	Task 5	Integrate APIs, manage UI state, validation for dealer selection
10	Testing (Unit + Integration + Edge Cases)	5 hours	All above	Cover filtering, pagination, export scenarios, and error handling
	Grand Total	49 hours

Testing & Quality Assurance

Integration Test Scenarios:

Fetch records API with valid and invalid filter combinations
Authorization checks (users can only access permitted dealer data)
Pagination edge cases (first page, last page, empty results, single page)
Sorting validation (Created Date, Posted Date ascending/descending)
Filter validation (dealer, source, date ranges, keyword search)
Export API with valid and invalid payloads
Export without dealer selection (should fail)
Export job creation and exportCode generation
Export history retrieval with different statuses
Large dataset handling during fetch and export
Data consistency between filtered results and exported data
Handling null/empty fields in records response

Testing Tools

xUnit - Unit and integration testing framework
FluentAssertions - Readable test assertions
Moq - Mocking framework for unit tests
WebApplicationFactory - Integration testing for APIs
Testcontainers - PostgreSQL container for integration tests
Bogus - Fake data generation for records
Postman/Swagger - Manual API testing
SonarQube - Code quality and coverage analysis

Acceptance Criteria

Feature Complete When:

✅ Records are fetched successfully with pagination
✅ All filters (dealer, source, date range, keyword) work correctly
✅ Sorting works correctly for Created Date and Posted Date
✅ Records display complete and accurate data from sources
✅ Listing URL and record details are correctly shown
✅ Export works only when dealer is selected
✅ Filter-based export generates correct dataset
✅ Export API returns a valid exportCode
✅ Export jobs are processed asynchronously without blocking UI
✅ Export history shows correct status (Pending, Processing, Completed, Failed)
✅ User can download exported file when status is "Completed"
✅ Proper error messages are shown for invalid inputs
✅ Authorization ensures access to permitted records only
✅ APIs respond within acceptable performance limits
✅ Unit test coverage > 85%
✅ All integration tests pass

Deployment Considerations

Configuration Changes

Database Migration:

Ensure records-related tables are created and up to date
Verify indexes on frequently queried fields (dealerId, sourceId, postedDate, createdAt)
Verify foreign key constraints between records, dealers, and sources
Ensure export job table is created for tracking export history
Seed source master data if required for filtering

Risks & Mitigations

Risk	Impact	Likelihood	Mitigation Strategy
Large dataset fetching impacting performance	High	Medium	Implement pagination, indexing, and query optimization
Slow filtering on multiple parameters	Medium	Medium	Add composite indexes; optimize queries; use caching for frequent filters
Exporting large data causing system load	High	Medium	Use asynchronous background jobs; limit export size; implement queue-based processing
Export job failures or incomplete files	Medium	Low	Add retry mechanism; maintain export status tracking; log failures for debugging
Missing dealer selection during export	Low	High	Enforce frontend and backend validation
Inconsistent data between UI and export	Medium	Medium	Use same filtering logic for UI and export APIs
High memory usage during export	Medium	Medium	Stream data instead of loading into memory; generate files in chunks
API latency under heavy load	High	Medium	Implement caching, rate limiting, and horizontal scaling

Review & Approval

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

Reviewer:
(pending)
Approval Date:
(pending)

Notes

Future Enhancements

Advanced filtering options (multi-select, saved filters)
Bulk record actions (bulk return, bulk export)
Real-time record updates and live data refresh
Export scheduling (daily/weekly automated exports)
Download history with expiry and re-download support
Record detail page with enriched insights
Integration with analytics dashboard
Notification system for export completion

Technical Debt to Address

Filter logic duplication between frontend and backend — centralize filtering contract
Response structure (data.data) is redundant — refactor to a cleaner structure
Lack of standardized error responses — implement consistent error handling model
No sorting parameters in API — add sortBy and sortDirection support
Export API shares filter model — consider separate ExportRequest model

Records

Author(s)​

Last Updated Date​

SRS References​

Version History​

Feature Overview​

Key Features​

User Types​

Functional Requirements​

Non-Functional Requirements​

Here need to include the Schema , Models , Enums​

API Interfaces​

API Examples​

1. Get Records API​

2 . Export Records API​

Workflow​

1. User Views and Manages Records​

2. Export Records (Filtered Data)​

Development Tasks & Estimates​

Testing & Quality Assurance​

Integration Test Scenarios:​

Testing Tools​

Acceptance Criteria​

Deployment Considerations​

Configuration Changes​

Risks & Mitigations​

Review & Approval​

Notes​

Future Enhancements​

Technical Debt to Address​

Author(s)

Last Updated Date

SRS References

Version History

Feature Overview

Key Features

User Types

Functional Requirements

Non-Functional Requirements

Here need to include the Schema , Models , Enums

API Interfaces

API Examples

1. Get Records API

2 . Export Records API

Workflow

1. User Views and Manages Records

2. Export Records (Filtered Data)

Development Tasks & Estimates

Testing & Quality Assurance

Integration Test Scenarios:

Testing Tools

Acceptance Criteria

Deployment Considerations

Configuration Changes

Risks & Mitigations

Review & Approval

Notes

Future Enhancements

Technical Debt to Address