FizzBuzz API

REST API that generates customizable FizzBuzz sequences and tracks request statistics.

Endpoints

• POST /api/v1/fizzbuzz - Generate FizzBuzz sequence
• GET /api/v1/statistics - Get most frequent request
• GET /health - Health check
• POST /api/v1/_qa/statistics/reset - Reset statistics (development only)

See openapi.yaml for full API specification.

Quick Start

make run

make tests

make test-e2e

make bench

make lint

Deployment

The project is deployed on my personal kubernetes cluster:

• prod: https://fizzbuzz.erwanleboucher.dev
• staging: https://fizzbuzz-staging.erwanleboucher.dev

The deployment is done via fluxcd monitoring the main branch of my homalab GitHub repository. https://github.com/eleboucher/mediaserver/tree/main/kubernetes/apps/selfhosted/fizzbuzz

Architecture

This application follows Hexagonal Architecture (Ports & Adapters) principles:

Layers:

• Domain: Pure business logic, no dependencies on frameworks
• Service: Orchestrates domain logic and coordinates with repositories
• Handlers: HTTP adapters that call services (not repositories directly)
• Repository: Data persistence adapters implementing storage ports

Observability

The application includes OTel Go auto-instrumentation sidecar using eBPF for zero-code tracing

When running with Docker Compose, all HTTP requests are automatically traced with:

• Request/response details
• Error tracking
• Performance metrics

Configuration

Environment variables:

• PORT - Server port (default: 8080)
• ENVIRONMENT - Environment mode (default: development)
• LOG_LEVEL - Log level: DEBUG, INFO, WARN, ERROR (default: INFO)
• OTEL_EXPORTER_OTLP_ENDPOINT - OpenTelemetry collector endpoint (optional)
• OTEL_SERVICE_NAME - Service name for traces (optional)