Revel Backend

An open-source event management, ticketing and membership platform for communities, clubs and independent venues.

---

🔗 Related Repositories

This repository contains the backend API and business logic for Revel. The complete platform consists of:

• revel-backend (this repository) - Django Ninja REST API, business logic, database models
• revel-frontend - SvelteKit web application, user interface
• infra - Docker Compose setup, reverse proxy, observability stack, deployment configurations

---

Revel is an event management and ticketing platform designed with community at its heart. Initially created to serve the specific needs of queer, LGBTQ+, and sex-positive communities, it is built to be event-agnostic, scalable, and a powerful tool for any group that values privacy, control, and transparency. It works just as well for a gym, a yoga studio, a dance school or a choir: sell monthly or annual memberships, run members-only classes with a plain RSVP, sell a pass for a whole series, and put the membership card in your members' wallets.

Unlike monolithic, corporate platforms that treat events as transactions, Revel treats them as part of a larger community ecosystem.

---

🤖 AI disclosure: Revel makes use of AI-assisted coding, but stays firmly away from vibe coding. Every line that lands in main is understood, reviewed, and defended by a human. If you contribute with AI, follow the workflow in AI_USAGE.md.

---

✨ Live Demo

You can try out an early version of Revel yourself at https://demo.letsrevel.io

The api lives at https://demo-api.letsrevel.io/api/docs

NOTE: Emails are dry, and the data is reset every day at 00:00 CET.

More info on what's available here.

---

🤔 Why Revel? The Philosophy

Revel is being built to address the shortcomings of existing event platforms, especially for communities that prioritize safety, autonomy, and trust.

• For Communities, Not Corporations: Mainstream platforms often have restrictive content policies or a lack of privacy features, creating challenges for adult, queer, or activist-oriented events. Revel is explicitly designed to support these communities.
• Open, Transparent & Self-Hostable: Avoid vendor lock-in. You can host Revel on your own infrastructure for free, giving you complete control over your data and eliminating platform commissions. Its open-source nature means you can trust the code you run.
• Fair & Simple Pricing: For those who choose our future hosted version, the model is simple: no charge for free events or events where you handle payments yourself; a 1.5% + 0.25€ commission (+ VAT where applicable) on paid tickets sold and bought through Revel. This significantly undercuts the high fees of major platforms and helps us keep the platform online, free and open source.

🚀 Key Features

Revel combines the ticketing power of platforms like Eventbrite with the community-building tools of Meetup, all under a privacy-minded, open-source framework.

Community & Membership

• Organizations: Create and manage your community's central hub. Customize its visibility (Public, Unlisted, Members-Only, Private).
• Roles & Permissions: Assign roles like Owner, Staff, and Member, with a granular permission system to control who can create events, manage members, and more.
• Membership System: Manage a roster of members, enabling members-only events and fostering a sense of belonging.
• Membership Tiers & Approval: Define membership tiers, each with its own approval questionnaire — auto-approved, manually reviewed, or hybrid.
• Subscription Plans: Sell monthly or annual memberships through Stripe, or record cash and wire payments manually from the dashboard.
• Members-Only Events: Restrict any event to your members — a weekly class for ten people is a members-only event with a plain RSVP, no tickets needed.
• Series Passes: Sell one pass covering a whole event series — a class pack, a course or a season — optionally restricted to members.
• Digital Membership Cards: Members add their card to Apple Wallet or Google Wallet, or download it as a PDF.

Trust, Safety & Privacy

• Advanced Attendee Screening: Gate event eligibility with custom questionnaires. Automatically review submissions or use a manual/hybrid approach to ensure attendees align with your community's values.
• Full Data Ownership: When self-hosting, you control your data. No third-party trackers, no selling of event data. Keep your community's information safe.
• Tailored Invitations: Send direct invitations that can waive specific requirements (like questionnaires, membership or purchase) for trusted guests.

Billing & VAT

• In-House VAT Calculations: Ticket prices include VAT; net/gross breakdowns are computed at purchase time and persisted on each payment record.
• EU B2B Reverse Charge: Platform fees automatically apply reverse charge for cross-border B2B transactions with VIES-validated VAT IDs.
• VIES Integration: Organization VAT IDs are validated in real-time against the EU's VIES system, with monthly re-validation via Celery Beat.
• Automated Invoicing: Monthly platform fee invoices are generated automatically, rendered as PDFs (WeasyPrint), and emailed to organization owners — with race-safe sequential numbering and idempotent generation.
• Attendee Invoicing: Organizations can generate invoices for ticket buyers on their behalf, with configurable modes (automatic or manual review) and buyer-specific VAT calculation including EU B2B reverse charge.

