Name Verification Application

Overview

The Name Verification Application is a specialized tool designed to demonstrate intelligent name matching with strict architectural separation. The system consists of two independent components: a Target Name Generator and a Name Verifier, operating under the constraint that the verifier must treat the generator as a black box.

Key Features

• Target Name Generation: Generate unique human names from natural language prompts using LLM integration
• Name Verification: Verify candidate names against the latest generated target with fuzzy matching
• Black Box Architecture: Strict isolation between generator and verifier components
• Comprehensive Test Suite: 30 test cases covering various name matching scenarios
• Mock Mode: Fallback to mock data when LLM API keys are unavailable
• Production-Ready: Full test coverage and robust error handling

Architecture and Design

Core Principles

• Black Box Constraint: The verifier cannot access generator internals, chat history, or call back into the generator
• Deterministic Verification: Matching algorithm produces stable, consistent results
• Isolated State: Only the latest generated name string is shared between components

Component Architecture

┌─────────────────┐
│    Client UI    │
│   (React/TS)    │
└─────────────────┘
        │
        │
        │
        ▼
┌───────────────┐               ┌────────────────┐
│  API server   │   generates   │                │
│ (Express/TS)  │──────────────►│ Name Generator │
│               │               │   (LLM/Mock)   │
└───────────────┘               └────────────────┘
        │
        │ exposes only
        │ targetName:string
        ▼
┌─────────────────┐
│  Name Verifier  │
│ (Fuzzy Matcher) │
└─────────────────┘

Technology Stack

Frontend

• Framework: React 19 with TypeScript
• Styling: Tailwind CSS 4
• Build Tool: Vite
• HTTP Client: Native Fetch API with typed wrappers

Backend

• Runtime: Node.js (>=18.0.0)
• Framework: Express.js with TypeScript
• LLM Integration: NVIDIA NIM API (with mock fallback)
• Testing: Jest with comprehensive test suite
• Code Quality: TypeScript, ESLint, Prettier

Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• (Optional) NVIDIA NIM API key for live name generation

Installation

1. Clone and Setup

# Clone the repository
git clone <repository-url>
cd name_verification_app

# Install root dependencies
npm install

# Install client and server dependencies
npm run install:all

2. Environment Configuration

Create a .env file in the server directory:

# server/.env
LLM_PROVIDER=nvidia_nim
LLM_MODEL=meta/llama-3.3-70b-instruct
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.9
LLM_MAX_TOKENS=256

# Optional: Add your NVIDIA NIM API key for live generation
# NIM_API_KEY=your_nim_api_key_here
NIM_BASE_URL=https://integrate.api.nvidia.com/v1

PORT=3001
NODE_ENV=development

Running the Application

Development Mode

Start both client and server concurrently:

npm run dev

This will launch:

• Client: http://localhost:3000
• Server: http://localhost:3001
• API Proxy: Client automatically proxies /api requests to the server

Production Build

# Build both client and server
npm run build

# Start production server
npm start

Testing

Run Test Suite

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

Test Coverage

The application includes 63 comprehensive tests covering:

• Name matching algorithms (30 test cases)
• Edge cases and error handling
• Performance benchmarks
• Configuration validation

Usage Guide

1. Generating Target Names

1. Navigate to the "Target Name Generator" panel
2. Enter a prompt (e.g., "Generate a random Arabic sounding name with Al and ibn")
3. Click "Generate"
4. The system will produce a target name and store it as the latest

2. Verifying Candidate Names

1. Navigate to the "Name Verifier" panel
2. Enter a candidate name to check
3. Click "Verify"
4. View results including match status, confidence score, and explanation

Example Workflow

Prompt: "Generate a Spanish name with two last names"
Generated Target: "Maria Garcia Lopez"

Candidate: "Mario Garcia Lopez"
Result: No Match (51% confidence)
Reason: Gendered name difference

Candidate: "Maria Garcia-Lopez"
Result: Match (92% confidence)
Reason: Names match with minor variations

API Documentation

Generate Endpoint

POST /api/generate

Request:

{
  "prompt": "Generate a random Arabic sounding name"
}

Response:

{
  "targetName": "Ahmed Al Fayed"
}

Verify Endpoint

POST /api/verify

Request:

{
  "candidateName": "Ahmad Alfayed"
}

Response:

{
  "match": true,
  "confidence": 0.85,
  "reason": "Names match with minor variations (spelling, nickname, or transliteration)",
  "targetName": "Ahmed Al Fayed"
}

Name Matching Algorithm

The verifier implements a sophisticated multi-layered matching strategy:

1. Normalization

• Convert to lowercase
• Remove diacritics and punctuation
• Standardize spacing and hyphens
• Special handling for Arabic names (Al, ibn, Abdul)

