selamet/letsraffle-api
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.
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 ToolsREADME.md
OriginalSanta'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 nameAPP_VERSION- Application versionDEBUG- Debug mode (True/False)API_VERSION- API versionHOST- Server hostPORT- Server portCORS_ORIGINS- CORS allowed originsDATABASE_URL- PostgreSQL connection stringDATABASE_ECHO- Log SQL queries (True/False)DATABASE_POOL_SIZE- Connection pool sizeDATABASE_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:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
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.