Core Event & Ticketing Features

• Event & Series Management: Easily create single events or recurring event series under your organization.
• Ticketing & RSVPs: Support for both paid/free ticketed events (powered by Stripe) and simpler RSVP-based gatherings.
• Batch Ticket Purchases: Buy multiple tickets in a single transaction with individual guest names for each ticket holder.
• Venue & Seat Management: Define venues with sectors and individual seats. Support for general admission, random seat assignment, or user-selected seating.
• QR Code Check-In: Manage event entry smoothly with QR code tickets and a staff-facing check-in flow.
• Apple Wallet Integration: Tickets can be added to Apple Wallet for easy access at events (optional, requires Apple Developer certificate).
• Discount Codes: Create percentage or fixed-amount discount codes scoped to events, series, or specific tiers, with usage limits and validity windows.
• Potluck Coordination: A unique, built-in system for attendees to coordinate bringing items, dietary restrictions and preferences, moving logistics off messy spreadsheets.
• Referral Program: Users earn a share of platform fees from ticket purchases by people they refer. Monthly payouts via Stripe with automated self-billing invoices (Gutschrift) or payout statements.
• Global Banning: Platform-wide bans by email, domain, or Telegram username with automatic account deactivation.
• XLSX Exports: Export attendee lists, ticket holders, and member rosters as spreadsheets.

---

📸 Screenshots

Event detail page — cover art, live availability, and one-click ticketing

Organization admin — events, tickets, members, questionnaires, venues, billing & more

---

💻 Tech Stack

Revel is built with a modern and robust backend, designed for performance and scalability.

• 🐍 Backend: Python 3.14+ with Django 5.2 LTS
• 🚀 API: Django Ninja and Django Ninja Extra for a fast, modern, and auto-documenting REST API.
• 🐘 Database: PostgreSQL with PostGIS for powerful geo-features.
• ⚙️ Async Tasks: Celery with Redis for background jobs (emails, evaluations).
• 🐳 Deployment: Fully containerized with Docker for easy setup and deployment.

Why Django 5.2 LTS?

We intentionally stay on Django 5.2 LTS rather than upgrading to Django 6.x. Our policy:

• LTS stability - Django 5.2 is a Long-Term Support release with security updates until April 2028
• Upgrade when it matters - We'll upgrade for compelling features, performance improvements, or security CVEs
• No bleeding edge for its own sake - Django 6.0 is only ~3 months old; we prefer battle-tested releases

---

🏁 Quick Start (Development)

Get a local development environment running in minutes. You'll need make, Docker, Python 3.14+, and UV.

1. Clone the repository:

   git clone https://github.com/letsrevel/revel-backend.git
   cd revel-backend
   

2. Make sure you have the necessary geo data:

   • You must download IP2LOCATION-LITE-DB5.BIN and place it in src/geo/data/
   • You must download the worldcities.csv and place it in src/geo/data/ (or for dev purposes just copy worldcities.mini.csv into worldcities.csv)

3. Run the setup command: This command fully automates the setup process.

   make setup
   

   macOS note: if startup crashes with Could not find the GDAL library or a libgobject-2.0 dlopen error (often after a macOS update), expose Homebrew's libs on dyld's default fallback path: ln -s "$(brew --prefix)/lib" ~/lib. See Troubleshooting.

4. You're ready!

   • The API is running at http://localhost:8000
   • Interactive API docs (Swagger UI) are at http://localhost:8000/api/docs
   • A default superuser is created (admin@letsrevel.io / password).
   • Mailpit (email testing) is at http://localhost:8025

---

🐳 Docker Compose Files

The project uses multiple Docker Compose files for different purposes:

The application itself (Django + Celery) runs on the host via make run — Docker only provides the backing services. For production (app, frontend, reverse proxy, TLS) use the infra repo.

For local development, simply run:

docker compose up -d

This starts PostgreSQL, Redis, ClamAV, and Mailpit. All emails sent by the application are captured by Mailpit and viewable at http://localhost:8025.

---

🏠 Self-Hosting (Production)

The entire stack — frontend, API, workers, database, and (optionally) the full observability suite — is self-hostable on a single box with Docker Compose. The infra repository ships the Compose files, a parameterized Caddyfile, and an interactive setup.sh wizard that writes your .env, picks the right Caddy config, fetches geo data, and brings the stack up. You don't need to clone the backend or frontend repos — the application images are pulled from the registry.

Two reference tiers let Revel scale down a long way:

