Version: RK Auto

Add-vehicle And validate VIN

Author(s)

Amarnath Garai
Sanket Mal

Last Updated Date

[2025-12-30]

SRS References

2.1.2
2.1.3

Version History

Version	Date	Changes	Author
1.0	2025-12-30	Initial draft	Amarnath Garai , Sanket Mal
...	...	...	...

Feature Overview

Objective: The Main Objective is To Store The Vehicle Details of a Customer With Full Validation That The Vehicle has been purchesed from Our Organization

Scope:

Dependencies:

Requirements

Functional Requirements:

Customer should be able to add any valid vehicle to their vehicle list.
Customer should be able to remove any vehicle from their vehicle list.

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:

  public record CustomerVehicle
  {
      // Primary Key
      public Guid Id { get; init; }

      // Ownership
      public Guid CustomerId { get; init; }
      public required string Vin { get; init; }

      // Basic Identity
      public string? Make { get; init; }
      public string? Model { get; init; }
      public int? Year { get; init; }
      public string? Trim { get; init; }

      // Body
      public string? VehicleType { get; init; }   // Passenger Car
      public string? BodyType { get; init; }     // Coupe, Sedan
      public int? Doors { get; init; }

      // Powertrain
      public string? FuelType { get; init; }      // Gasoline
      public string? Transmission { get; init; }  // Automatic
      public int? TransmissionSpeeds { get; init; }
      public string? DriveType { get; init; }

      // Engine
      public string? EngineModel { get; init; }   // J30A4
      public int? EngineCylinders { get; init; }
      public decimal? EngineDisplacementL { get; init; }

      // Manufacturer / Plant
      public string? Manufacturer { get; init; }
      public string? PlantCountry { get; init; }
      public string? PlantState { get; init; }
      public string? PlantCity { get; init; }

      // Audit
      public DateTime CreatedAt { get; init; }
      public DateTime UpdatedAt { get; init; }
  }

    public class ServerPaginatedData<T>
    {
        public List<T> Data { get; set; } = [];
        public int TotalNumber { get; set; }
        public bool HasPreviousPage { get; set; }
        public bool HasNextPage { get; set; }
        public int TotalPages { get; set; }
        public int PageNumber { get; set; }
        public int RowsPerPage { get; set; }
    }

  CREATE TABLE customervehicles (
    -- Primary Key
    customervehicleid UUID PRIMARY KEY,

    -- Ownership
    customerid UUID NOT NULL,
    vin VARCHAR(17) NOT NULL,

    -- Basic Identity
    make VARCHAR(100),
    model VARCHAR(100),
    year INT,
    trim VARCHAR(100),

    -- Body
    vehicletype VARCHAR(50),   -- Passenger Car
    bodytype VARCHAR(50),      -- Sedan, Coupe
    doors INT,

    -- Powertrain
    fueltype VARCHAR(50),      -- Gasoline
    transmission VARCHAR(50),   -- Automatic
    transmissionspeeds INT,
    drivetype VARCHAR(50),

    -- Engine
    enginemodel VARCHAR(100),  -- J30A4
    enginecylinders INT,
    enginedisplacement_l NUMERIC(4,2),

    -- Manufacturer / Plant
    manufacturer VARCHAR(100),
    plantCountry VARCHAR(100),
    plantState VARCHAR(100),
    plantCity VARCHAR(100),


    -- Audit
    createdat TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updatedat TIMESTAMPTZ NOT NULL DEFAULT NOW(),

    -- Constraints
    CONSTRAINT uq_customer_vin UNIQUE (customerId, vin),
    CONSTRAINT chk_vin_length CHECK (char_length(vin) = 17)
);

ALTER TABLE customervehicles
ADD CONSTRAINT fk_customer_vehicles_customer
FOREIGN KEY (customerid)
REFERENCES customermaster(customerid)
ON DELETE CASCADE
ON UPDATE CASCADE;

API Interfaces:

Add Customer Vehicle Endpoint

