Waitly

Waitly is a modern waitlist application designed for early-stage products and private launches. It provides a clean public signup experience alongside a secure admin panel for managing waitlist entries.

Features

• Public waitlist signup with email validation
• Automatic welcome email delivery after signup
• Secure admin authentication
• Admin-only waitlist management dashboard
• Admin accounts created via CLI for improved security (no public admin signup)
• Fully tested backend with CI support
• Frontend built with Next.js and TypeScript

Tech Stack

Frontend

• Next.js (App Router)
• TypeScript
• Tailwind CSS

Backend

• FastAPI
• PostgreSQL
• SQLAlchemy

Authentication & Security

• JWT-based authentication
• Password hashing with bcrypt

Tooling & DevOps

• GitHub Actions (CI)
• Pytest
• Docker (optional / production-ready)

Project Structure

├── .github/
│   └── workflows/            # GitHub Actions CI workflows
│
├── backend/
│   ├── app/
│   │   ├── core/             # App configuration and security utilities
│   │   ├── db/               # Database session and initialization
│   │   ├── dependencies/     # FastAPI dependencies (auth, admin guards)
│   │   ├── models/           # SQLAlchemy models
│   │   ├── routes/           # API route handlers
│   │   ├── schemas/          # Pydantic request/response schemas
│   │   ├── services/         # Business logic (email, auth helpers)
│   │   ├── templates/        # Email HTML templates
│   │   └── main.py           # FastAPI application entry point
│   │
│   ├── cli/                  # CLI tools (admin creation)
│   ├── tests/                # Backend tests
│   ├── Dockerfile            # Backend Docker image definition
│   └── .env.example          # Backend environment variables
│
├── frontend/
│   ├── src/
│   │   ├── app/              # Next.js App Router pages
│   │   │   └── _components/  # Reusable UI components
│   │   │
│   │   └── lib/
│   │       ├── api/          # API client and request helpers
│   │       └── auth/         # Auth utilities (tokens, guards)
│   │
│   ├── Dockerfile            # Frontend Docker image definition
│   └── .env.example          # Frontend environment variables
│
├── docker-compose.yml        # Multi-service Docker orchestration
└── README.md

Getting Started

This section explains how to run the application locally. You can either use Docker (recommended) or run the backend and frontend manually.

---

Prerequisites

• Docker & Docker Compose (recommended)
• Python 3.10+
• Node.js 18+

---

Option 1: Run with Docker (Recommended)

1. Environment variables

Create environment files from the provided examples:

cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env

2. Start the application

From the project root run:

docker-compose up --build

3. Create admin user (CLI)

Run the following command from the project root:

docker-compose exec backend python -m cli.create_admin

3. Access the application (CLI)

Service	URL
Frontend	http://localhost:3000
Backend	http://localhost:8000/docs

Option 2: Manual Development Setup

1. Create and activate virtual environment (project root)

python -m venv .venv
source .venv/bin/activate   # Linux / macOS
# .venv\Scripts\activate    # Windows

2. Backend setup

Install backend dependencies:

pip install -r backend/requirements.txt

Create environment file:

cp backend/.env.example backend/.env

Run the backend server:

cd backend
uvicorn app.main:app --reload

Backend will be available at: http://localhost:8000

3. Frontend setup

In a new terminal:

cd frontend
npm install
cp .env.example .env
npm run dev

Frontend will be available at: http://localhost:3000

4. Create admin user (manual)

With the virtual environment activated and on new terminal:

cd backend
python -m cli.create_admin

Contributing

Contributions are welcome. Please open an issue or submit a pull request with a clear description of your changes.

License

This project is licensed under the terms described in the LICENSE file.