Fast Boiler 🚀

Generate production-ready FastAPI projects with a modern, scalable architecture in seconds.

fast-boiler is a command-line tool that scaffolds a complete FastAPI application using the robust Repository → Service → Controller layering pattern. Stop writing boilerplate and start building features.

The generated project is not just a skeleton—it comes with a complete, secure authentication system, a powerful database layer, and self-documenting APIs right out of the box.

Core Features

• Scalable Architecture: Cleanly separates database logic (Repositories), business logic (Services), and API endpoints (Controllers) for maximum maintainability.
• Batteries-Included: Scaffolds a complete authentication system with registration, JWT login, and password reset powered by FastAPI Users.
• OAuth Ready: Optionally include social login (e.g., Google) with a single command.
• Advanced CRUD: Generated endpoints come with pagination, sorting, and filtering built-in and automatically documented in Swagger UI.
• Developer-Friendly: An interactive CLI wizard guides you through project setup, and a generate command automates the creation of new resources.
• Modern Tech Stack: Uses the latest, non-deprecated syntax for FastAPI, Pydantic, SQLAlchemy, and modern Python.

Prerequisites

Before you begin, you need to have Python 3.8+ and pipx installed on your system.

pipx is a tool for installing and running Python CLI applications in isolated environments. It is the recommended way to install tools like this one. If you don't have it, you can install it with:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

(You may need to restart your terminal after running pipx ensurepath.)

📦 Installation

Installing fast-boiler is a one-line command:

pipx install fast-boiler```

To verify the installation, run `fast-boiler --help`.

---

## 🚀 Quickstart: Create Your First Authenticated API

Let's build a new API in under two minutes.

### 1. Initialize a New Project

Run the `init` command. It will launch an interactive wizard to configure your project.

```bash
fast-boiler init

Answer the prompts. For this tutorial, accept the defaults (press Enter for each):

What is the name of your project?: myapi
▶ Use asynchronous (async/await) code? [Y/n]: Y
▶ Include FastAPI Users for authentication? (Recommended) [Y/n]: Y
  ▶ Add social OAuth login (e.g., Google)? [y/N]: N

2. Run the API Server

Navigate into your new project, install its dependencies, and run the server.

# Navigate into the project
cd myapi

# (Recommended) Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the dev server
uvicorn app.main:app --reload```

Your API is now live! Open your browser to **`http://127.0.0.1:8000/docs`**.

### 3. Test The Authentication Flow

Your generated API is fully functional. Let's create a user and log in.

1.  **Register:**
    -   In the docs, expand `POST /auth/register`.
    -   Click "Try it out" and enter your details:
        ```json
        {
          "email": "user@example.com",
          "password": "a-strong-password"
        }
        ```
    -   Execute. You should get a `201 Created` response.

2.  **Login:**
    -   Expand `POST /auth/jwt/login`.
    -   Enter your credentials in the form. **Note:** The `username` field is standard for OAuth2, but `fastapi-users` is smart enough to accept an **email address** here.
    -   Execute. You will get a `200 OK` response. An authentication cookie (`fastboilerauth`) has been set in your browser.

3.  **Access a Protected Endpoint:**
    -   Expand `GET /users/me`.
    -   Execute. It will succeed and return your user object, because the browser automatically sent the authentication cookie!

### 4. Generate a New Resource

Now, let's add a new "product" resource to our API.

```bash
# From the root of your 'myapi' project
fast-boiler generate product

The tool will automatically create all the files for the product resource and integrate its router into your application. When the server reloads, you will see a brand new, fully functional CRUD API for /products in your documentation!

What's Generated? The Architecture

fast-boiler creates a clean, layered architecture to keep your code organized:

• app/controllers/: Handles HTTP requests, responses, and calls the service layer. Contains a dependencies.py for query parsing.
• app/services/: Contains all business logic. It's the "brain" of your application.
• app/repositories/: Contains all database interaction logic using a reusable CRUDBase.
• app/models/: Defines your SQLAlchemy database models.
• app/schemas/: Defines your Pydantic data schemas (DTOs).
• app/auth/: If selected, contains the complete fastapi-users authentication setup.

Roadmap

fast-boiler is actively being developed. Future releases will include optional integrations for:

• Database Migrations (Alembic)
• Background Tasks (Celery)
• Caching (Redis)
• CI/CD (Docker, GitHub Actions)

Contributing

Contributions, issues, and feature requests are welcome! Please feel free to open an issue or submit a pull request.