Endpoint	Method	Auth Required	Description	Request Model	Response Model
`/vehicle`	`POST`	Yes (Customer)	Add new vehicle to customer	`AddCustomerVehicleRequest`	`AddCustomerVehicleResponse`
`/vehicle/{customerVehicleId}/delete`	`DELETE`	Yes (Customer)	Remove vehicle from customer	None	`CommonResponse`
`/vehicle/{customerVehicleId}`	`GET`	Yes (Customer)	Get all vehicles for customer	None	`ServerPaginatedData<CustomerVehicle>`
`/vehicles`	`GET`	Yes (Customer)	Get specific vehicle details	None	`CustomerVehicle`

C# Request/Response Models

1. Add Customer Vehicle

public record VehicleAddRequest
{
    [Required(ErrorMessage = "VIN is required")]
    [StringLength(17, MinimumLength = 17, ErrorMessage = "VIN must be exactly 17 characters")]
    [RegularExpression(@"^[A-HJ-NPR-Z0-9]{17}$", ErrorMessage = "VIN contains invalid characters")]
    public required string Vin { get; init; }

}

public record CommonResponse
{
    public int Status { get; init; }
    public string? Message { get; init; }
}

2. Customer Vehicle Details (Response Model)

public record CustomerVehicle
  {
      // Primary Key
      public Guid Id { get; init; }

      // Ownership
      public Guid CustomerId { get; init; }
      public string Vin { get; init; } = null!;

      // Basic Identity
      public string? Make { get; init; }
      public string? Model { get; init; }
      public int? Year { get; init; }
      public string? Trim { get; init; }

      // Body
      public string? VehicleType { get; init; }   // Passenger Car
      public string? BodyType { get; init; }     // Coupe, Sedan
      public int? Doors { get; init; }

      // Powertrain
      public string? FuelType { get; init; }      // Gasoline
      public string? Transmission { get; init; }  // Automatic
      public int? TransmissionSpeeds { get; init; }
      public string? DriveType { get; init; }

      // Engine
      public string? EngineModel { get; init; }   // J30A4
      public int? EngineCylinders { get; init; }
      public decimal? EngineDisplacementL { get; init; }

      // Manufacturer / Plant
      public string? Manufacturer { get; init; }
      public string? PlantCountry { get; init; }
      public string? PlantState { get; init; }
      public string? PlantCity { get; init; }

      // Audit
      public DateTime CreatedAt { get; init; }
      public DateTime UpdatedAt { get; init; }
  }
  

3. Delete Customer Vehicle

 public record CommonResponse
  {
      public int Status { get; init; }
      public string? Message { get; init; }
  }

4. Get Customer Vehicles List

public record UserVehicleFilter
{
    public string? SearchKeyword { get; init; } // Search by VIN, Make, Model
    public string? Make { get; init; } // Filter by make
    public string? Model { get; init; } // Filter by model
    public int? YearFrom { get; init; } // Filter by year range
    public int? YearTo { get; init; }
    public string? VehicleType { get; init; } // Filter by vehicle type
    public string? FuelType { get; init; } // Filter by fuel type
    public int PageNumber { get; init; } = 1;
    public int RowsPerPage { get; init; } = 10;
}

Status Codes

The API uses status codes from VanTrackerService.Models.Common.RkStatusCode namespace:

Status Code	Description	When Used
0	OK	Successful request
-20009	INVALID_REQUEST	Invalid VIN, validation failure
-20001	RECORD_NOT_FOUND	Vehicle not found
-20012	UNAUTHORIZED	Missing or invalid authentication
-20017	FORBIDDEN	Customer not authorized to access
-20025	CONFLICT	Vehicle already exists for customer
-20014	TOO_MANY_REQUESTS	Rate limit exceeded
-16000	INTERNAL_ERROR	Server error during processing

Status Code Reference:

public record RkStatusCode
{
    public const int OK = 0;
    public const int INVALID_REQUEST = -20009;
    public const int RECORD_NOT_FOUND = -20001;
    public const int UNAUTHORIZED = -20012;
    public const int FORBIDDEN = -20017;
    public const int CONFLICT = -20025;
    public const int TOO_MANY_REQUESTS = -20014;
    public const int INTERNAL_ERROR = -16000;
}

