📝 FastAPI + FastHTML + Supabase Todo App

A modern, production-ready todo application with user authentication

🌐 Live Demo | Try it now!

Features • Quick Start • Deployment • Documentation • Architecture

---

🎯 Overview

A full-stack todo application demonstrating modern Python web development best practices. Built with FastAPI for the backend, FastHTML for server-side rendering, and Supabase for database and authentication.

🚀 Try the Live Demo - See it in action with full authentication and todo management!

Perfect for: Learning full-stack Python development, understanding authentication flows, or as a starter template for production applications.

✨ Features

🔐 Authentication User registration & login Secure cookie-based sessions HttpOnly & secure cookies Auto-redirect for unauthenticated users	📋 Todo Management Create, read, update, delete Toggle completion status Real-time updates (HTMX) Auto-clearing forms
🛡️ Security Row-Level Security (RLS) Multi-user data isolation HTTPS-only in production No XSS vulnerabilities	🚀 Production Ready Health check endpoint Environment-based config Comprehensive logging Deployment guides

🏗️ Tech Stack

• Backend: FastAPI - Modern, fast Python web framework
• Frontend: FastHTML - Python-based HTML generation
• Database: Supabase - PostgreSQL with built-in auth
• UI: HTMX - Dynamic updates without JavaScript frameworks
• Server: Gunicorn + Uvicorn workers for production
• Testing: Pytest with 100% critical path coverage

🚀 Quick Start

Prerequisites

• Python 3.12+
• Supabase account (free tier available)
• UV (recommended) or pip

1. Clone and Install

git clone https://github.com/gregory1506/fastapi-supabase-todo-v1.git
cd fastapi-supabase-todo-v1

# Install dependencies with UV (recommended for local development)
uv pip install -r requirements.txt

# Or with pip (works everywhere, used by Render for deployment)
pip install -r requirements.txt

Note: This project uses uv for faster local development, but standard pip works fine and is used for production deployment on Render.

2. Set up Supabase Database

1. Create a new project at supabase.com
2. Go to the SQL Editor in your Supabase dashboard
3. Run the SQL from schema_with_auth.sql to create:
   • Users table (automatically managed by Supabase Auth)
   • Todos table with foreign key to users
   • Row-Level Security (RLS) policies for data isolation
4. Get your project URL and anon key from Settings > API

3. Configure Environment Variables

Create a .env file in the project root:

SUPABASE_URL=your_supabase_project_url
SUPABASE_KEY=your_supabase_anon_key

4. Run the Application

# With UV (recommended)
uv run uvicorn main:app --reload --port 8000

# Or with uvicorn directly
uvicorn main:app --reload --port 8000

The app will be available at http://localhost:8000

Note: For detailed step-by-step instructions including troubleshooting, see INSTRUCTIONS.md

🌐 Deployment

Ready to deploy to production? This app is configured for easy deployment to Render.

See DEPLOYMENT.md for complete deployment instructions including:

• Step-by-step Render deployment
• Environment configuration
• Health checks and monitoring
• Troubleshooting guide
• Production best practices

Production Features

• ✅ Secure HTTPS-only cookies
• ✅ Health check endpoint at /health
• ✅ Production logging configuration
• ✅ Gunicorn with Uvicorn workers
• ✅ Automatic environment detection

📚 Documentation

Document	Description
ARCHITECTURE.md	System architecture with diagrams
DEPLOYMENT.md	Production deployment guide
TESTING.md	Testing approach and commands
SUPABASE_SETUP.md	Supabase configuration guide
TROUBLESHOOTING_SUPABASE.md	Fix common Supabase issues
.claude/INSTRUCTIONS.md	Detailed build instructions

📁 Project Structure

/
├── main.py                 # FastHTML application entry point with routes
├── app/
│   ├── auth/              # Authentication module
│   │   ├── auth_utils.py  # AuthService for login/register
│   │   └── middleware.py  # Authentication middleware
│   ├── models/            # Pydantic models
│   │   ├── todo.py        # Todo data models
│   │   └── user.py        # User data models
│   ├── db/                # Database connection and queries
│   │   ├── supabase.py    # Supabase client setup
│   │   └── operations.py  # Todo CRUD operations with RLS
│   └── frontend/          # FastHTML components
│       └── components.py  # UI components (todos, auth forms)
├── tests/                 # Test files (10 critical tests)
│   ├── test_critical.py   # Core auth & security tests
│   └── test_models.py     # Model validation tests
├── .claude/               # LLM and setup documentation
├── requirements.txt       # Python dependencies
├── schema_with_auth.sql   # Database schema with RLS policies
└── .env                   # Environment variables (not in git)

