NumberToWords - Currency Converter Web Application

A web application that converts numerical currency values into their written word representation.

Features

• Converts numbers to words in currency format
• Supports values from -999,999,999.99 to 999,999,999.99
• Clean, responsive web interface
• RESTful API endpoint
• Real-time conversion with error handling

Example

Input:123.45
Output:ONE HUNDRED AND TWENTY-THREE DOLLARS AND FORTY-FIVE CENTS

Prerequisites

• .NET 8.0 SDK or higher
• A modern web browser (Chrome, Firefox, Safari, or Edge)

Quick Start

1. Clone the Repository

git clone https://github.com/NathanPerrier/NumberToWords.git
cd NumberToWords

2. Build the Application

cd code
dotnet restore
dotnet build

3. Run the Application

dotnet run --launch-profile http

The application will start and be available at:

• Web Interface: http://localhost:5122
• Swagger API Documentation: http://localhost:5122/swagger

4. Use the Application

Via Web Interface:

1. Open http://localhost:5122 in your browser
2. Enter a number (e.g., 123.45)
3. Click "Convert to Words" or press Enter
4. View the result

Via API:

curl -X POST "http://localhost:5122/api/conversion/convert" \
-H "Content-Type: application/json" \
-d '{"value": "123.45"}'

Project Structure

NumberToWords/
├── code/ # Main application code
│ ├── Controllers/ # API controllers
│ ├── Services/ # Business logic services
│ ├── wwwroot/ # Static web files
│ │ ├── index.html # Main web interface
│ │ ├── css/ # Stylesheets
│ │ └── js/ # JavaScript files
│ ├── Program.cs # Application entry point
│ └── NumbersToWords.csproj # Project configuration
├── DESIGN_APPROACH.md # Design decisions document
├── TEST_PLAN.md # Testing strategy document
└── README.md # This file

API Documentation

Convert Number to Words

Endpoint:POST /api/conversion/convert

Request Body:

{
"value": "123.45"
}

Success Response:

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

Error Response:

{
"success": false,
"error": "Invalid format. Please enter a valid number (e.g., 123.45)"
}

Health Check

Endpoint:GET /api/conversion/health

Response:

{
"status": "healthy",
"timestamp": "2024-01-20T10:30:00Z"
}

Input Validation Rules

• Numbers must be between -999,999,999.99 and 999,999,999.99
• Maximum of 2 decimal places
• Valid formats: 123, 123.45, -123.45
• Invalid formats: abc, 12.345, 1,000

Development

Running with HTTPS

dotnet run --launch-profile https

Access at: https://localhost:7124

Running Tests

Currently, manual testing is performed using the TEST_PLAN.md document. Unit tests can be added by creating a test project:

dotnet new xunit -n NumbersToWords.Tests
dotnet sln code/NumbersToWords.sln add NumbersToWords.Tests/NumbersToWords.Tests.csproj

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile browsers (iOS Safari, Chrome Android)

Troubleshooting

Port Already in Use

If you see an error about port 5122 being in use:

1. Change the port in code/Properties/launchSettings.json
2. Or find and stop the process using the port

Build Errors

Ensure you have .NET 8.0 SDK installed:

dotnet --version

API Not Responding

1. Check that the application is running
2. Verify the correct URL and port
3. Check browser console for JavaScript errors