🎁 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

# 1. Clone repository
git clone <repository-url>
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: http://localhost:8080

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 for details.

Test Users

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

💻 Development

Local Development Environment

IMPORTANT: Always use Docker for development!

# ✅ 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 for details.

Makefile Commands

# 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:

# 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

Features & Libraries

Development & Testing

🗄️ 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

🔐 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 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

🧪 Testing

Backend Tests (Go)

# 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)

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)

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 for:

• Contribution guidelines
• Development setup
• Code style requirements
• Pull request process
• Testing requirements

📝 Changelog

See CHANGELOG.md for full release history and breaking changes.

📚 Documentation

For Users

• README.md - This file: Quick Start, Features, Installation
• SUPPORT.md - Support resources, FAQ, Troubleshooting
• SECURITY.md - Security policy, vulnerability reporting
• CODE_OF_CONDUCT.md - Community guidelines, code of conduct

For Developers

• CONTRIBUTING.md - Contribution guidelines, code style, PR process
• AGENTS.md - AI agent documentation, offline architecture, cache validation
• ARCHITECTURE.md - System design, database schema, clean architecture, PWA
• OPERATIONS.md - Deployment (Traefik/K8s), monitoring, audit logging
• OBSERVABILITY.md - Observability stack, Prometheus, Grafana, Loki
• DEVELOPMENT.md - Docker development, Air hot reload, best practices
• RELEASE.md - Release process and versioning

Project Management

• GOVERNANCE.md - Project governance model, decision-making
• CHANGELOG.md - Release history and breaking changes
• LICENSE - MIT License
• NOTICE - Third-party software notices

Technical Details

• internal/migrations/migrations.go - Database migrations (embedded)

📧 Support

Need help? We have various support channels:

• 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 - security@sbaerlo.ch (NEVER report publicly!)

See also: CONTRIBUTING.md for contribution guidelines

📄 License

MIT License - see LICENSE file for details.

Built with Go + Echo + SvelteKit + TypeScript + TailwindCSS

Deployed with Docker + PostgreSQL (Traefik recommended for production)