Points Tax Calculator API

Author: André Lacasse

Welcome to the Points Tax Calculator API! I've been working for a few years as a python dev but I never had the chance to start a project from scratch. So this is a first and in any cases, I thank you for the opportunity, it was fun. I used the opportunity to try to use newer libraries and to better myself at knowing how to plug the different pieces of a project. I wanted as much as possible to start it like a real world project. I’m proud of the result and hope you find it interesting.

Features

• Flask-based REST API
• Interactive Swagger UI documentation
• Redis caching for tax bracket data
• Asynchronous HTTP calls with HTTPX
• Comprehensive testing with pytest and plugins
• Containerized development and testing with Docker

Quickstart

1. Clone the repository and navigate into it:

   git clone [email protected]:alacasse/points-test.git
   cd points-test/

2. Configure the tax service URL in docker-compose.yml:

   environment:
     TAX_SERVICE_URL: http://host.docker.internal:5001/tax-calculator

3. Start the application:

   make start

4. Browse the API docs at http://localhost:5000/api/docs.

Running Tests

make tests

Viewing Logs

make logs

Configuration

Variable	Description
FLASK_ENV	development or testing; toggles debug mode and error pages
REDIS_URL	URL for the Redis instance (e.g. redis://redis:6379/0)
USE_REDIS	true/false to enable or disable caching in the tax service
TAX_SERVICE_URL	Base URL of the external tax calculation API
TAX_SERVICE_TIMEOUT	Initial timeout (seconds) for external API calls
TAX_SERVICE_TIMEOUT_INCREASE_FACTOR	Multiplier to increase timeout after each retry
TAX_SERVICE_TIMEOUT_RETRY_AMOUNT	Number of retry attempts before giving up on the external service

Note: REDIS is enabled by default. To test logging and error handling without caching, set USE_REDIS=false.

Technology Choices

Gunicorn

A lightweight, pre-forking WSGI HTTP server used in production to manage multiple worker processes for handling requests.

Swagger

A framework around the OpenAPI spec that provides interactive API documentation and code generation tools.

Flask

A micro web framework that’s simple to use and ideal for small to medium APIs.

Flasgger

A Flask extension that allows annotating routes with OpenAPI specs (YAML or docstrings) and serves a Swagger UI automatically.

Redis

Used to cache external tax bracket data (which is static and occasionally unreliable) with a 24‑hour TTL, reducing flakiness and latency.

HTTPX

An async-capable HTTP client library that supports HTTP/1.1 and HTTP/2, chosen for its modern API and performance.

pytest

A powerful testing tool with a simple syntax, along with plugins:

• pytest-flask: simplifies Flask app testing (test client, context).
• pytest-asyncio: enables testing of async functions.

Makefile

Convenience commands (make start, make tests, make logs) for a smooth developer experience.

Additional Notes

Containerized Testing

Tests run inside Docker to guarantee the same environment as production and avoid discrepancies between local venvs and containerized deployments.

Build and Test Speed

To speed up builds:

• Added a .dockerignore.

• Enabled BuildKit and Compose v2 bake via .env variables:

  DOCKER_BUILDKIT=1
  COMPOSE_BAKE=1

Caveats

• Bracket-level taxes may not sum exactly to the total due to rounding.
• Redis is disabled during unit tests; Redis-specific tests are TODO.
• More edge-case tests could be added.