Skip to content

DESIGN_APPROACH.md

Latest commit

 

History

History
178 lines (136 loc) · 6 KB

DESIGN_APPROACH.md

File metadata and controls

178 lines (136 loc) · 6 KB

Design Approach - Number to Words Converter

Executive Summary

This document outlines the design decisions and architectural approach for the Number to Words Converter web application. The solution implements a clean, maintainable architecture using ASP.NET Core Web API with a responsive web interface.

1. Technology Stack Selection

Backend: ASP.NET Core 8.0 with C#

Reasons for Selection:

  • Performance: ASP.NET Core is one of the fastest web frameworks with excellent throughput
  • Cross-platform: Runs on Windows, Linux, and macOS
  • Modern Framework: Latest .NET 8.0 provides current language features and optimizations
  • Dependency Injection: Built-in DI container for clean separation of concerns
  • Developer Productivity: Strong typing, IntelliSense, and comprehensive tooling

Alternatives Considered:

  • Java Spring Boot: Excellent option but requires more boilerplate code
  • Node.js: Good for simple APIs but lacks strong typing without TypeScript
  • Python Flask/Django: Good options but performance is lower than .NET Core

Frontend: Vanilla JavaScript with HTML5/CSS3

Reasons for Selection:

  • Simplicity: No build process required for a simple conversion tool

  • Performance: No framework overhead for a single-page application

  • Browser Compatibility: Works in all modern browsers without transpilation

  • Maintainability: Easy to understand and modify without framework knowledge

  • Alternatives Considered:

  • React: Overkill for a single-form application

  • Angular: Too heavy for simple requirements

  • Vue.js: Good option but adds unnecessary complexity

2. Architecture Design

API Design Pattern: RESTful Web API

Implementation:

POST /api/conversion/convert
{
    "value": "123.45"
}

Response:
{
    "success": true,
    "words": "ONE HUNDRED AND TWENTY-THREE DOLLARS AND FORTY-FIVE CENTS",
    "originalValue": "123.45"
}

Reasons:

  • Standard HTTP Methods: Uses POST for conversion operation
  • JSON Format: Universal data format for web APIs
  • Clear Response Structure: Includes success flag and error messages
  • Stateless: Each request is independent

Service Layer Pattern

Implementation:

  • INumberToWordsService interface for abstraction
  • NumberToWordsService concrete implementation
  • Registered as Scoped in DI container

Benefits:

  • Testability: Easy to mock for unit testing
  • Flexibility: Can swap implementations
  • Separation of Concerns: Business logic separated from controllers

3. Algorithm Design

Number to Words Conversion Algorithm

Approach:

  1. Input Validation: Regex pattern for currency format validation
  2. Number Parsing: Convert string to decimal with proper culture handling
  3. Range Checking: Ensure number is within supported range
  4. Dollar/Cents Separation: Split decimal into whole and fractional parts
  5. Recursive Conversion: Break down numbers into groups of thousands
  6. Text Assembly: Build final string with proper formatting

Key Features:

  • Handles numbers up to 999,999,999.99
  • Supports negative numbers
  • Proper singular/plural handling (DOLLAR vs DOLLARS)
  • Groups of three digits (thousands, millions)

Algorithm Complexity:

  • Time: O(log n) where n is the number value
  • Space: O(1) constant space for conversion arrays

4. Error Handling Strategy

Multi-Layer Validation

  1. Client-Side: Basic validation for empty input
  2. Controller Level: Format validation using regex
  3. Service Level: Business rule validation
  4. Global Exception Handling: Catch-all for unexpected errors

Error Response Format:

{
    "success": false,
    "error": "Descriptive error message"
}

5. Security Considerations

Input Validation

  • Regex Pattern: ^-?\d{1,9}(\.\d{0,2})?$
  • Prevents SQL injection by not using database
  • Prevents XSS by validating input format
  • Limited input size to prevent DoS attacks

API Security

  • Input sanitization before processing
  • Proper HTTP status codes for errors
  • No sensitive data in responses

6. User Interface Design

Design Principles

  1. Simplicity: Single-purpose interface
  2. Responsiveness: Works on all device sizes
  3. Accessibility: Proper labels and ARIA attributes
  4. Feedback: Clear success/error messages

User Experience Features

  • Auto-focus on input field
  • Enter key submission
  • Loading state during conversion
  • Animated result display
  • Example conversions shown

7. Performance Optimizations

  1. Minimal Dependencies: Only Swashbuckle for API documentation
  2. Efficient Algorithm: No recursive string concatenation
  3. Client-Side Caching: Browser caches static assets
  4. Async Operations: Non-blocking API calls

8. Rejected Approaches

Database Storage

Rejected Because:

  • No requirement for persistence
  • Adds complexity without value
  • Performance overhead for simple calculations

Microservices Architecture

Rejected Because:

  • Over-engineering for single functionality
  • Deployment complexity
  • Network latency between services

Client-Side Only Solution

Rejected Because:

  • Business logic exposure in browser
  • Limited programming capabilities
  • Harder to maintain complex conversion logic

9. Future Enhancements

  1. Internationalization: Support for other currencies and languages
  2. Caching: Redis cache for common conversions
  3. Batch Processing: Convert multiple numbers at once
  4. API Rate Limiting: Prevent abuse
  5. Analytics: Track usage patterns
  6. Unit Testing: Comprehensive test suite

Conclusion

The chosen approach balances simplicity with functionality, providing a clean, maintainable solution that meets all requirements while remaining extensible for future enhancements. The architecture follows SOLID principles and industry best practices for web application development.