From Peewee models
to a working admin app.

Why bro-sba-py?

Starting a data-driven app often means repeating the same setup: API routes, service functions, admin tables, forms, and configuration. bro-sba-py generates that foundation from your Peewee models, so you can spend more time on the behavior that makes your application yours.

Getting started

Install the package in an isolated command-line environment. pipx keeps the generator's dependencies separate from the Python packages in your app.

pipx install bro-sba-py

This installs two commands:

• bro-py generates the Flask backend.
• bro-py-admin generates the browser-based admin interface.

Your first project

Generate the admin pages, then generate the backend into the same output folder. If you leave setup options out, the interactive terminal asks you to choose them.

bro-py-admin --models-dir ./models --output-dir ./generated

bro-py --models-dir ./models --output-dir ./generated

Install the generated dependencies and start the app:

python -m pip install -r requirements.txt
python app.py

Open http://127.0.0.1:5000/admin/ in your browser. On first setup, answer the database and feature questions in the terminal.

Configure what each model exposes

Peewee fields describe your data. Optional class methods tell the generator which fields can be written, searched, displayed, protected, or turned into custom actions.

class User(Model):
    name = CharField()
    email = CharField()
    password = CharField()

    @classmethod
    def insert_fields(cls):
        return {
            "name": {"required": True, "type": str},
            "email": {"required": True, "type": str},
        }

    @classmethod
    def search_fields(cls):
        return ["name", "email"]

    @classmethod
    def sensitive_fields(cls):
        return ["password"]

A REST API, generated per model

For each model, the backend creates endpoints for listing, creating, reading, updating, deleting, and searching records. List endpoints include pagination and sorting.

GET /api/users?page=2&per_page=20&sort=name&order=desc

Generated view functions call service functions for model operations. This keeps the HTTP layer separate from the generated data-handling layer.

Add actions for your app's workflow

Use custom_actions() to describe operations that are specific to your application, such as approving an invoice or freezing an account. An action can be a route stub for your own code, generated from supported declarative logic, or kept internal without an API route.

@classmethod
def custom_actions(cls):
    return {
        "freeze": {
            "method": "PATCH",
            "label": "Freeze account",
            "confirm": True,
        },
    }

Generated custom-code markers preserve supported hand-written logic during regeneration. Always preview changes before using --force.

A dashboard for everyday data work

The frontend generator creates the admin pages, styles, browser JavaScript, and Flask blueprint. Generated tables support search, sorting, and pagination; forms follow the fields configured on each model.

Choose SQLite or MySQL

In an interactive terminal, the generator asks which engine to use if you did not specify one. SQLite is a good choice for a local demo; MySQL connects to a database server.

Protect the admin and API

Enable --auth and define auth_config() on the model selected for authentication. The generated flow can include admin login, signup, email verification, JWT API authentication, role restrictions, CSRF protection for dashboard changes, and rate limiting for sensitive endpoints.

Configure SMTP settings to send verification email. In local development, the generated configuration can provide a console fallback. Use admin_config() to define which roles may read, create, update, delete, or run selected actions.

Keep the admin dashboard in sync

Enable --socketio in both generators. The backend publishes record events and operational status; the admin frontend receives them over Socket.IO without requiring a manual refresh.

from extensions import publish_task_status

publish_task_status("catalog-sync", "running", "Checking products")
# Run your background work here
publish_task_status("catalog-sync", "completed", "Sync finished")

Task status is held in process memory, so it is temporary and is not shared across multiple workers. For a multi-worker Socket.IO deployment, configure SOCKETIO_MESSAGE_QUEUE with Redis and set up sticky sessions at your host.

See what changed

Enable --audit-log in both generators to record successful create, update, delete, and exposed custom-action calls. The generated admin home can display recent entries, including the actor when one is available. The API endpoint is /api/audit-logs.

Accept files and images

Configure a model's insert or update field with a file or image type. The generated backend can save uploads and expose them under /uploads/; the admin form provides a file picker and can show image thumbnails.

Built-in developer tools

Make generated files your own

Pass --templates-dir with a directory that mirrors a supported template path. The generator uses your file instead of the built-in fallback for that template.

bro-py-admin --models-dir ./models --output-dir ./generated --templates-dir ./my-templates

Supported overrides include admin Jinja templates, frontend CSS and JavaScript, and backend service/view templates. Preserve required generator replacement fields in backend templates.

Generate extra project files with plugins

A plugin is a Python file with a generate_files(context) function. It receives the parsed models, output directory, and command options, then returns output paths mapped to text content.

def generate_files(context):
    names = [model["class_name"] for model in context["models"]]
    return {"MODEL_INDEX.md": "# Models\n" + "\n".join(names)}

bro-py --models-dir ./models --output-dir ./generated --plugin ./plugins/model_index.py

You can repeat --plugin to load more than one. Plugins execute Python code on your machine with your user permissions; only use plugins you trust. A dry run previews changes but does not execute plugins.

Common command options

Run bro-py --help or bro-py-admin --help to see all options available in your installed version. Explicit positive or negative feature flags let you skip individual interactive questions.

Review the generated application

The generated README, dependency files, .env.example, Dockerfile, and WSGI entry point provide a starting point. They are not a substitute for checking your hosting environment.

• Keep .env and real secrets out of version control.
• Set production secret keys, HTTPS, database access, and logging.
• Review authentication rules, custom actions, uploaded file handling, and generated code.
• For multi-worker Socket.IO, configure Redis messaging and sticky sessions.
• Read the project's SECURITY_AND_LIMITS.md before deploying.