Metadata-Version: 2.4
Name: vflask
Version: 1.1.3
Summary: Modern typed Flask project scaffolder with blueprints, RBAC, and local module generation.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1.7
Requires-Dist: jinja2>=3.1.4
Requires-Dist: watchdog>=4.0.1
Requires-Dist: rich>=13.0.0
Requires-Dist: pyfiglet<2,>=1.0.2

# vflask

> A backend framework built on Flask for developers who want a production-ready app structure without writing the same boilerplate every time.

[![Python 3.11+](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![Flask 3](https://img.shields.io/badge/Flask-3.x-000000?logo=flask&logoColor=white)](https://flask.palletsprojects.com/) [![Postgres](https://img.shields.io/badge/PostgreSQL-316192?logo=postgresql&logoColor=white)](https://www.postgresql.org/) [![Redis](https://img.shields.io/badge/Redis-DC382D?logo=redis&logoColor=white)](https://redis.io/) [![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white)](https://www.docker.com/) [![OpenAPI](https://img.shields.io/badge/OpenAPI-6BA539?logo=openapiinitiative&logoColor=white)](https://www.openapis.org/) [![Alembic](https://img.shields.io/badge/Alembic-6D5EAC)](https://alembic.sqlalchemy.org/)

## What Flask is

Flask is a lightweight Python web framework. It gives you routes, request handling, and a simple app setup, but it does not give you a full production backend structure by default.

A typical Flask app usually needs you to add:

- app factory setup
- database models
- migration tooling
- auth and role checks
- service layer organization
- tests
- deployment scripts
- environment-based configuration

## What vflask adds

vflask is a backend starter built on top of Flask. It gives you a usable structure for building real apps faster while staying close to Flask and Python conventions.

It adds:

- project scaffolding
- domain module generation
- app factory pattern
- SQLAlchemy models
- Alembic migrations
- JWT auth and refresh flow
- RBAC helpers
- OAuth and provider adapters
- integration patterns for email, storage, and payment
- CLI commands for local development and project tasks

## When to use vflask

Use vflask when you want to build a backend service, internal platform, SaaS API, or admin system without setting up the same patterns repeatedly.

It is useful if you want:

- a consistent project structure
- reusable CRUD patterns
- auth and authorization by default
- safer database changes through migrations
- faster project bootstrapping
- a path toward production without rewriting everything

## Install

```bash
python -m pip install vflask
```

## Create a project

```bash
vflask new bookstore
cd bookstore
```

This creates a project structure with a Flask app factory, config files, migrations, tests, and starter modules.

## Understand the app factory

This is the most important concept in Flask and in vflask.

An app factory is a function that creates your Flask app. It keeps configuration and setup in one place instead of creating globals everywhere.

```python
from app import create_app

app = create_app()
```

The generated app usually does things like:

- load environment variables
- configure Flask
- initialize the database
- register blueprints
- set up auth and routes
- add health and docs endpoints

You do not need to know every detail of Flask before using vflask. The key idea is: the app is created in one place and then used by the runtime.

## Your real backend workflow

Here is the workflow a backend developer normally follows in vflask.

### 1) Create the project

```bash
vflask new fintech-api
cd fintech-api
```

### 2) Generate a domain module

For a real system, you usually create domain modules such as users, products, orders, invoices, or subscriptions.

```bash
vflask module create products \
  -f name:string:required \
  -f price:decimal:required \
  -f sku:string:unique \
  -r admin -r editor
```

This generates files for a business module, such as:

- models
- routes
- services
- handlers
- tests
- migration stub

Choose the generated operations with `--mode`: `c` generates create, `cr` adds read/list, `crd` adds soft and bulk delete, and `crud` includes update as well. The default is `crud`.

### 3) Add the database model

Generated module files create a model for your data. For example, a product might have fields like name, price, and sku.

The generated app uses SQLAlchemy, so relationships, validation, and migrations are handled in a structured way.

### 4) Run migrations

When the schema changes, you migrate it instead of editing the database manually.

```bash
python -m app.cli init-db
```

If you are using the standard Flask CLI flow, you may also use migration commands in the generated app depending on the project runtime.

### 5) Add auth and roles

Most business systems need authentication and authorization.

The generated project already includes patterns for:

- signup
- login
- refresh tokens
- user profile
- logout
- RBAC checks
- Google OAuth routes

A simple backend pattern looks like this:

```python
from flask_jwt_extended import jwt_required

@jwt_required()
def get_profile():
    return {"ok": True}
```

The main point is that vflask gives you a consistent place for auth, not a scattered set of ad-hoc checks across the app.

### 6) Add provider integrations

Real apps talk to external systems. vflask supports patterns for:

- email delivery
- object storage
- payments
- OAuth providers

Example env config:

```bash
export PAYMENT_PROVIDER=flutterwave
export STORAGE_PROVIDER=s3
export MAIL_PROVIDER=smtp
export GOOGLE_CLIENT_ID=your-client-id
export GOOGLE_CLIENT_SECRET=your-client-secret
export GOOGLE_REDIRECT_URI=http://localhost:5000/api/v1/auth/google/callback
```

This keeps provider logic separate from the business logic.

### 7) Run the project

Local development is simple:

```bash
python -m app.cli run
```

You can also use the package-level CLI for scaffolding:

```bash
vflask run
```

The app runtime is designed to behave like a real backend service, not just a static template.

### 8) Test it

```bash
pytest -q
```

Generated modules usually include tests so you can validate each domain area as it grows.

### 9) Deploy

The generated project is structured with Docker, env configuration, and release flow in mind. That means you can move from local development to deployment without rebuilding your entire architecture.

## App structure

A generated vflask project usually looks like this:

```text
app/
  auth/
  base/
  integrations/
  shared/
  modules/
  tests/
  migrations/
  cli.py
  __init__.py
Dockerfile
docker-compose.yml
.env.example
scripts/
```

The important idea is that the app is organized around real backend concerns:

- auth
- business modules
- base utilities
- integrations
- migrations
- deployment scripts

## Common commands

### Scaffold a new project

```bash
vflask new myapp
```

### Generate a module

```bash
vflask module create products \
  -f name:string:required \
  -f price:decimal:required
```

### Run the generated app

```bash
vflask run
```

### Manage schema and tests

```bash
vflask db init
vflask db migrate -m "add products"
vflask db upgrade
vflask test -- -q
```

### Run common project tasks

```bash
vflask create-user admin@example.com "Admin User"
vflask push "feat: add products"
vflask app -- --help
vflask exec -- python -m pytest -q
```

`create-user` prompts for the password without echoing it. `app` forwards commands to the generated app CLI, while `exec` runs an arbitrary command in the project directory without invoking a shell. Use `vflask --help` and `vflask db --help` for the full command options.

### Check help

```bash
vflask --help
python -m app.cli --help
```

## Example backend flow

A simple SaaS backend might look like this:

1. User signs up
2. User logs in with JWT
3. App validates roles and permissions
4. Product module exposes CRUD endpoints
5. Database stores product records
6. Storage and email services are called when needed
7. Tests cover key business rules
8. Deployment runs with Docker and env config

This is the typical shape of a real vflask backend project.

## Environment variables

Use environment variables for secrets and provider settings. Keep them out of source control.

Common variables include:

- `SECRET_KEY`
- `DATABASE_URL`
- `JWT_SECRET_KEY`
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- `GOOGLE_REDIRECT_URI`
- `PAYMENT_PROVIDER`
- `MAIL_PROVIDER`
- `STORAGE_PROVIDER`

Example:

```bash
export DATABASE_URL=postgresql://user:pass@localhost:5432/app
export SECRET_KEY=your-secret-key
export JWT_SECRET_KEY=your-jwt-secret
```

## Production mindset

vflask is not a toy framework. It is meant to give you a backend layout that is strong enough for a real product.

A good backend is usually built around:

- clean separation of concerns
- explicit auth
- migration-safe schema changes
- env-based configuration
- testing
- integration boundaries
- deployable runtime setup

vflask tries to give you those defaults from the beginning.

## Recommended next steps

If you are starting from scratch:

1. create a project with `vflask new`
2. generate your first real domain module
3. connect your database and auth settings
4. add endpoints and business logic
5. write tests early
6. deploy through Docker or CI flow
