loyalty-card

README

Loyalty Card Service

---

Table of Contents

• Loyalty Card Service
  • Table of Contents
  • Overview
  • Demo & API Docs
  • Features
  • Getting Started
    • Prerequisites
    • Quickstart (Docker Compose)
    • Manual Setup (Go)
    • Environment Variables
  • Usage
    • API Endpoints
      • Guests
      • Scores
      • Tags
    • Example: Create a Guest
    • API Documentation
  • Development
    • Makefile Commands
    • Running Tests
    • Contributing
  • Tech Stack
  • License
  • Contact & Community
  • Acknowledgements

---

Overview

Loyalty Card is a modern, open-source RESTful service for managing loyalty programs, guests, scores, and tags. Built with Go, Fiber, and GORM, it offers a robust API, modular architecture, and full Docker support. Ideal for businesses, developers, and open-source contributors looking for a scalable and extensible loyalty management backend.

---

Demo & API Docs

• Swagger/OpenAPI Documentation: View API Docs
• Live Swagger UI: /api/v1/swagger/index.html (when running the service)

---

Features

• RESTful API for managing guests, scores, and tags
• Modular Go codebase with clear separation of concerns
• CLI support via Cobra
• OpenAPI/Swagger auto-generated documentation
• Dockerized for easy deployment
• Makefile for streamlined development workflows
• Environment-based configuration
• PostgreSQL & SQLite support via GORM
• Extensible and open for contributions

---

Getting Started

Prerequisites

• Go 1.18+
• Docker & Docker Compose

Quickstart (Docker Compose)

git clone https://github.com/patricksferraz/loyalty-card.git
cd loyalty-card
cp .env.example .env
# Edit .env as needed (set REST_PORT, DB_DEBUG, DSN)
docker-compose up -d

Manual Setup (Go)

git clone https://github.com/patricksferraz/loyalty-card.git
cd loyalty-card
cp .env.example .env
# Edit .env as needed
go mod tidy
go run main.go

Environment Variables

See .env.example:

• REST_PORT - Port for REST API
• DB_DEBUG - Enable DB debug logs
• DSN - Database connection string

---

Usage

API Endpoints

All endpoints are prefixed with /api/v1.

Guests

• POST /guests - Create a new guest
• GET /guests/{guest_id} - Retrieve guest by ID

Scores

• POST /scores - Create a new score
• GET /scores/{score_id} - Retrieve score by ID
• POST /scores/{score_id}/use - Use a score
• POST /scores/{score_id}/tags - Add a tag to a score

Tags

• POST /tags - Create a new tag
• GET /tags - Search tags
• GET /tags/{tag_id} - Retrieve tag by ID

Example: Create a Guest

curl -X POST http://localhost:<REST_PORT>/api/v1/guests \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "doc": "123456789"}'

API Documentation

• Swagger YAML
• Swagger JSON
• Live Swagger UI: http://localhost:<REST_PORT>/api/v1/swagger/index.html

---

Development

Makefile Commands

• make build - Build Docker image
• make up - Start services (Docker Compose)
• make down - Stop and remove containers
• make logs - Tail logs
• make gtest - Run Go tests with coverage
• make attach - Open shell in running container

Running Tests

make gtest

Contributing

Contributions are welcome! Please open issues or submit pull requests. For major changes, open a discussion first.

---

Tech Stack

• Language: Go 1.18+
• Web Framework: Fiber
• ORM: GORM
• CLI: Cobra
• API Docs: Swagger/OpenAPI
• Containerization: Docker, Docker Compose
• Database: PostgreSQL, SQLite

---

License

This project is licensed under the GNU GPLv3.

---

Contact & Community

• Author: Patrick Ferraz
• Email: patrick.ferraz@coding4u.tech
• GitHub Issues: Report bugs or request features
• Discussions: Join the conversation

---

Acknowledgements

• Fiber
• GORM
• Cobra
• Swagger
• Docker
• Open-source community

Documentation

Overview

Copyright © 2022 Patrick Ferraz <patrick.ferraz@coding4u.tech>