Example API Requests & Responses

Add Vehicle Request Example

Request:

POST /vehicle HTTP/1.1
Host: api.rkauto.com
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "vin": "1HGCV41JXMN109186"
}

Success Response (201):

{
  "status": 0,
  "message": "Vehicle added successfully",
}

Error Response (400):

{
  "status": -20009,
  "message": "Invalid VIN format. VIN must be exactly 17 characters."
}

Error Response (409 - Conflict):

{
  "status": -20025,
  "message": "Vehicle with VIN 1HGCV41JXMN109186 already exists in your vehicle list."
}

Delete Vehicle Request Example

Request:

DELETE /vehicle/550e8400-e29b-41d4-a716-446655440000/delete HTTP/1.1
Host: api.rkauto.com
Authorization: Bearer <access_token>

Success Response (200):

{
  "status": 0,
  "message": "Vehicle removed successfully"
}

Error Response (404):

{
  "status": -20001,
  "message": "Vehicle not found"
}

Get All Vehicles Request Example

Request:

GET /vehicle/550e8400-e29b-41d4-a716-446655440000?pageNumber=1&rowsPerPage=10&make=Honda HTTP/1.1
Host: api.rkauto.com
Authorization: Bearer <access_token>

Success Response (200):

{
  "status": 0,
  "message": "Vehicles retrieved successfully",
  "data": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "customerId": "650e8400-e29b-41d4-a716-446655440001",
        "vin": "1HGCV41JXMN109186",
        "make": "Honda",
        "model": "Civic",
        "year": 2017,
        "trim": "EX-L",
        "vehicleType": "Passenger Car",
        "bodyType": "Sedan",
        "doors": 4,
        "fuelType": "Gasoline",
        "transmission": "Automatic",
        "transmissionSpeeds": 5,
        "driveType": "Front-Wheel Drive",
        "engineModel": "R18Z1",
        "engineCylinders": 4,
        "engineDisplacementL": 1.8,
        "manufacturer": "Honda",
        "plantCountry": "USA",
        "plantState": "OH",
        "plantCity": "East Liberty",
        "createdAt": "2025-12-29T10:30:00Z",
        "updatedAt": "2025-12-29T10:30:00Z"
      }
    ],
  "totalNumber": 1,
  "hasNextPage": false,
  "hasPreviousPage": false,
  "totalPages": 1,
  "pageNumber": 1,
  "rowsPerPage": 10
}

Get Specific Vehicle Request Example

Request:

GET /vehicles HTTP/1.1
Host: api.rkauto.com
Authorization: Bearer <access_token>

Success Response (200):

{
  "status": 0,
  "message": "Vehicle retrieved successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "customerId": "650e8400-e29b-41d4-a716-446655440001",
    "vin": "1HGCV41JXMN109186",
    "make": "Honda",
    "model": "Civic",
    "year": 2017,
    "trim": "EX-L",
    "vehicleType": "Passenger Car",
    "bodyType": "Sedan",
    "doors": 4,
    "fuelType": "Gasoline",
    "transmission": "Automatic",
    "transmissionSpeeds": 5,
    "driveType": "Front-Wheel Drive",
    "engineModel": "R18Z1",
    "engineCylinders": 4,
    "engineDisplacementL": 1.8,
    "manufacturer": "Honda",
    "plantCountry": "USA",
    "plantState": "OH",
    "plantCity": "East Liberty",
    "createdAt": "2025-12-29T10:30:00Z",
    "updatedAt": "2025-12-29T10:30:00Z"
  }
}

Third-Party Integrations:

VIN Validation API

Purpose: Validate VIN and retrieve comprehensive vehicle information. Additionally, verify that the vehicle was purchased from our organization.