• Slim — ~2 vCPU / 4 GB RAM (~5 €/mo). Core services only; ClamAV, Telegram, and observability switched off. Recommended starting point for a single-org instance.
• Full — 8 vCPU / 32 GB RAM. Every optional Compose profile: antivirus, the LGTM observability stack, the Telegram bot, and the login canary.

The difference is mostly which Compose profiles you enable (COMPOSE_PROFILES) plus a few feature flags (FEATURE_MALWARE_SCAN, FEATURE_TELEGRAM, FEATURE_OBSERVABILITY, FEATURE_ORGANIZATION_CREATION). Clients read the active flags from GET /version, so gated features are hidden rather than 403'd. The published frontend image (ghcr.io/letsrevel/revel-frontend) is environment-agnostic — it reads its backend API URL from PUBLIC_API_URL at runtime, so one prebuilt image can target any backend (no rebuild required).

📖 Full guide: docs.letsrevel.io/self-hosting.

---

📊 Observability

Revel includes a comprehensive observability stack built on the LGTM (Loki, Grafana, Tempo, Mimir) framework.

Available Services

The observability stack lives in a separate Docker Compose file. After make setup, only the core services (PostgreSQL, Redis, ClamAV, Mailpit) are running. To enable full observability:

docker compose down                                          # stop compose.yaml first
docker compose -f docker-compose-observability.yml up -d

