VoucherVault

VoucherVault is a Django‑based web application designed to digitize and manage vouchers, coupons, loyalty cards, and gift cards. From a developer’s perspective, the core of the system is a RESTful API that exposes CRUD operations for items, categories, and transaction logs, while the front‑end is a lightweight, mobile‑optimised portal built with Django’s templating engine and minimal JavaScript. The application is intentionally lightweight, supporting both SQLite3 for simple deployments and PostgreSQL for production workloads, making it straightforward to integrate into existing database ecosystems.

Architecture & Technical Stack

• Framework: Django 4.x, leveraging its built‑in authentication, admin panel, and ORM.
• Languages: Python 3.11 for the backend; HTML/CSS/JavaScript (ES6) for the front‑end.
• Database: SQLite3 (default) or PostgreSQL; migrations are managed via Django’s migration system.
• Containerization: Official Docker image (l4rm4nd/vouchervault) with volumes for persistent storage and optional docker-compose snippets in the repo.
• Background Tasks: Celery is not used; instead, scheduled expiry notifications are handled by Django’s cron integration through the django-crontab package.
• External Services: Apprise for cross‑platform notifications, OIDC libraries for SSO, and QR/barcode generation via qrcode and python-barcode.

The application follows a modular Django app structure: separate apps for vouchers, users, notifications, and API. Each module encapsulates its own models, serializers (using Django REST Framework), and views, allowing developers to extend or replace components without touching the core.

Core Capabilities & APIs

• Voucher CRUD: Create, read, update, delete items with fields for code, type, expiry, and media uploads.
• Barcode/QR Rendering: Server‑side generation of 1D/2D codes on demand; the API can return a PNG or SVG.
• Scanning Integration: Client‑side JavaScript reads QR/Barcode using the device camera and auto‑detects code type for item creation.
• Transaction Logging: For gift cards, every redemption is recorded with timestamp, amount, and user.
• Multi‑tenant Support: All data is scoped to the authenticated user; sharing between users is possible via a many‑to‑many relation.
• Internationalization: Built‑in Django i18n with translations for English, German, French, and Italian.
• REST Endpoints: /api/v1/items/, /api/v1/transactions/, and a statistics endpoint for Home Assistant integration.
• Webhooks: The API can be extended to expose webhook endpoints for external services; the repo includes a skeleton for incoming webhook handling.

Deployment & Infrastructure

VoucherVault is designed for self‑hosting on a range of platforms:

• Docker Compose: A single docker-compose.yml can spin up the app with PostgreSQL, Redis (optional for caching), and a reverse‑proxy.
• Unraid & NAS: The repository contains a dedicated wiki page for Unraid installations, illustrating how to map volumes and set permissions.
• Scalability: While the default setup runs a single Django process, it can be scaled horizontally behind a load balancer. The stateless nature of the API and use of a shared database make this straightforward.
• Persistent Storage: Media uploads are stored on a Docker volume; the database is also persisted in a dedicated directory.
• Security: The project uses bandit for static analysis, and the Docker image is built from a minimal Python base to reduce attack surface.

Integration & Extensibility

• Plugin System: Developers can add new voucher types by creating a Django app that registers a model and serializer; the admin panel auto‑detects new models.
• APIs & SDK: The REST API follows standard conventions; authentication is handled via token or session cookies, and documentation can be generated with Swagger/OpenAPI.
• Webhooks & Callbacks: External services (e.g., e‑commerce platforms) can push voucher data to VoucherVault via POST requests; the app can also emit events when a voucher is redeemed.
• Custom Themes: The front‑end uses Bootstrap 5, allowing developers to override CSS or swap themes without touching the core logic.

Developer Experience

• Documentation: The README and wiki provide clear guidance on installation, configuration, and API usage. Code comments are concise, and the project follows PEP8 conventions.
• Community & Support: The repo has an active contributors list and issue tracker. Licensing is permissive (MIT), encouraging internal use or commercial deployment.
• Testing: Unit tests cover models, serializers, and views; the test suite can be run with pytest or Django’s manage.py test.

Use Cases

1. Small Business Loyalty Management – A boutique can host VoucherVault to issue digital loyalty cards, track redemptions, and push expiry alerts via Apprise.
2. E‑commerce Integration – Developers can expose the REST API to a Shopify or WooCommerce store, allowing customers to view and redeem vouchers directly in their checkout flow.
3. Personal Gift Card Repository – Individuals can run the app on a Raspberry Pi or NAS to keep all gift cards in one place, with QR codes for quick scanning at stores.
4. Home Assistant Dashboard – The statistics