Current Implementation (Placeholder):
- Provider: NHTSA (National Highway Traffic Safety Administration)
- API Endpoint: https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinExtended/{vin}?format=json
- Method: GET
- Rate Limit: Varies by NHTSA
- Timeout: 30 seconds
Current Request Example:
```
GET https://vpic.nhtsa.dot.gov/api/vehicles/DecodeVinExtended/1HGCM82633A004219?format=json HTTP/1.1
```
Current Response Example:
```
{
  "Count": 1,
  "Message": "Response returned successfully",
  "SearchCriteria": "VIN: 1HGCM82633A004219",
  "Results": [
    {
      "Vin": "1HGCM82633A004219",
      "Make": "HONDA",
      "Model": "ACCORD",
      "ModelYear": "2003",
      "Trim": "EX",
      "VehicleType": "PASSENGER CAR",
      "BodyClass": "Sedan",
      "Doors": "4",
      "FuelType": "Gasoline",
      "Transmission": "Automatic",
      "DriveType": "Front-Wheel Drive",
      "EngineModel": "F23A1",
      "EngineCylinders": "4",
      "EngineDisplacementL": "2.3",
      "Manufacturer": "Honda Manufacturing of Ohio, LLC.",
      "PlantCountry": "United States",
      "PlantState": "OH",
      "PlantCity": "East Liberty"
    }
  ]
}
```
⚠️ IMPORTANT - Future Replacement:

This NHTSA API is a temporary placeholder. The actual VIN validation will be replaced with RKAuto's proprietary API when available. The actual API will:
1. Validate VIN Format: Ensure VIN is valid (17 characters, proper checksum)
2. Retrieve Vehicle Data: Get comprehensive vehicle information
3. Verify Purchase Origin: CRITICAL - Confirm that the vehicle was purchased from RKAuto organization
4. Return Organization Flag: Include a flag indicating whether the vehicle qualifies for service under RKAuto
Expected Actual API Response (when available):
```
{
  "success": true,
  "isValidVin": true,
  "isPurchasedFromRKAuto": true,
  "vehicleData": {
    "vin": "1HGCM82633A004219",
    "make": "Honda",
    "model": "Accord",
    "modelYear": 2003,
    "trim": "EX",
    ...
  },
  "eligibleForService": true,
  "message": "Vehicle validated successfully"
}
```
Integration Points:
- Called during the Add Vehicle request flow
- Called before storing vehicle information in database
- Used for real-time VIN validation
- Cached responses to reduce API calls (configurable TTL: 24 hours)
Error Handling:
- If API is unavailable: Return 503 Service Unavailable
- If VIN is invalid: Return 400 Bad Request with validation error
- If vehicle not purchased from organization: Return 403 Forbidden with message "Vehicle not purchased from RKAuto"
- If API timeout: Return 504 Gateway Timeout after 30 seconds

Workflow:

Add Vehicle Feature Workflow

Customer Input VIN
     ↓
Validate VIN Format (17 chars, regex pattern)
     ↓
Call VIN Validation API (NHTSA for now → RKAuto API later)
     ↓
API Returns Vehicle Data
     ↓
Store Vehicle Information in Database
     ↓
Return Vehicle ID + Full Details
     ↓
Success Response to Customer

Detailed Flow Steps

Customer Initiates Add Vehicle
- Customer provides VIN (mandatory) and optional vehicle details
- Request validated for required fields and format
VIN Format Validation (Client-side + Server-side)
- Ensure VIN is exactly 17 characters
- Validate against regex pattern: ^[A-HJ-NPR-Z0-9]{17}$
- Check for duplicate VIN in customer's vehicle list
External API Call - VIN Validation
- Call VIN validation API with the VIN
- Retrieve comprehensive vehicle information
- Currently using NHTSA API (temporary)
- Will be replaced with RKAuto proprietary API (when available)
API Response Handling
- If API returns vehicle data successfully: Vehicle is valid and purchased from organization
- Use API response data as authoritative source for vehicle specifications
- Store source as "NHTSA" (or "RKAuto" when API changes)
- Store any VIN decode warnings from API
- If API returns error/invalid VIN: Return 400 Bad Request with validation error
- If API timeout or unavailable: Return 503/504 Service Unavailable
Data Enrichment
- Merge user-provided data with API response data
- Use API data as authoritative source for vehicle specifications
- Store source as "NHTSA" (or "RKAuto" when API changes)
- Store any VIN decode warnings from API
Database Storage
- Create new CustomerVehicle record with:
  - CustomerId (from authenticated customer)
  - VIN (primary identifier)
  - Vehicle details (from API)
  - Timestamps (CreatedAt, UpdatedAt)
