Skip to content

README.md

Latest commit

 

History

History
234 lines (203 loc) · 8.26 KB

README.md

File metadata and controls

234 lines (203 loc) · 8.26 KB

FastAPI Authentication & Billing Service

A FastAPI backend that provides login/registration, OAuth, OTP, email verification, and Stripe-based subscriptions. It runs async with PostgreSQL, Redis, and Celery so you can plug it into a SaaS dashboard or API-first product.

Project Structure

fastapi-saas-starter/
|-- .github/
|   `-- workflows/ci.yml
|-- alembic/
|   |-- env.py
|   |-- script.py.mako
|   `-- versions/
|-- src/
|   |-- admin/
|   |   |-- ai_repo.py
|   |   |-- ai_settings.py
|   |   |-- ai_utils.py
|   |   |-- ai_vars.py
|   |   |-- config.py
|   |   |-- dependencies.py
|   |   |-- emails.py
|   |   |-- models.py
|   |   |-- repository.py
|   |   |-- router.py
|   |   |-- schemas.py
|   |   |-- services.py
|   |   `-- utils.py
|   |-- auth/
|   |   |-- config.py
|   |   |-- dependencies.py
|   |   |-- emails.py
|   |   |-- models.py
|   |   |-- repository.py
|   |   |-- router.py
|   |   |-- schemas.py
|   |   |-- service.py
|   |   `-- utils.py
|   |-- billing/
|   |   |-- dependencies.py
|   |   |-- emails.py
|   |   |-- models.py
|   |   |-- repository.py
|   |   |-- router.py
|   |   |-- schemas.py
|   |   |-- service.py
|   |   |-- stripe_gateway.py
|   |   `-- tasks.py
|   |-- common/
|   |   `-- enums.py
|   |-- settings/
|   |   |-- app.py
|   |   |-- celery.py
|   |   |-- database.py
|   |   |-- mail.py
|   |   |-- redis.py
|   |   `-- stripe.py
|   |-- auth_bearer.py
|   |-- celery_app.py
|   |-- config.py
|   |-- database.py
|   |-- dependencies.py
|   |-- hashing.py
|   |-- jwt.py
|   |-- logging.py
|   |-- main.py
|   |-- models.py
|   |-- paginate.py
|   |-- rate_limiter.py
|   |-- repository.py
|   |-- tasks.py
|   `-- utils.py
|-- static/
|   `-- admin/
|-- templates/
|   `-- email/
|-- tests/
|   |-- auth/
|   |-- billing/
|   `-- conftest.py
|-- .env.example
|-- Dockerfile
|-- alembic.ini
|-- docker-compose.yml
|-- pyproject.toml
`-- uv.lock

Technical Overview

  • FastAPI app with per-domain routers (src/auth/router.py, src/billing/router.py, src/admin/router.py), CORS, structured logging, and slowapi rate limiting.
  • Service/repository layers over async SQLAlchemy 2.0 + asyncpg; sync engine for Celery tasks.
  • JWT access, refresh, and validation tokens with hashed refresh storage and rotation.
  • Stripe Checkout + webhook handling for plans, subscriptions, renewals, and cancellations.
  • SMTP email flows (verification, password reset, OTP, subscription notices) via FastAPI-Mail.
  • Celery worker and beat for subscription emails and expiry sweeps.
  • Admin module with AI-assisted features (audit logs, SQL/CSV export).

Main Features

  • Local auth: register/login, email verification, password reset/change.
  • OTP login (email-delivered, single-use, 15-minute expiry).
  • Social auth: Google and GitHub with state validation and auto-provisioning.
  • Refresh token rotation with DB-backed JTI tracking and httpOnly cookies.
  • Plans: create/update/soft-delete, tiering, and Stripe product/price sync.
  • Subscriptions: checkout, upgrade, cancel-at-period-end, and access window enforcement.
  • Stripe webhooks: checkout completion, invoice success/failure, subscription deleted.
  • Payments recorded on invoice success; subscription emails dispatched via Celery.
  • Admin dashboard with audit logging.
  • Rate limiting (default 5/min) and request logging for observability.

Technology Stack

  • Python 3.12+, FastAPI, Starlette, Pydantic v2
  • Async SQLAlchemy + asyncpg (PostgreSQL), Alembic migrations
  • JWT via python-jose; Argon2 hashing (passlib)
  • Stripe Python SDK
  • Redis broker; Celery worker and beat
  • FastAPI-Mail (SMTP + Jinja templates)
  • slowapi for rate limiting; loguru for logging
  • uv for dependency management

