Skip to content
Projects

selamet/letsraffle-api

View on GitHub

selamet/letsraffle-api has 29 GitHub stars and 5 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 04:25 UTC. Last push 2026-11-13.

How these counts are measured

What you can do

  • πŸ” User authentication and authorization
  • 🎲 Draw creation and management
  • πŸ‘₯ Participant addition and removal
  • 🎁 Automatic matching algorithm

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

A simple and secure raffle platform with instant result generation

Developer Tools

README.md

Original

Santa's Draw - Secret Santa API

FastAPI-based RESTful API project for Secret Santa draw management.

Features

  • πŸ” User authentication and authorization
  • 🎲 Draw creation and management
  • πŸ‘₯ Participant addition and removal
  • 🎁 Automatic matching algorithm
  • πŸ“§ Email notifications
  • πŸ”„ Versioned API (v1)

Technologies

  • FastAPI 0.120.0 - Modern web framework
  • Pydantic 2.12.3 - Data validation
  • Python 3.13
  • Uvicorn - ASGI server
  • SQLAlchemy 2.0.36 - ORM
  • PostgreSQL - Database
  • Alembic 1.14.0 - Database migrations

Quick Start

# Clone the repository
git clone <repository-url>
cd santas_draw

# Copy environment file
cp .env.example .env

# Start all services
docker-compose up -d

# That's it! Application is running at http://localhost:8000
# API Docs: http://localhost:8000/docs

Prerequisites

  • Docker & Docker Compose

No Python, PostgreSQL, or other dependencies needed!

Available Commands

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f

# View application logs only
docker-compose logs -f app

# View database logs only
docker-compose logs -f postgres

# Rebuild and start
docker-compose up -d --build

# Stop and remove volumes
docker-compose down -v

Configuration

The application uses environment variables loaded from .env file. Key settings:

  • APP_NAME - Application name
  • APP_VERSION - Application version
  • DEBUG - Debug mode (True/False)
  • API_VERSION - API version
  • HOST - Server host
  • PORT - Server port
  • CORS_ORIGINS - CORS allowed origins
  • DATABASE_URL - PostgreSQL connection string
  • DATABASE_ECHO - Log SQL queries (True/False)
  • DATABASE_POOL_SIZE - Connection pool size
  • DATABASE_MAX_OVERFLOW - Max overflow connections

E-mails

When Who Template
Names are drawn every participant email-template-{tr,en}.html
Someone joins a draw that participant join-confirmation.html
An invite draw is created the organizer draw-created.html
24 hours before a scheduled draw the organizer draw-reminder.html
A scheduled draw cannot run (fewer than 3 participants) the organizer, once draw-not-run.html
Password reset requested the user reset-password-template-{tr,en}.html

All of them are sent from Celery tasks, so a mail problem never fails the request that caused it.

Push notifications

When Who
Names are drawn participants
Someone joins the organizer: right away for the first join, then at most one summary per hour
24 hours before a scheduled draw organizer and participants
A scheduled draw cannot run (fewer than 3 participants) the organizer, once

Announcement e-mails

Campaign e-mails (for example the 2027 launch announcement) are sent with a script, never automatically:

python -m scripts.send_announcement                      # dry run: recipient counts only
python -m scripts.send_announcement --to [email protected]  # one test e-mail
python -m scripts.send_announcement --apply              # send to every registered user

Every e-mail carries a personal unsubscribe link (/api/v1/email/unsubscribe) and one-click List-Unsubscribe headers. Unsubscribed addresses are skipped, and sent addresses are recorded so the script can be re-run safely. API_URL must be the public URL of the API in production.

API Documentation

After running the application:

Project Structure

app/
β”œβ”€β”€ main.py          # Main application
β”œβ”€β”€ models/          # Database models
β”œβ”€β”€ schemas/         # Pydantic schemas
β”œβ”€β”€ api/
β”‚   β”œβ”€β”€ deps.py      # Dependency injection
β”‚   └── v1/          # API endpoints
β”œβ”€β”€ config/          # Configuration
└── tasks/           # Background tasks

License

AGPL v3 - See LICENSE file for details.