!!! note docker-compose-observability.yml is standalone: it bundles the core services and the observability stack, so it replaces compose.yaml (same container names — don't run both). Note it does not include Mailpit, so email testing is unavailable while it's running.

Features

• Structured Logging: All logs in JSON format with automatic context (request_id, user_id, task_id, etc.)
• Distributed Tracing: Automatic tracing of HTTP requests, database queries, Redis operations, and Celery tasks
• Metrics: Django, PostgreSQL, Redis, and Celery metrics automatically collected
• PII Scrubbing: Automatic redaction of sensitive data (passwords, card numbers, emails, etc.)
• Trace-to-Log Correlation: Jump from traces to related logs and vice versa in Grafana
• Grafana Alerting: Production-ready alerts for errors, payments, auth failures, and more (no DB overhead)

!!! warning "Pyroscope SDK Disabled" The Pyroscope Python SDK (pyroscope-io) is currently disabled due to incompatibility with Grafana Pyroscope 1.6+. Profiling can be provided externally (e.g., via a Grafana Alloy eBPF agent at the infrastructure level). This may change when the SDK is updated.

Quick Start

1. View logs in Grafana: Go to http://localhost:3000 → Explore → Select "Loki" datasource

   {service="revel"} | json | level="error"
   

2. View traces in Grafana: Explore → Select "Tempo" datasource → Search by service or endpoint

3. View metrics in Prometheus: Go to http://localhost:9090 → Graph

   rate(django_http_requests_total[5m])
   

4. Set up alerts: Configure Grafana alert rules for production monitoring

   • See GRAFANA_ALERTING.md for 10+ ready-to-use alert examples
   • Supports Email, Slack, Discord, PagerDuty notifications

Configuration

Observability can be configured via environment variables in .env:

FEATURE_OBSERVABILITY=True         # Enable/disable all observability features (legacy alias: ENABLE_OBSERVABILITY)
TRACING_SAMPLE_RATE=1.0            # 100% in dev (auto-switches to 0.1 in production)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

!!! note make setup runs with FEATURE_OBSERVABILITY=False to avoid connection errors to non-existent services. If you start the observability stack later, set FEATURE_OBSERVABILITY=True in your .env. The old ENABLE_OBSERVABILITY name is still honoured as a deprecated alias for one release.

Verifying Observability Setup

After starting the observability stack and Django with make run, verify the setup:

1. Check startup logs: Look for initialization messages:

   OpenTelemetry tracing initialized: service=revel, sample_rate=1.0, endpoint=http://localhost:4318
   

2. Check metrics endpoint: Visit http://localhost:8000/metrics - should show Prometheus metrics

3. Generate some traffic: Make API requests to create traces and logs

   curl http://localhost:8000/api/docs
   

4. Check Grafana: Go to http://localhost:3000 → Explore → Select datasource

   • Loki for logs: {service="revel"} | json
   • Tempo for traces: Search by service name "revel"
   • Prometheus for metrics: rate(django_http_requests_total[5m])

For detailed documentation, see:

• OBSERVABILITY_SPEC.md - Full specification and implementation plan
• OBSERVABILITY_IMPLEMENTATION.md - What's implemented and how to use it
• GRAFANA_ALERTING.md - Production-ready alert rules and notification setup
• ASYNC_LOGGING.md - Async logging architecture (50-100x faster)

---

🛠️ Development Commands

The project uses a Makefile to streamline common development tasks.

---

🔐 Protected File Access

Revel implements HMAC-signed URLs for protected file access, allowing certain media files to require authorization while being served efficiently by Caddy.

Architecture

Client → Caddy → forward_auth → Django /api/media/validate/*
                                     ↓
                        Validates HMAC signature + expiry
                                     ↓
                        Returns 200 (serve file) or 401

Why HMAC over MinIO/S3?

We evaluated MinIO but chose HMAC signing for these reasons:

• FOSS-friendly: MinIO moved to AGPL v3 and now distributes community edition as source-only (no pre-compiled binaries)
• No additional services: Caddy already handles file serving
• Simple is better: For our use case (<100MB files, no streaming), HMAC signing is sufficient
• No vendor lock-in: Pure Django + Caddy, no external dependencies

How It Works

1. Any file in protected/ requires signed URL access
2. Caddy configuration routes /media/protected/* through forward_auth
3. Django validates the signature and expiry, returns 200 or 401
4. Caddy serves the file if validation passes

Usage in Models

Use ProtectedFileField or ProtectedImageField for files requiring signed access:

from common.fields import ProtectedFileField, ProtectedImageField


class MyModel(models.Model):
    # Stored in protected/attachments/ - requires signed URL
    attachment = ProtectedFileField(upload_to="attachments")

    # Stored in protected/profile-pics/ - requires signed URL
    profile_pic = ProtectedImageField(upload_to="profile-pics")

Usage in Schemas

Use get_file_url() with a static resolver to generate signed URLs in your schemas:

from ninja import ModelSchema
from common.signing import get_file_url


class MyResourceSchema(ModelSchema):
    file_url: str | None = None

    @staticmethod
    def resolve_file_url(obj: MyModel) -> str | None:
        """Return signed URL for protected files, direct URL for public files."""
        return get_file_url(obj.file)

    class Meta:
        model = MyModel
        fields = ["id", "name"]

The get_file_url() function automatically:

• Returns a signed URL (with exp and sig params) for protected paths
• Returns a direct URL for public paths
• Returns None if the file field is empty

Security

• Signatures use Django's SECRET_KEY with domain separation
• URLs expire after 1 hour by default (configurable)
• Timing-safe comparison prevents timing attacks
• Rate limiting on validation endpoint prevents brute-force attacks

Caddy Configuration

See the Protected Files architecture docs for details. The Caddy configuration lives in the infra repository.

---

📂 Project Structure

The codebase is organized into a src directory with a clear separation of concerns, following modern Django best practices.

• src/revel/: The core Django project settings.
• src/accounts/: User authentication, registration, and profile management.
• src/events/: The core logic for organizations, events, tickets, and memberships.
• src/questionnaires/: The questionnaire building, submission, and evaluation system. 📖 Read more
• src/notifications/: Multi-channel notification system (in-app, email, Telegram) with user preferences, digest support, and event-driven delivery.
• src/wallet/: Apple Wallet pass generation for event tickets (.pkpass files).
• src/geo/: Geolocation features (cities, IP lookups).
• src/telegram/: Telegram Bot integration with FSM-based conversation flows, inline keyboards, and organizer notifications.
• src/api/: Main API configuration, exception handlers, and global endpoints.
• src/common/: Shared utilities, authentication backends, base models, and admin customizations.

Most apps contain controllers and service modules for API endpoints and business logic respectively, either as directories or single files depending on complexity.

---

🤝 Contributing

We welcome contributions! Please read our CONTRIBUTING.md to learn how you can get involved, from reporting bugs to submitting code. If you contribute with AI assistance, also read AI_USAGE.md — it is not optional.

Internationalization

Revel aims to support multiple languages (currently English, German, Italian, and French). See i18n.md for details on how the translation system works and how to add new languages.

This is currently heavily WIP.

---

🔒 Security

We run layered, mostly-automated security controls — SAST (bandit), dependency CVE scanning (pip-audit) and license checks, strict typing, a 90% branch-coverage gate, a nightly dependency audit, and periodic OWASP ZAP scans. See SECURITY.md for the full posture.

Found a vulnerability? Please report it privately via Report a vulnerability — do not open a public issue.

---

📜 License

This project is licensed under the MIT license. See LICENSE.

Acknowledgements

• Revel uses the IP2Location LITE database for IP geolocation.
• Revel uses the World Cities Database from SimpleMaps, available under CC BY 4.0.