🚀 fh-saas

Production-ready multi-tenant SaaS toolkit for FastHTML applications.

⚡ Quick Start

1. Install

pip install fh-saas

2. Configure Environment

# .env file
DB_TYPE=POSTGRESQL
DB_USER=postgres
DB_PASS=your_password
DB_HOST=localhost
DB_NAME=app_host

# Optional integrations
STRIPE_SECRET_KEY=sk_...
RESEND_API_KEY=re_...
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

3. Initialize Your App

from fh_saas.db_host import HostDatabase, GlobalUser, TenantCatalog, Membership, gen_id, timestamp
from fh_saas.db_tenant import get_or_create_tenant_db
from fh_saas.utils_db import register_tables, create_indexes
from fh_saas.utils_log import configure_logging

# Configure logging (once at startup)
configure_logging()

# Connect to host database
host_db = HostDatabase.from_env()

# Create a new user
user = GlobalUser(
    id=gen_id(),
    email="founder@startup.com",
    oauth_id="google_abc123",
    created_at=timestamp()
)
host_db.global_users.insert(user)

# Create a tenant for their organization
tenant = TenantCatalog(
    id=gen_id(),
    name="Acme Corp",
    db_url="postgresql://...",
    created_at=timestamp()
)
host_db.tenant_catalogs.insert(tenant)

# Link user to tenant as owner
membership = Membership(
    id=gen_id(),
    user_id=user.id,
    tenant_id=tenant.id,
    profile_id=gen_id(),
    role="owner",
    created_at=timestamp()
)
host_db.memberships.insert(membership)
host_db.commit()

4. Work with Tenant Data

# Get tenant's isolated database
tenant_db = get_or_create_tenant_db(tenant.id, tenant.name)

# Define your app's data models
class Project:
    id: str
    name: str
    status: str = "active"
    created_at: str

class Task:
    id: str
    project_id: str
    title: str
    completed: bool = False

# Register tables (creates if not exist)
tables = register_tables(tenant_db, [
    (Project, "projects", "id"),
    (Task, "tasks", "id"),
])

# Add indexes for performance
create_indexes(tenant_db, [
    ("tasks", ["project_id"], False, None),
    ("tasks", ["completed"], False, None),
])

# Use the tables
projects = tables["projects"]
projects.insert(Project(id=gen_id(), name="Launch MVP", created_at=timestamp()))
tenant_db.conn.commit()

📚 Documentation Guide

Section	What You'll Learn
📦 Core
Multi-Tenant Setup	Host database, user management, tenant registry
Tenant Databases	Isolated databases per tenant, connection pooling
Table Management	Create tables & indexes from dataclasses
🔌 Integrations
HTTP Client	REST APIs with retries, rate limiting, auth
GraphQL Client	Streaming pagination for large datasets
Webhooks	Receive & verify external webhooks
💳 Payments & Migrations
Stripe Payments	Subscriptions, trials, access control
DB Migrations	Version tracking, rollback support
⚙️ Data Pipeline
Background Tasks	Async job execution
Data Transforms	JSON → Polars → Database pipeline
🛠️ Utilities
SQL Helpers	Database type detection, query builders
Logging	Configurable logging for all modules
Authentication	OAuth flows (Google, GitHub)
Email Sending	Transactional emails via Resend
📣 Content
Blog Publishing	Markdown blog with frontmatter
SEO & Sitemaps	Sitemap generation, meta tags
Workflow Engine	Multi-step automation

🛠️ Developer Guide

This project uses nbdev for literate programming. The source of truth is in the nbs/ notebooks.

Development Setup

# Clone and install in dev mode
git clone https://github.com/abhisheksreesaila/fh-saas.git
cd fh-saas
pip install -e .

# Make changes in nbs/ directory, then compile
nbdev_prepare

📦 Installation

# From PyPI (recommended)
pip install fh-saas

# From GitHub (latest)
pip install git+https://github.com/abhisheksreesaila/fh-saas.git

GitHub · PyPI · Documentation

🤖 For AI Assistants: Download llms-ctx.txt — Complete API documentation for LLMs

🤖 AI Assistant Context

For AI coding assistants (GitHub Copilot, Claude, ChatGPT, Cursor, etc.), download the complete API documentation:

📥 Download llms-ctx.txt — Complete fh-saas documentation in LLM-friendly format

How to use:

Download the context file
Add to your AI assistant’s instructions/knowledge base
Get accurate code suggestions for fh-saas APIs

This file contains all module documentation, examples, and API signatures formatted for optimal LLM understanding.

🤝 Contributing

Contributions are welcome! Please check the GitHub repository for issues and discussions.