Skip to content

Developer Q&A

This document captures common questions, clarifications, and design decisions that arise during the development process. Each entry provides context and rationale to help developers understand system architecture and implementation choices.

Battery Swap Service

Q-BSS-001: Battery Identification and Validation

Question: Which service should be responsible for battery identification and how should it be done? What are the metrics to identify a returned battery?

Context: During battery swap operations, we need to validate that the battery being returned matches the expected asset and belongs to the correct user.

Answer:

Responsible Service: Battery identification should be handled by the Inventory Management service in coordination with the Service Plan service.

Identification Metrics: 1. Primary Identifier: Battery unique ID (serial number, RFID tag, or QR code) 2. Ownership Validation: Cross-reference with currentAsset field in the active service plan 3. Asset Registry Check: Verify battery exists in the asset inventory system 4. State Validation: Confirm battery state matches expected swap workflow state

Additional Validation Beyond Ownership: - Physical Condition: Battery health status and damage assessment - Compatibility: Ensure battery model/type matches the service plan requirements - Swap Eligibility: Verify the battery has been in use for a valid duration - Location Check: Confirm swap is happening at an authorized location - Tamper Detection: Check for unauthorized modifications or seal integrity - Charge Level: Validate battery meets minimum charge threshold for return

Implementation Notes: - Use multi-factor validation to prevent fraud - Log all identification attempts for audit trail - Consider implementing fallback identification methods

Service Validation and Optimization

Q-VAL-002: Consolidating Customer and Payment Validation

Question: Why should we run Customer Identification, Customer Status Validation, and Payment Status Validation as separate steps? Why not use the opportunity of Customer Identification to also check Customer Status and Payment Status simultaneously? All this information is available in the servicePlan, which would reduce requests by 2.

Context: Current workflow appears to make separate calls for customer identification, status validation, and payment validation, potentially creating unnecessary overhead.

Answer:

Rationale for Separation:

  1. Separation of Concerns: Each validation addresses a distinct domain:
  2. Customer Identification: Authentication/Authorization domain
  3. Customer Status: Account management domain

  4. Payment Status: Financial/billing domain

  5. Failure Isolation: Separate validations allow for:

  6. Specific error messaging for each failure type
  7. Independent retry logic per validation type

  8. Clearer audit trails and debugging

  9. Service Independence: Different services may own different data:

  10. Identity Service owns customer identification
  11. Account Service owns customer status
  12. Payment Service owns payment status

Optimization Opportunity:

You raise a valid point. Consider implementing a composite validation pattern where:

  • A ServiceEligibilityValidator orchestrates the three checks
  • Single data fetch from servicePlan
  • Parallel validation execution
  • Composite result with granular error details

Recommended Approach: 

interface ServiceEligibilityCheck {
  customerIdentified: boolean;
  customerStatusValid: boolean;
  paymentStatusValid: boolean;
  eligibilityResult: 'ELIGIBLE' | 'INELIGIBLE';
  failureReasons?: string[];
}

This maintains separation of concerns while optimizing for performance.

Q-VAL-003: Equipment Condition Validation Service

Question: Do we have a service to deal with validating the Equipment Condition?

Answer:

Current State: This should be clarified with the architecture team.

Expected Implementation:

Equipment condition validation would typically be handled by:

  1. Asset Inspection Service: Dedicated service for physical asset validation
  2. Visual inspection protocols
  3. Automated sensor-based diagnostics

  4. Condition scoring algorithms

  5. Integration Points:

  6. IoT sensors on batteries (if available)
  7. Manual inspection app/interface for swap station operators

  8. Computer vision for automated damage detection

  9. Validation Triggers:

  10. Pre-swap validation (before accepting returned battery)
  11. Post-swap validation (before issuing replacement battery)
  12. Periodic maintenance checks

Action Items: - [ ] Verify if Asset Inspection Service exists in current architecture - [ ] Define equipment condition validation criteria - [ ] Establish condition grading system (e.g., Grade A-D) - [ ] Determine rejection thresholds

Event-Driven Architecture

Q-EVENT-004: Service Intent Signal Response Handling

Question: When we emit a Service Intent Signal, who should respond to it?

Context: Understanding the event-driven architecture and service responsibilities for intent signal handling.

Answer:

Response Pattern:

Service Intent Signals follow a publish-subscribe pattern where:

  1. Signal Emitter: The service that detects an intent/need (e.g., Battery Swap Orchestrator)

  2. Signal Responders: One or more services interested in that intent type:

  3. Direct Responders: Services that must act on the signal (synchronous-style)
  4. Observers: Services that log/monitor but don't act (analytics, audit)
  5. Conditional Responders: Services that act based on signal payload

Example - Battery Swap Intent Signal:

Signal: "SWAP_INTENT_DETECTED"
Payload: { customerId, location, timestamp }

Responders:
- Inventory Service → Reserve battery slot
- Quota Service → Verify swap quota
- Payment Service → Check payment status  
- Analytics Service → Log intent (observer)
- Notification Service → Alert customer (conditional)

Design Principles:

  1. Loose Coupling: Responders register interest via MQTT subscriptions, not direct calls
  2. Multiple Responders: Signals can have 0-to-many responders
  3. No Guaranteed Order: Responses may arrive in any sequence
  4. Idempotency: Responders must handle duplicate signals gracefully

Implementation: - Use MQTT topic patterns for routing (e.g., intent/swap/#) - Document expected responders in service manifest - Implement timeout/circuit breaker for critical response paths

Action Items: - [ ] Document all Service Intent Signal types - [ ] Map signals to expected responders - [ ] Define SLAs for critical response paths

Contributing to this Q&A

When adding new entries:

  1. Use consistent labeling: Q-[DOMAIN]-[NUMBER] (e.g., Q-BSS-005)
  2. Include context: Explain why the question arose
  3. Provide actionable answers: Include code examples or specific guidance
  4. Link to related documentation: Reference architecture diagrams or API docs
  5. Track action items: Use checkboxes for follow-up tasks

Domain Prefixes: - BSS - Battery Swap Service - VAL - Validation & Authorization - EVENT - Event-Driven Architecture - DATA - Data Models & Persistence - API - API Design - PERF - Performance & Optimization

Last Updated: 2025-11-07