- Transaction: Ensure atomic write operation
Response
- Return 201 Created with complete vehicle details
- Include vehicle ID for future reference
- Cache vehicle data locally (optional TTL: 24 hours)
Remove Vehicle Flow
- Verify customer owns the vehicle
- Delete from database
- Clear any cached data
- Return 200 OK
Get Vehicles Flow
- Apply customer filters (make, model, year, etc.)
- Paginate results
- Return paginated list of CustomerVehicles

Data Flow Diagram

┌─────────────┐
│   Client    │
│ (Web/Mobile)│
└──────┬──────┘
       │
       │ POST /vehicle
       │ {vin, optional details}
       ↓
┌──────────────────┐
│ VehicleController│
│  - Validate Req  │
│  - Check Auth    │
└────────┬─────────┘
         │
         ↓
┌──────────────────────┐
│ VehicleService       │
│ - Format Validation  │
│ - Duplicate Check    │
└────────┬─────────────┘
         │
         │ Call VIN Validation
         ↓
┌──────────────────────────────────┐
│  VIN Validation API              │
│  (NHTSA / Future: RKAuto API)    │
│  - Decode VIN                    │
│  - Get vehicle specs             │
│  - Verify purchase (future)      │
└────────┬─────────────────────────┘
         │
         │ Return vehicle data
         ↓
┌──────────────────────┐
│ VehicleService       │
│ - Merge data         │
│ - Enrich info        │
└────────┬─────────────┘
         │
         ↓
┌──────────────────────┐
│ VehicleRepository    │
│ - Save to DB         │
│ - Transaction mgmt   │
└────────┬─────────────┘
         │
         ↓
┌──────────────────┐
│  PostgreSQL      │
│  (uservahicle)   │
└────────┬─────────┘
         │
         │ Return new record
         ↓
┌──────────────────────┐
│ VehicleController    │
│ - Format response    │
│ - Set status 201     │
└────────┬─────────────┘
         │
         │ 201 Created + Vehicle Details
         ↓
┌─────────────┐
│   Client    │
└─────────────┘

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:
(List the unit tests that will be written for this feature.)
Integration Tests:
(Describe how integration testing will be conducted.)
Acceptance Criteria:
(Define the criteria that must be met for the feature to be considered complete.)
Testing Tools:
(List any tools that will be used for testing.)

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.)

Add-vehicle And validate VIN

Author(s)​

Last Updated Date​

SRS References​

Version History​

Feature Overview​

Requirements​

Design Specifications​

Add Customer Vehicle Endpoint​

C# Request/Response Models​

1. Add Customer Vehicle​

2. Customer Vehicle Details (Response Model)​

3. Delete Customer Vehicle​

4. Get Customer Vehicles List​

Status Codes​

Example API Requests & Responses​

Add Vehicle Request Example​

Delete Vehicle Request Example​

Get All Vehicles Request Example​

Get Specific Vehicle Request Example​

VIN Validation API​

Add Vehicle Feature Workflow​

Detailed Flow Steps​

Data Flow Diagram​

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

Add Customer Vehicle Endpoint

C# Request/Response Models

1. Add Customer Vehicle

2. Customer Vehicle Details (Response Model)

3. Delete Customer Vehicle

4. Get Customer Vehicles List

Status Codes

Example API Requests & Responses

Add Vehicle Request Example

Delete Vehicle Request Example

Get All Vehicles Request Example

Get Specific Vehicle Request Example

VIN Validation API

Add Vehicle Feature Workflow

Detailed Flow Steps

Data Flow Diagram

Development Tasks & Estimates

Testing & Quality Assurance

Deployment Considerations

Risks & Mitigations

Review & Approval