https://github.com/sbaerlocher/savvy

Digital management of customer cards, vouchers, and gift cards with sharing functionality - Progressive Web App with Go + SvelteKit
https://github.com/sbaerlocher/savvy

barcode docker echo echo-framework gift-cards go golang gorm helm kubernetes loyalty-cards offline-first postgresql progressive-web-app pwa svelte sveltekit typescript voucher-management vouchers

Last synced: 4 months ago
JSON representation

Digital management of customer cards, vouchers, and gift cards with sharing functionality - Progressive Web App with Go + SvelteKit

• Host: GitHub
• URL: https://github.com/sbaerlocher/savvy
• Owner: sbaerlocher
• License: mit
• Created: 2026-01-28T22:09:30.000Z (5 months ago)
• Default Branch: main
• Last Pushed: 2026-02-18T22:54:39.000Z (4 months ago)
• Last Synced: 2026-02-19T00:54:49.682Z (4 months ago)
• Topics: barcode, docker, echo, echo-framework, gift-cards, go, golang, gorm, helm, kubernetes, loyalty-cards, offline-first, postgresql, progressive-web-app, pwa, svelte, sveltekit, typescript, voucher-management, vouchers
• Language: Go
• Size: 20.8 MB
• Stars: 0
• Watchers: 0
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE
  • Code of conduct: CODE_OF_CONDUCT.md
  • Codeowners: .github/CODEOWNERS
  • Security: SECURITY.md
  • Support: SUPPORT.md
  • Governance: GOVERNANCE.md
  • Notice: NOTICE
  • Agents: AGENTS.md

Awesome Lists containing this project

