Architecture¶

If you want to understand how Shopyo actually works without wading through a sea of fluff, this is for you.

Core Philosophy¶

Shopyo is a modular wrapper around Flask. It doesn’t try to reinvent the wheel; it just gives the wheel a better axle and some decent rims. The goal is to make Flask applications modular by default, using a “Box and Module” system.

The “Box and Module” System¶

A Shopyo project is organized into modules. These modules are essentially Flask Blueprints on steroids.

Modules: The basic unit of functionality. Contains its own views, models, forms, and static files.
Boxes: A logical grouping of modules. Folder name must start with box__.

Project Structure¶

A typical Shopyo project looks like this:

/project_root
├── app.py          # The entry point. Defines create_app().
├── init.py         # The extension initializer. Defines db, login_manager, etc.
├── manage.py       # CLI entry point.
└── modules/        # Where the magic (code) happens.
    ├── box__default/
    │   ├── auth/
    │   └── settings/
    └── my_custom_module/

Initialization Flow¶

app.py: create_app() is called.
init.py: load_extensions(app) initializes Flask extensions (SQLAlchemy, Migrate, etc.).
Module Loading: Shopyo scans the modules/ directory. - It looks for info.json in each module to get metadata (URL prefix, etc.). - It registers a Blueprint for each module. - It imports models.py from each module automatically for discovery by Flask-Migrate.

Configuration¶

Shopyo uses a profile-based configuration system defined in config.py. Use the SHOPYO_CONFIG_PROFILE environment variable to switch between development, testing, and production.

Static Asset Collection¶

To maintain modularity while serving files efficiently, Shopyo uses the collectstatic command. This copies static files from individual modules into a global static/modules/ directory. Do not edit files in static/modules/ directly; they will be overwritten.

Database Management¶

Shopyo wraps Flask-Migrate. Use shopyo initialise for a fresh start or standard flask db commands for migrations. The shopyo clean command is there when you inevitably mess up your local database and just want to start over.