Flask Boilerplate

A scalable, production-ready Flask boilerplate with advanced features like authentication, database integration, caching, monitoring, and more.

Project Structure

flask-boilerplate/
├── app/
│   ├── __init__.py          # App factory
│   ├── config/
│   │   └── settings.py      # Pydantic settings
│   ├── core/                # Core infrastructure
│   │   ├── database.py      # Tortoise ORM setup
│   │   ├── cache.py         # Redis setup
│   │   └── metrics.py       # Prometheus metrics
│   ├── middlewares/         # Middleware components
│   │   └── middleware.py    # CORS, rate limiting
│   ├── models/              # Tortoise models
│   │   └── user.py
│   ├── routes/              # Flask blueprints
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   └── example.py
│   ├── schemas/             # Pydantic schemas
│   │   └── user.py
│   ├── services/            # Business logic
│   │   └── auth.py
│   ├── errors/
│   │   └── handlers.py      # Error handlers
│   └── utils/
│       └── logger.py        # Structured logging
├── tests/
│   └── test_app.py          # pytest tests
├── .env.example             # Environment variables template
├── docker-compose.yml       # Docker services
├── Dockerfile               # Container definition
├── pyproject.toml           # Dependencies and project config
├── run.py                   # Entry point
└── README.md

---

Getting Started

Prerequisites

• Python 3.13+
• Docker and docker-compose (optional)

Installation

1. Clone the repository

   git clone https://github.com/samarth3301/flask-boilerplate.git
   cd flask-boilerplate

2. Set up environment

   cp .env.example .env
   # Edit .env with your settings

3. Install dependencies

   pip install -e .

4. Run with docker-compose (recommended)

   docker-compose up --build

5. Or run locally

   python run.py

---

Running the Application

Start the Flask development server:

flask run

Or, if you have an app.py or similar entrypoint:

python app.py

By default, the server runs at http://localhost:5000.

---

Routes

This boilerplate is structured to make it easy to add new API routes. Here’s how routes are typically handled:

• All routes are defined in the routes/ directory or in the main app.py file.

• Example of a basic route in app.py:

  from flask import Flask, jsonify
  
  app = Flask(__name__)
  
  @app.route("/")
  def home():
      return jsonify({"message": "Welcome to Flask Boilerplate!"})

• To add new routes, create new Python files in the routes/ directory (if it exists) and import them in your main app.

Tip: For modular APIs, use Blueprints to organize your routes.

---

Development & Customization

• Add more endpoints by creating new routes.
• Update requirements.txt and install new dependencies using uv pip install <package>.
• Use .env for environment variables.

---

Useful Commands

• Install dependencies:
  uv pip install -r requirements.txt
• Add new dependencies:
  uv pip install <package>
• Freeze dependencies:
  uv pip freeze > requirements.txt

---

License

This project is licensed under the MIT License. See LICENSE for details.

---

Happy coding!