README

          
# 🎁 Savvy

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![Go Version](https://img.shields.io/badge/Go-1.23%2B-blue.svg)](https://golang.org/dl/)

[![Node Version](https://img.shields.io/badge/Node-18%2B-green.svg)](https://nodejs.org/)

[![CI Status](https://github.com/sbaerlocher/savvy/workflows/Continuous%20Integration/badge.svg)](https://github.com/sbaerlocher/savvy/actions/workflows/ci.yml)

[![Security Scan](https://github.com/sbaerlocher/savvy/workflows/Security%20Scan/badge.svg)](https://github.com/sbaerlocher/savvy/actions/workflows/security.yml)

[![E2E Tests](https://github.com/sbaerlocher/savvy/workflows/E2E%20Tests/badge.svg)](https://github.com/sbaerlocher/savvy/actions/workflows/e2e.yml)

[![Go Report Card](https://goreportcard.com/badge/github.com/sbaerlocher/savvy)](https://goreportcard.com/report/github.com/sbaerlocher/savvy)

[![codecov](https://codecov.io/gh/sbaerlocher/savvy/branch/main/graph/badge.svg)](https://codecov.io/gh/sbaerlocher/savvy)

> Digital management system for loyalty cards, vouchers, and gift cards with sharing functionality

A modern web-based system for managing loyalty cards, discount vouchers, and prepaid gift cards. Features integrated

barcode scanner, transaction history, and flexible sharing with other users.

## ✨ Features

### 🎴 Loyalty Cards

- Digital storage of loyalty cards and membership cards

- Barcode support (CODE128, QR, EAN13, EAN8)

- Barcode scanning via smartphone/webcam (html5-qrcode)

- Server-side barcode generation (bwip-js)

- Status tracking (Active, Inactive)

- Merchant management with colors and logos

- Merchant filter for quick merchant-based filtering

- Share with other users (with edit permissions)

### 🎟️ Vouchers

- Discount vouchers (percentage, fixed amount, points multiplier)

- Multiple usage models:

  - Single-Use (one-time)

  - One-per-Customer (once per customer)

  - Multiple-Use (multiple times with/without card tracking)

  - Unlimited

- Validity period and minimum order value

- Barcode scanning for quick capture

- Merchant filter for targeted searching

- Sharing (always read-only for shared users)

### 💳 Gift Cards

- Prepaid balance with automatic calculation

- Transaction history (expenses and recharges)

- Optional PIN protection

- Barcode scanning for card numbers

- Merchant filter for organized overview

- Expiration date management

- Share with granular permissions:

  - Edit (modify details)

  - Delete (remove card)

  - Manage transactions (record expenses)

### 👥 Sharing & Permissions

- All three resource types can be shared

- Flexible permissions per share

- Edit/Delete/View permissions for Cards

- Transaction management for Gift Cards

- Overview of shared items in dashboard

- User-specific favorites (shared items can be favorited individually)

- Owner display for shared items ("from [Name]")

### 🔄 Ownership Transfer

- **Complete ownership transfer** for Cards, Vouchers & Gift Cards

- Email-based recipient selection with autocomplete

- Only owner can transfer (Authorization via AuthzService)

- Clean slate approach: All shares are deleted on transfer

- Audit logging for all ownership transfers

- Inline form with warnings before transfer

- Reactive SvelteKit UI without page reload

### 📊 Dashboard

- Statistics (number of Cards/Vouchers/Gift Cards)

- Total balance of all Gift Cards

- ⭐ Favorites system (pinning) - Quick access to frequently used items

- Recently added items (when no favorites available)

- Quick access to create new items

- Mobile-optimized view (favorites before statistics)

### 🔍 Search & Filter

- Full-text search by merchant/code

- Filter by owner (Mine / All)

- Filter by status (Active / Expired)

- Sort by merchant or date

- Client-side filtering (Svelte reactive statements) for fast results

### 📱 Progressive Web App (PWA)

- ✅ **Installable**: Can be installed as app on iOS/Android/Desktop

- ✅ **Offline-first**: Automatic warmup cache for instant offline support

- ✅ **Custom Service Worker**: NetworkFirst strategy with Workbox Recipes

- ✅ **Offline detection**: Visual feedback for network issues

- ✅ **Automatic updates**: Service worker updates transparently in background

- ✅ **Zero 500 errors**: Cache fallback prevents offline errors

**Offline features**:

- ✅ View cards/vouchers/gift cards (automatically cached on Service Worker install)

- ✅ Display barcode details

- ✅ Filter & sort (client-side)

- ✅ Browse favorites

- ✅ Dashboard statistics (automatically cached)

- ❌ Create/edit/delete items (online only)

- ❌ Share management (online only)

### 🔔 Notifications

- In-app notification system for shares and transfers

- Real-time notifications when items are shared with you

- Permission change alerts for shared resources

- Ownership transfer notifications

- Mark as read/unread functionality

- Delete individual or all notifications

- Automatic notification generation via service layer

### 🌍 Internationalization

- **Multi-language support**: German (DE), English (EN), French (FR)

- Language switcher in navigation

- Fully translated UI including forms, buttons, and messages

- SvelteKit i18n store with reactive language switching

- Persistent language preference (localStorage)

- Date and number localization per language

### 🔐 Authentication & Authorization

- **OAuth/OIDC**: Provider-agnostic authentication (Google, Microsoft, etc.)

- **Local Authentication**: Email/Password with bcrypt hashing

- Session-based authentication with Gorilla Sessions

- **AuthzService**: Centralized authorization logic for all resources

- Granular permission checks (view, edit, delete, manage transactions)

- User impersonation for admin debugging

- Secure session management with CSRF protection

### 🎛️ Feature Toggles

- **Environment-based feature flags** for flexible deployment:

  - `ENABLE_CARDS` - Enable/disable loyalty cards feature

  - `ENABLE_VOUCHERS` - Enable/disable vouchers feature

  - `ENABLE_GIFT_CARDS` - Enable/disable gift cards feature

  - `ENABLE_LOCAL_LOGIN` - Enable/disable email/password authentication

  - `ENABLE_REGISTRATION` - Enable/disable user self-registration

- Runtime configuration via `/api/v1/config` endpoint

- Client-side feature detection (SvelteKit reads config on startup)

- Middleware-based feature enforcement

### 📝 Audit Logging

- **Automatic logging** of all delete operations

- Comprehensive audit trail with:

  - User ID, action type, resource type/ID

  - JSONB snapshot of deleted resource

  - IP address and user agent

  - Timestamp with timezone

- Admin panel access to audit logs

- Retention policy support

- Compliance-ready audit trail

### 📊 Observability & Monitoring

- **Prometheus Metrics** (`/metrics` endpoint):

  - HTTP request duration and counts

  - Resource counts (cards, vouchers, gift cards, users)

  - Active sessions and database connections

- **Health Checks**:

  - `/health` - Liveness probe (server running)

  - `/ready` - Readiness probe (database connectivity)

- **Structured Logging**: JSON logs with slog

- **OpenTelemetry**: Optional distributed tracing (OTEL_ENABLED)

- Performance monitoring (N+1 query prevention, database triggers)

### 👨‍💼 Admin Panel

- **User Management**: View and manage all users

- **Resource Overview**: Access to all cards/vouchers/gift cards

- **Audit Log Viewer**: Review deletion history

- **Resource Restoration**: Recover soft-deleted items

- **User Impersonation**: Debug user-specific issues

- **Statistics Dashboard**: System-wide metrics

- Role-based access control (admin-only features)

## 🚀 Quick Start

### Prerequisites

- Docker & Docker Compose

- Make (optional, for Makefile shortcuts)

### Installation & Start

```bash

# 1. Clone repository

git clone 

cd savvy

# 2. Configure environment variables

cp .env.example .env

# Edit .env with your settings

# 3. Start Docker containers (automatically builds everything)

make dev

# 4. Load test data (optional, in another terminal)

make seed

```

**Application URL**: 

> **Note**: Local development without Docker is **not supported** due to Vite proxy requirements.

> The Vite dev server requires access to `http://api:8080` which only works in the Docker network.

> See [DEVELOPMENT.md](DEVELOPMENT.md) for details.

### Test Users

After seeding, the following test accounts are available (password: `test123`):

| Email                        | Role  | Description                  |

| ---------------------------- | ----- | ---------------------------- |

| `admin@example.com`          | Admin | Has admin rights + own items |

| `anna.mueller@example.com`   | User  | Has access to shared items   |

| `thomas.schmidt@example.com` | User  | Has access to shared items   |

| `maria.garcia@example.com`   | User  | Has own items                |

## 💻 Development

### Local Development Environment

**IMPORTANT**: Always use Docker for development!

```bash

# ✅ RECOMMENDED: Start with Makefile (includes Hot Reload)

make dev

# This starts:

# - PostgreSQL (port 5432)

# - Go API with Air Hot Reload (port 8080)

# - Vite Dev Server with HMR (port 5173)

```

#### Why Docker?

- ✅ Consistent development environment

- ✅ Vite proxy only works in Docker network (`http://api:8080`)

- ✅ Air and Vite HMR work automatically

- ✅ No manual port configurations

- ✅ All dependencies bundled (PostgreSQL, Go, Node.js)

See [DEVELOPMENT.md](DEVELOPMENT.md) for details.

### Makefile Commands

```bash

# Development (Docker-based)

make dev         # Start Docker development (alias for make up)

make up          # Start Docker containers with hot reload

make down        # Stop Docker containers

make restart     # Restart containers

make rebuild     # Rebuild containers

make logs        # View API logs

make logs-all    # View all container logs

# Database (runs in Docker)

make migrate-up     # Apply migrations

make migrate-down   # Rollback migration

make migrate-status # Check migration status

make seed           # Seed test data

make db-shell       # PostgreSQL shell

# Testing & Build

make test        # Run all tests

make test-core   # Run core tests (services + models)

make build       # Build binary with embedded client

# Container Access

make shell       # Application shell

```

### Code Changes

**All changes are automatically detected in Docker containers:**

```bash

# Start Docker development environment

make dev  # or: make up

# This provides automatic hot reload for:

# - SvelteKit Frontend: Vite HMR detects changes in client/src/

# - Go Backend: Air reloads on changes in internal/

# - Database: GORM AutoMigrate runs on server start

```

**File locations:**

- **Frontend**: `client/src/` - SvelteKit components, stores, API clients

- **Backend**: `internal/` - Go handlers, services, repositories

- **Database Models**: `internal/models/` - GORM models

- **API Endpoints**: `internal/handlers/api/` - JSON API handlers

**Important**: Always use Docker (`make dev`) - local npm/air commands won't work due to network requirements.

## 📁 Project Structure

```

savvy/

├── cmd/                  # Application entrypoints

│   ├── server/           # Main application server

│   ├── seed/             # Database seeding script

│   ├── migrate/          # Database migration tool

│   ├── release-tool/     # Release version synchronization

│   └── e2e/              # E2E test server setup

│

├── internal/

│   ├── setup/            # Server initialization│   │   ├── dependencies.go # DI container, database, telemetry

│   │   ├── routes.go     # Route registration

│   │   └── server.go     # Echo configuration

│   ├── config/           # Configuration management

│   ├── database/         # Database connection & utilities

│   ├── handlers/         # HTTP handlers (Controllers)

│   │   ├── api/          # JSON API handlers│   │   │   ├── cards.go    # Cards API

│   │   │   ├── vouchers.go # Vouchers API

│   │   │   ├── gift_cards.go # Gift Cards API

│   │   │   ├── notifications.go # Notifications API

│   │   │   ├── dto.go      # Data Transfer Objects

│   │   │   └── mappers.go  # Model ↔ DTO mapping

│   │   ├── shares/       # Share handler abstraction

│   │   ├── health.go     # Health checks

│   │   ├── oauth.go      # OAuth/OIDC handlers

│   │   └── spa.go        # SvelteKit SPA fallback

│   ├── services/         # Business logic layer

│   │   ├── card_service.go

│   │   ├── voucher_service.go

│   │   ├── gift_card_service.go

│   │   ├── notification_service.go

│   │   ├── transfer_service.go

│   │   ├── authz_service.go

│   │   └── container.go  # Service DI container

│   ├── repository/       # Data access layer (GORM)

│   ├── models/           # GORM models

│   │   ├── user.go

│   │   ├── merchant.go

│   │   ├── notification.go│   │   ├── card.go / voucher.go / gift_card.go

│   │   └── *_share.go    # Sharing models

│   ├── middleware/       # HTTP middleware

│   │   ├── auth.go       # Authentication

│   │   ├── cors.go       # CORS configuration

│   │   ├── csrf*.go      # CSRF protection

│   │   ├── security.go   # Security headers

│   │   └── ...           # Other middleware

│   ├── migrations/       # Database migrations (embedded)

│   ├── mocks/            # Generated mocks for testing (mockery)

│   ├── audit/            # Audit logging

│   ├── metrics/          # Prometheus metrics

│   ├── telemetry/        # OpenTelemetry integration

│   ├── oauth/            # OAuth/OIDC implementation

│   ├── security/         # Security utilities

│   ├── i18n/             # Internationalization

│   ├── validation/       # Input validation

│   ├── debug/            # Debug utilities

│   └── assets/           # Embedded client build

│       └── client/       # SvelteKit build output

│

├── client/               # SvelteKit Frontend│   ├── src/

│   │   ├── routes/       # SvelteKit pages

│   │   │   ├── +page.svelte       # Dashboard

│   │   │   ├── cards/             # Cards routes

│   │   │   ├── vouchers/          # Vouchers routes

│   │   │   ├── gift-cards/        # Gift cards routes

│   │   │   └── admin/             # Admin panel

│   │   ├── lib/

│   │   │   ├── components/        # Reusable Svelte components

│   │   │   ├── api/               # API client modules

│   │   │   ├── stores/            # Svelte stores (auth, offline, i18n)

│   │   │   ├── utils/             # Helper functions

│   │   │   ├── i18n/              # Translations (DE, EN, FR)

│   │   │   └── types/             # TypeScript types

│   │   ├── tests/        # E2E tests (Playwright)

│   │   ├── hooks.client.ts # SvelteKit client hooks

│   │   └── app.html      # HTML template

│   ├── static/           # Static assets (favicon, etc.)

│   ├── vite.config.ts    # Vite configuration

│   ├── playwright.config.ts # Playwright E2E test config

│   ├── package.json      # Node.js dependencies

│   └── tsconfig.json     # TypeScript config

│

├── deploy/               # Deployment configurations

│   ├── helm/             # Helm charts for Kubernetes

│   ├── kustomize/        # Kustomize overlays

│   ├── grafana/          # Grafana dashboards

│   └── observability/    # Observability stack (Prometheus, Loki)

│

├── .air.toml            # Hot reload config (Air)

├── .golangci.yml        # Go linter configuration

├── .revive.toml         # Revive linter configuration

├── .mockery.yaml        # Mock generation config

├── .goreleaser.yaml     # Release automation config

├── docker-compose.yml   # Docker services (dev)

├── Dockerfile           # Multi-stage build

├── Makefile             # Development commands

├── go.mod / go.sum      # Go dependencies

├── CODE_OF_CONDUCT.md   # Community guidelines

├── OBSERVABILITY.md     # Observability guide

└── README.md            # This file

```

## 🛠️ Tech Stack

### Core Stack

| Component              | Technology                  | Version | Purpose                       |

| ---------------------- | --------------------------- | ------- | ----------------------------- |

| **Backend Framework**  | Echo                        | v4.15   | HTTP Router & Middleware      |

| **ORM**                | GORM                        | v1.31   | PostgreSQL Abstraction        |

| **Frontend**           | SvelteKit + TypeScript      | 2.51    | Modern SPA Framework          |

| **Build Tool**         | Vite                        | 7.3     | Fast Build & Dev Server       |

| **Styling**            | TailwindCSS                 | 4.1     | Utility-First CSS             |

| **Database**           | PostgreSQL                  | 16      | Primary Data Store            |

| **Language**           | Go                          | 1.26    | Backend Language              |

| **Language**           | TypeScript                  | 5.9     | Frontend Language             |

### Features & Libraries

| Feature                | Technology                  | Purpose                       |

| ---------------------- | --------------------------- | ----------------------------- |

| **Auth (Sessions)**    | Gorilla Sessions            | Session-based Authentication  |

| **Auth (OAuth/OIDC)**  | go-oidc                     | OpenID Connect Provider       |

| **Barcode Scanning**   | @undecaf/zbar-wasm          | WebAssembly Barcode Scanner   |

| **Barcode Generation** | bwip-js                     | Server-side Barcode Rendering |

| **Validation**         | go-playground/validator     | Input Validation              |

| **i18n**               | go-i18n                     | Internationalization          |

| **Metrics**            | Prometheus                  | Application Metrics           |

| **Tracing**            | OpenTelemetry               | Distributed Tracing           |

| **PWA**                | @vite-pwa/sveltekit         | Service Worker & Offline      |

| **Service Worker**     | Workbox                     | Caching & Offline Strategies  |

### Development & Testing

| Tool                   | Technology                  | Purpose                       |

| ---------------------- | --------------------------- | ----------------------------- |

| **Hot Reload (Go)**    | Air                         | Go Auto-Reload                |

| **Hot Reload (Vite)**  | Vite HMR                    | Frontend Hot Module Replace   |

| **Unit Testing (Go)**  | testify                     | Go Test Assertions            |

| **Unit Testing (JS)**  | Vitest                      | Frontend Unit Tests           |

| **E2E Testing**        | Playwright                  | End-to-End Browser Tests      |

| **Mocking**            | Mockery                     | Mock Generation for Tests     |

| **Linting (Go)**       | golangci-lint + revive      | Go Code Quality               |

| **Linting (TS)**       | svelte-check                | TypeScript/Svelte Validation  |

## 🗄️ Database

The application uses **PostgreSQL** with 12 main tables for users, merchants, cards, vouchers,

gift cards, sharing, favorites, notifications, and audit logs.

**For detailed database schema, ERD diagram, and table descriptions, see:**

📖 [ARCHITECTURE.md - Database Schema](ARCHITECTURE.md#️-database-schema)

## 🔐 Security

- ✅ Bcrypt password hashing

- ✅ Session-based authentication

- ✅ CSRF protection (Echo middleware)

- ✅ SQL injection protection (GORM parameterized queries)

- ✅ XSS protection (SvelteKit auto-escaping)

- ✅ UUID instead of integer IDs

- ✅ Granular permissions for sharing

See [SECURITY.md](SECURITY.md) for complete security policy and vulnerability reporting.

## 🚀 Deployment

The application is designed for **containerized deployment** with Traefik reverse proxy for

production use. Supports Docker Compose and Kubernetes (K3s/K8s).

**Production Architecture**:

```

Client (HTTPS) → Traefik (TLS) → Savvy (HTTP:8080) → PostgreSQL

```

**For detailed deployment instructions, environment variables, Traefik configuration,

and Kubernetes manifests, see:**

📖 [OPERATIONS.md - Deployment Guide](OPERATIONS.md)

## 🧪 Testing

### Backend Tests (Go)

```bash

# Run all tests

make test

# Run core tests (services + models)

make test-core

# Run tests with coverage report

make test-coverage

# Run specific test (direct go test)

go test ./internal/models -run TestCard_GetColor

# Run tests with race detection

go test -race ./...

```

**Coverage**: 57.8% (Services), 54.1% (Handlers/API), 100.0% (Models), 97.2% (Repositories)

### Frontend Tests (Vitest)

```bash

cd client

# Run unit tests

npm test

# Run tests with UI

npm run test:ui

# Run tests with coverage

npm run test:coverage

```

**Coverage**: 32.8% unit test coverage (19 tests, stores and utils)

### E2E Tests (Playwright)

```bash

cd client

# Install Playwright browsers

npm run playwright:install

# Run all E2E tests

npm run test:e2e

# Run tests in UI mode (interactive)

npm run test:e2e:ui

# Run tests with visible browser

npm run test:e2e:headed

# Run on specific browser

npm run test:e2e:chromium

# View test report

npm run playwright:report

```

**Coverage**: 75 E2E tests across 13 test suites covering authentication, CRUD operations, sharing,

favorites, notifications, and admin panel.

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:

- Contribution guidelines

- Development setup

- Code style requirements

- Pull request process

- Testing requirements

## 📝 Changelog

See [CHANGELOG.md](CHANGELOG.md) for full release history and breaking changes.

## 📚 Documentation

### For Users

- **[README.md](README.md)** - This file: Quick Start, Features, Installation

- **[SUPPORT.md](SUPPORT.md)** - Support resources, FAQ, Troubleshooting

- **[SECURITY.md](SECURITY.md)** - Security policy, vulnerability reporting

- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** - Community guidelines, code of conduct

### For Developers

- **[CONTRIBUTING.md](CONTRIBUTING.md)** - Contribution guidelines, code style, PR process

- **[AGENTS.md](AGENTS.md)** - AI agent documentation, offline architecture, cache validation

- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design, database schema, clean architecture, PWA

- **[OPERATIONS.md](OPERATIONS.md)** - Deployment (Traefik/K8s), monitoring, audit logging

- **[OBSERVABILITY.md](OBSERVABILITY.md)** - Observability stack, Prometheus, Grafana, Loki

- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Docker development, Air hot reload, best practices

- **[RELEASE.md](RELEASE.md)** - Release process and versioning

### Project Management

- **[GOVERNANCE.md](GOVERNANCE.md)** - Project governance model, decision-making

- **[CHANGELOG.md](CHANGELOG.md)** - Release history and breaking changes

- **[LICENSE](LICENSE)** - MIT License

- **[NOTICE](NOTICE)** - Third-party software notices

### Technical Details

- **[internal/migrations/migrations.go](internal/migrations/migrations.go)** - Database migrations (embedded)

## 📧 Support

Need help? We have various support channels:

- **[SUPPORT.md](SUPPORT.md)** - Complete support guide with FAQ and troubleshooting

- **GitHub Discussions** - Community Q&A and discussions

- **GitHub Issues** - Bug reports and feature requests (use templates!)

- **Security Issues** -  (NEVER report publicly!)

See also: **[CONTRIBUTING.md](CONTRIBUTING.md)** for contribution guidelines

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Built with** Go + Echo + SvelteKit + TypeScript + TailwindCSS

**Deployed with** Docker + PostgreSQL (Traefik recommended for production)