Hunting Incident API

This repository contains the backend API for the hunting incident management system.

🚀 Quick Start

Prerequisites

• Go 1.23 or higher
• Docker and Docker Compose
• PostgreSQL (if running locally)

Development with Docker (Recommended)

1. Start all services (API, PostgreSQL, Redis, Mailpit):

make up

The API will be available at http://localhost:8080

2. Stop all services:

make down

3. Clear database data (if needed):

make clear-db-data

Local Development

1. Install Go dependencies:

go mod download

2. Set up environment variables:

export HUNTING_INCIDENTS_DB_HOST=localhost
export HUNTING_INCIDENTS_DB_PASSWORD=postgres
# Add other required environment variables

3. Start PostgreSQL and Redis services:

docker compose up postgres redis mailpit

4. Run the API:

go run main.go

Build

To build the Docker image:

make build

🛠️ Tech Stack

Core Framework

• Go 1.23 - Modern Go with latest features
• HTTP Server - Custom HTTP server with timeouts and graceful shutdown
• PostgreSQL - Primary database with PostGIS extension for geospatial data
• Redis - Caching and session storage
• Docker - Containerized deployment

Libraries & Tools

• pgx/v5 - High-performance PostgreSQL driver
• Viper - Configuration management
• golang-migrate - Database migration management
• Mailpit - Email testing in development

Architecture

• Clean Architecture - Organized by domain (incidents, users, configs)
• Repository Pattern - Data access abstraction
• Controller Pattern - HTTP request handling
• DTO Pattern - Data transfer objects for API contracts

🐳 Services

The application runs with the following services:

• API (:8080) - Main application server
• PostgreSQL (:5432) - Database with PostGIS extension
• Redis (:6379) - Caching layer
• Mailpit (:8025, :1025) - Email testing interface

🔧 Environment Variables

Variable	Description	Default
HUNTING_INCIDENTS_DB_HOST	Database host	localhost
HUNTING_INCIDENTS_DB_PASSWORD	Database password	postgres
POSTGRES_USER	PostgreSQL username	postgres
POSTGRES_PASSWORD	PostgreSQL password	postgres
POSTGRES_DB	PostgreSQL database name	postgres

🗄️ API Endpoints

The API provides endpoints for:

• Incidents - Hunting incident management
• Users - User authentication and management
• Configs - Application configuration
• Health - Health check endpoint (/health)

Database migration

golang-migrate

Database migration files use golang-migrate. This tools allow:

• migration from source code
• manual migration

Migration files

Database migration files are located in ./database/migrations.

To create a new migration version, run migrate create -ext sql -dir database/migrations -seq <migration_name>.

Dirty migration version

When a migraiton fail, the version number will be updated and the dirty flag set to true. Consecutive migration will fail until a migration is run using the -force flag or the dirty flag is set to false un database

Best practice

To preserve data intergrity, here are a set of rule one should follow:

• new database version should stay backward compatible (don't delete column, change types, etc)
• new database version must keep existing data
• migration script should be run in transaction. This ensure that either all or no change are performed
• migration down must return to previous state

Town data

If you need to load towns data, clone the doc repository, then run the following command to copy town data to database:

psql -h localhost -p 5432 -d postgres -U postgres \
    -c "\copy towns from PROGRAM 'doc/database/processed_town.csv' with delimiter as ',' CSV HEADER"