🔌 API Routes

Authentication Routes

Method	Endpoint	Description
GET	/login	Display login page
POST	/auth/login	Handle user login (sets session cookie)
GET	/register	Display registration page
POST	/auth/register	Handle user registration (sets session cookie)
POST	/auth/logout	Handle user logout (clears session cookie)

Todo Routes (Authenticated)

Method	Endpoint	Description
GET	/	Main todo app page (redirects to login if not authenticated)
POST	/todos	Create new todo (returns HTML fragment)
GET	/todos/{id}	Get single todo item (returns HTML fragment)
GET	/todos/{id}/edit	Get edit form for todo (returns HTML fragment)
PUT	/todos/{id}	Update todo (returns HTML fragment)
PUT	/todos/{id}/toggle	Toggle completion status (returns HTML fragment)
DELETE	/todos/{id}	Delete todo (returns empty response)

All todo routes are protected and require authentication via session cookie. HTMX handles partial page updates for a seamless user experience.

🧪 Development

Testing

This project uses a pragmatic testing approach with 10 critical tests (100% passing) focused on essential functionality for CI/CD. See TESTING.md for details.

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=app --cov=main --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_critical.py -v

Code Quality

# Lint code
uv run ruff check .

# Format code
uv run ruff format .

# Auto-fix linting issues
uv run ruff check --fix .

🏛️ Architecture

System Overview

graph TB
    subgraph "Client Browser"
        UI[Web UI]
        HTMX[HTMX Library]
    end

    subgraph "FastHTML Application"
        Router[FastHTML Router]
        Routes[Route Handlers]
        Components[FastHTML Components]
        Models[Pydantic Models]
    end

    subgraph "Data Layer"
        DBClient[Supabase Client]
        Operations[TodoOperations]
    end

    subgraph "External Services"
        Supabase[(Supabase PostgreSQL)]
    end

    UI --> HTMX
    HTMX -->|HTTP Requests| Router
    Router --> Routes
    Routes --> Components
    Routes --> Operations
    Operations --> Models
    Operations --> DBClient
    DBClient -->|REST API| Supabase
    Components -->|HTML Partials| HTMX
    HTMX --> UI

    style UI fill:#e1f5ff
    style Router fill:#fff4e1
    style Supabase fill:#e8f5e9

Loading

Request Flow - Creating a Todo

sequenceDiagram
    participant Browser
    participant HTMX
    participant FastHTML
    participant TodoOps as TodoOperations
    participant Supabase

    Browser->>HTMX: Submit form
    HTMX->>FastHTML: POST /todos (title, description)
    FastHTML->>FastHTML: Validate with Pydantic
    FastHTML->>TodoOps: create(TodoCreate)
    TodoOps->>Supabase: INSERT INTO todos
    Supabase-->>TodoOps: New todo record
    TodoOps-->>FastHTML: Todo object
    FastHTML->>FastHTML: Render todo_item()
    FastHTML-->>HTMX: HTML partial
    HTMX->>Browser: Insert at top of list
    Browser->>Browser: Display new todo

Loading

See ARCHITECTURE.md for complete architecture documentation with all diagrams.

🔒 Security Features

Authentication

• Cookie-based sessions with HttpOnly cookies for security
• Supabase Auth handles password hashing and user management
• Session tokens stored securely in cookies (not localStorage)
• Automatic redirect to login for unauthenticated users

Database Security

• Row-Level Security (RLS) policies ensure users only see their own todos
• Foreign key relationships maintain data integrity
• Supabase automatically manages user authentication

Frontend Security

• Server-side rendering with FastHTML (Python generates HTML)
• HTMX for dynamic updates (no full page reloads)
• Custom CSS for responsive design
• Form auto-reset after successful submissions

⚙️ Critical Configuration

• HTMX Version: Must use 1.9.12 (stable). The @next version has compatibility issues
• FastHTML HTMX Override: Default HTMX disabled in favor of explicit version loading
• UV vs Pip: UV for local development (speed), pip for production (reliability)
• See INSTRUCTIONS.md for detailed troubleshooting

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI - For the excellent web framework
• FastHTML - For simplifying server-side rendering
• Supabase - For the fantastic PostgreSQL platform
• HTMX - For making dynamic UIs simple

---

Built with ❤️ using Python | Report Bug | Request Feature