Flask Starter Pack (w/ Postgres) 🚀

A robust starter pack or boilerplate for building production-ready APIs using Flask and PostgreSQL. This project is designed with Clean Architecture and SOLID principles in mind to ensure scalability and maintainability.

The main goal of this starter pack is to accelerate the development process by providing a well-structured foundation, allowing you to focus directly on business logic.

✨ Core Features & Tech Stack

• Framework: Flask
• Database: PostgreSQL
• Production Server: Gunicorn
• Architecture: Layered Architecture (API, Services, Models) that separates concerns.
• ORM: Flask-SQLAlchemy for elegant database interaction.
• Database Migrations: Flask-Migrate (using Alembic) to safely manage schema changes.
• Validation & Serialization: Flask-Marshmallow for clean request validation and response serialization.
• API Documentation: Flasgger automatically generates OpenAPI 3.0 (Swagger UI) documentation.
• Configuration: Uses a .env file for secure management of environment variables.

---

🏛️ Project Structure

The directory structure is designed for scalability and code readability.

flask-postgres-starter/
├── app/
│   ├── __init__.py
│   ├── api/
│   ├── core/
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── utils/
├── migrations/
├── .env.example 
├── .gitignore
├── .railway.json
├── run.py
└── requirements.txt

---

⚙️ Getting Started

Follow these steps to get the project running in your local environment.

1. Prerequisites

• Python 3.9+
• PostgreSQL installed and running.
• Create a new database in PostgreSQL for this project (e.g., starter_db).

2. Installation

1. Clone this repository:

   git clone https://github.com/asepscareer/flask-postgres-starter.git
   cd flask-postgres-starter

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # or `venv\Scripts\activate` on Windows

3. Install all dependencies:

   pip install -r requirements.txt

4. Configure Environment Variables:

   • Copy the .env.example file to .env.

     cp .env.example .env

   • Open the .env file and adjust the values, especially DATABASE_URL and SECRET_KEY.

     # Format: postgresql://<user>:<password>@<host>:<port>/<dbname>
     DATABASE_URL="postgresql://postgres:password@localhost:5432/starter_db"
     SECRET_KEY="change-me-to-a-very-secret-key"

5. Run Database Migrations: This command will create all the necessary tables in your database.

   # Set FLASK_APP environment variable
   export FLASK_APP=run.py # (use 'set' on Windows CMD)
   
   # Initialize migrations (only once at the start of the project)
   flask db init
   
   # Create a migration file
   flask db migrate -m "Initial migration."
   
   # Apply the migration to the database
   flask db upgrade

6. Run the Development Server:

   flask run

   The application is now running at http://127.0.0.1:5000.

---

📚 API Usage

The primary guide for using the API is the interactive Swagger UI documentation.

• API Documentation (Swagger): Open your browser and navigate to http://127.0.0.1:5000/apidocs

You can see all available endpoints, data models, and even try the API directly from your browser.

cURL Example: Creating a New User

curl -X POST [http://127.0.0.1:5000/api/v1/users/](http://127.0.0.1:5000/api/v1/users/) \
-H "Content-Type: application/json" \
-H "X-Request-ID: 12345" \
-d '{
    "username": "cool_boss",
    "email": "[email protected]"
}'

---

🚀 Running in Production

For a production environment, use Gunicorn as the WSGI server.

gunicorn --bind 0.0.0.0:8000 run:app

---

📄 License

This project is licensed under the MIT License.