2. Token Matching

• Greedy token alignment algorithm
• Nickname equivalence mapping (Bob ↔ Robert, Liz ↔ Elizabeth)
• Transliteration variations (Mohammed ↔ Muhammad)
• Phonetic suffix handling (v ↔ ff, ov ↔ off)

3. Similarity Scoring

• Levenshtein distance for typos
• String similarity thresholds
• Cultural-specific rule sets
• Order swap detection and penalization

4. Confidence Calculation

• Weighted average of token matches
• Penalties for structural differences
• Adaptive thresholds based on name complexity

Test Cases

The application passes 30 specified test cases including:

Expected Matches (18 cases)

• Transposition typos: "Tyler Bliha" ↔ "Tlyer Bilha"
• Cultural variations: "Mohammed Al Fayed" ↔ "Muhammad Alfayed"
• Nickname equivalence: "Bob Ellensworth" ↔ "Robert Ellensworth"
• Punctuation differences: "Sarah O'Connor" ↔ "Sara Oconnor"

Expected Non-Matches (12 cases)

• Different first names: "John Smith" ↔ "James Smith"
• Order swaps: "Ali Hassan" ↔ "Hassan Ali"
• Gendered differences: "Maria Gonzalez" ↔ "Mario Gonzalez"
• Different surname roots: "Ahmed Al Rashid" ↔ "Ahmed Al Rashidi"

Configuration Options

Environment Variables

Variable	Default	Description
LLM_PROVIDER	nvidia_nim	LLM provider (nvidia_nim, openai_compatible, other)
LLM_MODEL	meta/llama-3.3-70b-instruct	Model identifier
LLM_TEMPERATURE	0.2	Generation creativity (0-2)
LLM_TOP_P	0.9	Nucleus sampling parameter
LLM_MAX_TOKENS	256	Maximum tokens per generation
NIM_API_KEY	-	NVIDIA NIM API key (optional)
NIM_BASE_URL	https://integrate.api.nvidia.com/v1	API endpoint
PORT	3001	Server port
NODE_ENV	development	Runtime environment

Mock Mode

When no API key is provided, the system automatically uses a mock name generator that:

• Returns consistent names based on prompt hash
• Includes all test case names in rotation
• Provides deterministic behavior for testing

Project Structure

name_verification_app/
├── client/                    # React frontend
│   ├── src/
│   │   ├── api/              # HTTP client and types
│   │   ├── components/       # React components
│   │   └── App.tsx          # Main application
│   └── vite.config.ts       # Build configuration
├── server/                   # Express backend
│   ├── src/
│   │   ├── config/          # Configuration management
│   │   ├── generator/       # Name generation logic
│   │   ├── verifier/        # Name matching algorithm
│   │   ├── storage/         # Latest target persistence
│   │   ├── routes/          # API endpoints
│   │   └── index.ts         # Server entry point
│   └── test/               # Comprehensive test suite
├── package.json            # Root build and run scripts
└── README.md              # This documentation

Development Guidelines

Code Style

• TypeScript strict mode enabled
• ESLint with React/TypeScript rules
• Prettier for code formatting
• Consistent import ordering

Error Handling

• Structured error responses from API
• Graceful degradation when services unavailable
• Comprehensive logging in development mode
• User-friendly error messages in UI

Limitations and Future Improvements

Current Limitations

• English-centric nickname mappings
• Limited support for non-Latin scripts
• Basic phonetic matching (no Soundex/Metaphone)
• In-memory state persistence (restart clears state)

Troubleshooting

Common Issues

Server fails to start:

• Check Node.js version (>=18 required)
• Verify all dependencies are installed (npm run install:all)
• Ensure PORT 3001 is available

Name generation fails:

• Check NIM_API_KEY in server/.env
• Verify network connectivity to NVIDIA NIM
• Review server logs for API errors

Tests failing:

• Ensure all dependencies are installed
• Check test environment configuration
• Verify no other process is using test ports

Client cannot connect to server:

• Verify both client and server are running
• Check proxy configuration in vite.config.ts
• Ensure CORS is properly configured

Debug Mode

Enable detailed logging by setting in server/.env:

DEBUG=true
NODE_ENV=development

Security Considerations

• API keys stored server-side only
• No sensitive data in client code
• Input validation on all endpoints
• CORS configured for development only
• Environment-based configuration

Acknowledgments

• Test cases designed to cover realistic name matching scenarios
• Architecture inspired by clean separation principles
• Fuzzy matching algorithm optimized for name-specific patterns
• Built as a demonstration of robust system design with TypeScript

This application serves as both a practical tool for name verification and a demonstration of well-architected, test-driven TypeScript application development with clear separation of concerns and comprehensive error handling.