Skip to content

README.md

Latest commit

 

History

History
127 lines (96 loc) · 4.03 KB

README.md

File metadata and controls

127 lines (96 loc) · 4.03 KB
Raw

Python API

A FastAPI backend application with Supabase database integration, designed to complement the React Native mobile application stack at Kealy Studio.

Tech Stack

  • Framework: FastAPI
  • Database: Supabase (PostgreSQL)
  • Package Manager: uv
  • Testing: pytest, pytest-asyncio, pytest-mock
  • Deployment: Docker, Google Cloud Run

Project Structure

python-api/
├── app/
│   ├── core/
│   │   ├── auth.py            # JWT verification dependency + auth helpers
│   │   ├── logger.py          # Colored console logger
│   │   ├── settings.py        # Environment configuration (Pydantic)
│   │   └── supabase_client.py # Singleton async Supabase client
│   ├── routes/
│   │   ├── auth_router.py     # Auth endpoints
│   │   └── email_router.py    # Welcome email (Supabase database webhook)
│   ├── services/
│   │   └── email.py           # Outgoing email via Resend (EMAIL_ENABLED gate)
│   ├── tests/
│   │   ├── conftest.py        # pytest fixtures
│   │   └── test_*.py          # Endpoint tests
│   ├── __init__.py            # FastAPI app initialization
│   └── main.py                # API endpoints and route registration
├── supabase/
│   ├── migrations/            # Database migrations
│   └── config.toml            # Local Supabase configuration
├── .github/workflows/         # CI/CD workflows
├── Dockerfile
├── pyproject.toml
└── uv.lock

API Endpoints

Method Path Auth Description
GET / Public Welcome message
GET /protected Bearer JWT Example authenticated route
DELETE /auth/users/me Bearer JWT Delete the authenticated user's account
POST /emails/welcome X-Webhook-Secret header Send the welcome email — intended for a Supabase database webhook on public.users inserts

Interactive docs are served at /docs (disabled when APP_ENV=production).

Getting Started

Prerequisites

  • Python 3.10 - 3.12
  • uv package manager
  • Supabase CLI (for local development)

Installation

  1. Install dependencies:

    uv sync --all-groups

  2. Start local Supabase:

    supabase start

  3. Copy environment variables:

    cp .env.example .env
cp supabase/.env.example supabase/.env

  4. Run the development server:

    uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

Running Tests

uv run pytest

Database

Supabase migrations are in supabase/migrations/. Current schema includes:

  • users - User profiles synced with Supabase Auth
  • devices - A user may have many devices

Deployment

Publishing a GitHub release is the single deploy ceremony — both workflows run on it:

  • Database: migrations are pushed to production first (see .github/workflows/supabase-deploy-migrations.yaml)
  • API: the code is deployed to Google Cloud Run alongside (see .github/workflows/gcp-deploy.yaml)

The API workflow needs a one-time setup, documented in its own header: fill in the env: block (service name, region, Supabase URL), then create a github-deployer service account and hand its key to GitHub as the GCLOUD_SERVICE_KEY secret. Until that's done, it skips itself quietly on each release. Deploys run as the github-deployer account; the service itself runs as the project's default compute service account, which needs roles/secretmanager.secretAccessor to read its secret from Secret Manager.

To deploy by hand instead (the same command the workflow runs):

gcloud run deploy <appname>-api-service \
  --source . \
  --region=us-east1 \
  --allow-unauthenticated \
  --update-env-vars="APP_ENV=production,LOG_LEVEL=INFO,SUPABASE_URL=<your prod supabase url>" \
  --update-secrets="SUPABASE_SECRET_KEY=SUPABASE_SECRET_KEY:latest" \
  --clear-base-image