Requirements

  • Python 3.12+
  • uv package manager
  • PostgreSQL 15+
  • Redis 7+
  • Stripe keys (public, secret, webhook signing) for billing features
  • SMTP credentials for transactional emails
  • Google and GitHub OAuth credentials for social login
  • Optional: Docker and docker-compose for containerised orchestration

Quick Start (Local Development)

  1. Install uv (if you haven't already):

    curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Install dependencies (creates a .venv automatically):

    uv sync

  3. Install and start PostgreSQL & Redis (Ubuntu/Debian):

    sudo apt-get install -y postgresql redis-server
sudo systemctl start postgresql redis-server

  4. Create the database and user:

    sudo -u postgres psql -c "CREATE USER dev_user WITH PASSWORD 'dev_pass' CREATEDB;"
sudo -u postgres psql -c "CREATE DATABASE fastapi_saas OWNER dev_user;"
sudo -u postgres psql -c "CREATE DATABASE fastapi_saas_test OWNER dev_user;"

  5. Configure environment: copy .env.example to .env and adjust values (database URLs, secrets, etc.):

    cp .env.example .env
# Edit .env — at minimum set DATABASE_URL, SYNC_DATABASE_URL, TEST_DATABASE_URL

  6. Run migrations:

    uv run alembic upgrade head

  7. Start the API:

    uv run uvicorn src.main:app --reload

  8. Start Celery (separate terminals, optional for email/subscription background jobs):

    uv run celery -A src.celery_app.celery_app worker --loglevel=info
uv run celery -A src.celery_app.beat_app beat --loglevel=info

The API docs are at http://localhost:8000/docs once running.

Environment Variables

All settings are loaded via pydantic-settings from .env. See .env.example for the full list.

Group Variables
App APP_NAME, APP_ENV, APP_DEBUG, APP_URL
Database DATABASE_URL (async/asyncpg), SYNC_DATABASE_URL (sync/psycopg for Celery), TEST_DATABASE_URL
JWT ALGORITHM, ACCESS_SECRET_KEY, ACCESS_TOKEN_EXPIRE, REFRESH_SECRET_KEY, REFRESH_TOKEN_EXPIRE, VALIDATION_SECRET_KEY, VALIDATION_TOKEN_EXPIRE
Mail SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD
Google OAuth GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI, GOOGLE_AUTH_URL, GOOGLE_TOKEN_URL, GOOGLE_USERINFO_URL
GitHub OAuth GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GITHUB_REDIRECT_URI, GITHUB_AUTHORIZE_URL, GITHUB_TOKEN_URL, GITHUB_USER_API, GITHUB_EMAILS
Redis REDIS_URL
Celery CELERY_WORKER_URL, CELERY_BEAT_URL
Stripe STRIPE_PUBLIC_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET
AI AI_PROVIDER, GROQ_API_KEY, GROQ_BASE_URL, AI_MODEL

Running with Docker Compose

docker compose up --build

Services: api, db (Postgres 16), redis, celery, celery_beat. Health checks ensure the API waits for Postgres and Redis to be ready.

Production Notes

  • Set APP_DEBUG=False, tighten CORS origins, and set cookie secure=True in the auth router.
  • Provide HTTPS termination (e.g., Nginx in front of Uvicorn/Gunicorn workers).
  • Run workers with process managers (systemd/supervisor) or containers.
  • Validate Stripe webhook signature with STRIPE_WEBHOOK_SECRET and expose the webhook URL publicly.

Tests

uv run pytest
  • Set TEST_DATABASE_URL to a dedicated test database.
  • Tests spin up schema automatically, disable the rate limiter, and use httpx ASGI client fixtures.
  • Mock Stripe/email in new tests to avoid real calls.

API Overview

  • Auth: /register, /login, /refresh-token, /verify, /request/verify, /forget-password, /new-password, /change-password, /request/login-code, /login/code, /google/login + callback, /github/login + callback, /deactivate.
  • Billing: /billing/plans (list/create), /billing/plans/{id} (get/update/delete), /billing/subscriptions/me, /billing/subscriptions/subscribe, /billing/subscriptions/upgrade, /billing/subscriptions/cancel, /billing/payments/me, /billing/stripe/webhook.
  • Admin: User management, audit logs, AI-assisted SQL/CSV export.

Contribution Guidelines

  • Fork/branch, keep PRs focused, and update docs when behaviors change.
  • Add/adjust tests (uv run pytest) for any new logic; mock external providers.
  • Run uv run alembic upgrade head and uv run pytest before pushing.
  • Use clear commit messages and reference relevant modules/paths.

License

MIT-style licensing (check repository for the full text).