Contributing to Banking & ATM Locator
This guide covers the implementation details and contribution guidelines for the Banking & ATM Locator feature.
Overview
The Banking & ATM Locator provides comprehensive search and discovery of banking facilities across Ghana, integrating real-time data from OpenStreetMap with fallback static data.
Architecture
Module Structure
src/banking/
├── banking.controller.ts # API endpoints and validation
├── banking.service.ts # Business logic and data processing
├── banking.module.ts # Module configuration
├── dto/ # Data transfer objects
│ ├── bank.dto.ts # Main bank entity definition
│ ├── bank-search.dto.ts # Search query parameters
│ └── bank-search-response.dto.ts # API response structure
├── entities/
│ └── bank.entity.ts # TypeScript interfaces
└── services/
└── bank-data-provider.service.ts # External data integration
Key Components
BankingController
- Path:
src/banking/banking.controller.ts
- Purpose: Handles HTTP requests and validates input parameters
- Endpoints: 6 endpoints for comprehensive banking facility search
- Validation: Uses class-validator for input sanitization
BankingService
- Path:
src/banking/banking.service.ts
- Purpose: Implements business logic and data processing
- Features: Location-based search, data filtering, result sorting
- Distance Calculation: Haversine formula for accurate geolocation
BankDataProviderService
- Path:
src/banking/services/bank-data-provider.service.ts
- Purpose: Manages external data sources and caching
- Integration: OpenStreetMap Overpass API with static fallback
- Caching: 24-hour TTL for performance optimization
API Endpoints
Search Banks and ATMs
GET /api/v1/banking/search
Query Parameters:
q
(string, optional): Search query for bank name or locationlat
(number, optional): Latitude for location-based searchlng
(number, optional): Longitude for location-based searchradius
(number, optional): Search radius in meters (default: 5000)type
(string, optional): Filter by 'bank', 'atm', or 'all' (default: 'all')limit
(number, optional): Maximum results to return (default: 20)
Find Nearby Banks
GET /api/v1/banking/nearby
Query Parameters:
lat
(number, required): Latitude coordinatelng
(number, required): Longitude coordinateradius
(number, optional): Search radius in meters (default: 5000)type
(string, optional): Filter by facility type
Browse by Region
GET /api/v1/banking/region
Query Parameters:
region
(string, required): Ghana region nametype
(string, optional): Filter by facility typelimit
(number, optional): Maximum results
Browse by City
GET /api/v1/banking/city
Query Parameters:
city
(string, required): City nametype
(string, optional): Filter by facility typelimit
(number, optional): Maximum results
Data Sources
OpenStreetMap Integration
- API: Overpass API for real-time banking data
- Query: Comprehensive Overpass QL for banks and ATMs
- Coverage: All of Ghana with detailed facility information
- Update Frequency: Real-time with 24-hour caching
Fallback Data
- Purpose: Ensures service availability when external APIs fail
- Coverage: Major banks and ATM networks in Ghana
- Format: Structured JSON with complete facility details
- Maintenance: Regularly updated with verified information
Testing
Unit Tests
npm test src/banking/banking.service.spec.ts
npm test src/banking/banking.controller.spec.ts
Integration Tests
npm test src/banking/services/bank-data-provider.service.integration.spec.ts
E2E Tests
npm run test:e2e -- --testNamePattern="Banking"
Development Guidelines
Adding New Banking Data
-
Static Data Updates
- Location:
src/banking/data/banks.json
- Format: Follow existing BankDto structure
- Validation: Run tests to ensure data integrity
- Location:
-
OpenStreetMap Queries
- Location:
src/banking/services/bank-data-provider.service.ts
- Method:
buildOverpassQuery()
- Testing: Use Overpass Turbo for query validation
- Location:
Error Handling
// Location validation
if ((query.lat && !query.lng) || (!query.lat && query.lng)) {
throw new HttpException(
"Both latitude and longitude are required for location-based search",
HttpStatus.BAD_REQUEST
);
}
// Service error handling
try {
return await this.bankingService.searchBanks(query);
} catch (error) {
throw new HttpException(
"Failed to search banks",
HttpStatus.INTERNAL_SERVER_ERROR
);
}
Performance Optimization
Caching Strategy
- TTL: 24 hours for external API data
- Key Structure:
banking:${region}:${type}:${timestamp}
- Invalidation: Automatic expiry with manual refresh option
Distance Calculation
private calculateDistance(
lat1: number,
lng1: number,
lat2: number,
lng2: number
): number {
// Haversine formula implementation
const R = 6371e3; // Earth's radius in meters
const φ1 = (lat1 * Math.PI) / 180;
const φ2 = (lat2 * Math.PI) / 180;
// ... calculation
}
Code Style
Naming Conventions
- Controllers:
BankingController
- Services:
BankingService
,BankDataProviderService
- DTOs:
BankDto
,BankSearchQueryDto
- Interfaces:
IBankEntity
,IBankSearchParams
Documentation
- Swagger: All endpoints must have complete OpenAPI documentation
- JSDoc: Public methods require comprehensive documentation
- Examples: Include realistic examples in API docs
Validation
@ApiProperty({
description: 'Search radius in meters',
example: 5000,
minimum: 100,
maximum: 50000,
required: false,
})
@IsOptional()
@IsNumber()
@Min(100)
@Max(50000)
radius?: number = 5000;
Common Issues & Solutions
OpenStreetMap API Timeouts
- Issue: Overpass API occasionally times out
- Solution: Implemented fallback to static data
- Prevention: Optimize query complexity and use caching
Location Accuracy
- Issue: GPS coordinates may be imprecise
- Solution: Use configurable search radius with reasonable defaults
- Enhancement: Implement fuzzy matching for addresses
Data Inconsistency
- Issue: External data sources may have outdated information
- Solution: Combine multiple sources with intelligent deduplication
- Monitoring: Regular data quality checks
Future Enhancements
Planned Features
-
Advanced Search Filters
- Business hours filtering
- Service-specific search (ATM, foreign exchange, etc.)
- Accessibility features
-
Data Quality
- User feedback system for facility information
- Automated data validation workflows
- Real-time availability status
-
Performance
- Geographic indexing for faster searches
- Predictive caching based on usage patterns
- CDN integration for static data
Integration Opportunities
- Payment Systems: Link to mobile money and card networks
- Transport Module: Distance and route integration
- Location Services: Address validation for banking facilities
Getting Started
-
Setup Development Environment
cd backend
npm install
npm run start:dev -
Run Tests
npm test
npm run test:e2e -
API Testing
- Open
http://localhost:3000/api/docs
- Test endpoints using Swagger UI
- Verify data accuracy and response times
- Open
-
Code Quality
npm run lint
npm run format
npm run build
For questions or suggestions, please refer to the main contributing guidelines or open an issue on GitHub.