⚙️ Bitcoin Map Backend

Backend service for the Bitcoin Map application that provides APIs for Bitcoin-accepting locations.

🚀 Getting Started

💻 Development Mode

# Install dependencies
npm install

# Start the development server
npm run dev

The development server will run at http://localhost:3001 with auto-reload enabled.

🏭 Production Mode

# Install dependencies
npm install

# Build the application
npm run build

# Start the production server
npm run start

The production server will run at http://localhost:3001.

🧪 Testing

The application includes a comprehensive test suite built with Jest:

# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Generate test coverage report
npm run test:coverage

The test coverage report will be generated in the coverage/ directory.

🔄 Continuous Integration

Tests are automatically run on each pull request and push to the main branch using GitHub Actions. The workflow:

1. Runs all tests
2. Generates a coverage report
3. Checks if coverage is above the threshold (75%)
4. Comments on the PR with the coverage report

This ensures that all code changes maintain quality and don't break existing functionality.

For more details about the testing approach and structure, see the tests README.

🔌 API Routes

Method	Route	Description
GET	/health	Health check endpoint
GET	/api/locations	Get all Bitcoin-accepting locations with complete details
GET	/api/coordinates	Get only coordinates of all Bitcoin-accepting locations (optimized for initial map loading)
GET	/api/locations/:id	Get complete details of a specific Bitcoin-accepting location by ID
GET	/api/stats	Get statistics about Bitcoin locations including total count, location types, and country distribution

🚀 Performance Optimizations

The API has been optimized for better performance and user experience:

• Coordinates-Only Endpoint: The /api/coordinates endpoint returns only essential location data (id, type, lat, lon), reducing payload size by up to 90% compared to full location details.
• On-Demand Location Details: The /api/locations/:id endpoint allows fetching complete details only when needed (e.g., when a user clicks on a map marker).
• Efficient Data Loading: This two-step approach significantly improves initial map loading time, especially on slower connections or mobile devices.
• Reduced Bandwidth Usage: By loading only necessary data, the application uses less bandwidth and is more responsive.

🔄 External API Integration

The backend integrates with the following external services:

• BTCMap.org:

  • Used to fetch Bitcoin-accepting locations worldwide
  • Synchronized hourly using a cron job
  • Provides essential location data, including coordinates and business details

• Overpass API:

  • Used to fetch Bitcoin-accepting locations from OpenStreetMap
  • Synchronized hourly along with BTCMap data
  • Provides additional geographic and point-of-interest data

🛠️ Technologies Used

• Express.js: Web server framework
• SQLite: Database for storing location data
• Node Cron: For scheduling hourly data synchronization
• Axios: For HTTP requests to external APIs
• TypeScript: For type-safe code
• Jest: For testing
• ts-jest: For TypeScript support in Jest

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request for bug fixes, new features, or improvements.

When contributing, please ensure:

1. All tests pass (npm test)
2. New features include appropriate tests
3. Code follows the existing style and conventions