FXQL (Foreign Exchange Query Language) Parser

Project Overview

This project implements a custom parsing system for Foreign Exchange (FXQL) statements, allowing users to define currency pair transactions with buy, sell, and cap amounts.

Table of Contents

• Features
• Prerequisites
• Local Development Setup
• Environmental Variables
• API Documentation
• Design Decisions
• Testing
• Deployment

Features

• Parse complex Foreign Exchange statements
• Validate currency pairs and transaction amounts
• Store parsed statements in a database
• Comprehensive error handling
• Supports multiple currency pair statements in a single request

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v18+ recommended)
• npm or yarn
• PostgreSQL (or your preferred database)
• Docker (optional, for containerization)

Local Development Setup

1. Clone the Repository

 git clone https://github.com/hamzzy/fxql-parser-api.git
 cd fxql-parser

2. Install Dependencies

npm install
# or
yarn install

3. Set Up Environment Variables

Create a .env file in the project root with the following variables:

POSTGRES_NAME=""
POSTGRES_USER=""
POSTGRES_PASSWORD=""
# Database Connection
DATABASE_URL="postgresql://username:password@localhost:5432/fxql_db?schema=public"

# Application Configuration
PORT=3000

4. Initialize Database

# Generate Prisma client
npx prisma generate

# Run migrations
npx prisma migrate dev

# Optional: Seed initial data
npx prisma db seed

5. Run the Application

# Development mode
npm run start:dev
# or
yarn start:dev

# Production mode
npm run start:prod
# or
yarn start:prod

Docker

# Build Docker image
docker compose up

API Documentation

Documentation : https://fxql-parser.up.railway.app/api

Endpoint: POST https://fxql-parser.up.railway.app/fxql-statements

Request Payload

{
  "FXQL": "USD-GBP {\\n  BUY 0.85\\n  SELL 0.90\\n  CAP 10000\\n}"
}

Successful Response

{
  "message": "FXQL Statement Parsed Successfully.",
  "code": "FXQL-200",
  "data": [
    {
      "EntryId": 1,
      "SourceCurrency": "USD",
      "DestinationCurrency": "GBP",
      "SellPrice": 0.85,
      "BuyPrice": 100,
      "CapAmount": 10000
    }
  ]
}

Error Response

{
  "message": "Invalid currency format",
  "code": "FXQL-400",
  "details": "Specific error information"
}

Design Decisions

Parsing Strategy

• Lexer-Parser architecture for robust statement parsing
• Stateless parsing with comprehensive error collection
• Support for multiple statements in a single request

Currency Validation

• Strict 3-letter uppercase currency code validation
• Predefined list of supported currencies
• Prevents parsing of unsupported or malformed currency pairs

Error Handling

• Granular error tracking
• Preserves parsing context (line, column)
• Returns multiple errors if present
• Provides clear, actionable error messages

Performance Considerations

• Atomic database transactions
• Efficient input normalization
• Limit of 1000 currency pairs per request to prevent system overload

Testing

Running Tests

# Unit tests
npm run test
# or
yarn test

# Coverage report
npm run test:cov
# or
yarn test:cov

Troubleshooting

• Ensure all environment variables are correctly set
• Check database connectivity
• Verify Node.js and npm versions
• Review application logs for detailed error information