Flask-AAS Example Plugin

A deliberately small but complete reference implementation for Flask-AAS Plugin API v1. It is intended to show the common pieces a real application plugin normally needs without copying the feature breadth of a product such as OpenAuto.

What this reference demonstrates

• static plugin.toml identity, API version, navigation label, and migration declaration;
• a plugin-owned Blueprint with public and administrator routes;
• host navigation registration without hard-coding package-directory names into UI labels;
• required configuration with a host-linked configuration endpoint;
• a plugin-managed persisted secret and clear_secrets() lifecycle behavior;
• plugin-owned SQLAlchemy models and an independent Alembic migration history;
• a small admin dashboard;
• ordinary settings forms and CSRF-protected POST handling;
• create/edit/enable/disable CRUD for one representative business object;
• host administrator authorization and host audit logging;
• a plugin-owned CLI surfaced through python manage.py plugin run example ...;
• host theme inheritance with normal page flow and no modal/overlay UI;
• focused tests owned by the plugin repository.

The example intentionally does not implement custom authentication, organizations, payments, background workers, a JavaScript application shell, or its own design system.

Repository / install model

This repository is independent of Flask-AAS. Under the current Plugin API v1 deployment model, install it into the host plugin package just like another source-distributed plugin:

cd /path/to/flask-aas
git clone <example-plugin-repository-url> app/plugins/example

The repository itself is the contents of app/plugins/example; it is not tracked as part of the Flask-AAS repository.

Then register the discovered manifest using the normal clean-install/seeding path:

python manage.py seed-db

Enable Application Plugins in Flask-AAS Site Settings and enable example from Admin -> Applications. Because this plugin owns database tables, advance its schema:

python manage.py plugin run example db upgrade

The migration history intentionally retains the original bundled Example schema as revision 0001 and advances the external reference implementation at 0002. Existing development databases stamped at the old 0001 can therefore upgrade normally; fresh installs bootstrap directly to the current 0002 schema.

Reload/restart the application so the newly migration-ready plugin can structurally register its routes. The Applications page will then expose Configure Application. Complete the Example Settings form; once the managed secret and ordinary settings are valid, normal application access and navigation become available.

URLs

/example/                     public example page
/example/admin/               plugin admin dashboard
/example/admin/settings       plugin configuration/settings
/example/admin/items          simple CRUD administration

CLI

Flask-AAS owns the top-level dispatcher and migration commands; this plugin contributes only its own commands:

python manage.py plugin run example --help
python manage.py plugin run example status
python manage.py plugin run example add-item "First item"
python manage.py plugin run example db current
python manage.py plugin run example db upgrade

Development rules illustrated here

• Plugin tables use the plugin_example_ namespace.
• Plugin schema changes belong to the plugin migration history, not Flask-AAS core.
• Plugin configuration readiness is derived from plugin state rather than toggled manually.
• Disabling a plugin clears only secrets owned by that plugin; ordinary configuration and business data remain in place.
• Administrative mutations use normal forms and caller-owned database transactions.
• Plugin pages inherit Flask-AAS presentation primitives. No custom CSS is required here.
• UI labels come from plugin metadata where appropriate; Python directory names are an installation detail, not product identity.