Scaffold stk Blueprint
Create a complete blueprint for $ARGUMENTS in the stk framework.
Current project state
Existing blueprints:
!ls -d stk/*/views.py 2>/dev/null | sed 's|stk/||;s|/views.py||'
Registered in app.py:
!grep -E 'register_blueprint|from stk\.' stk/app.py
Navigation items:
!grep -E 'title:|heading:' stk/static/js/navigation.js 2>/dev/null | head -20
Steps
Create the blueprint directory at stk/$ARGUMENTS/:
__init__.py (empty)
models.py with model(s) inheriting from Base
views.py with Blueprint, page route, and CRUD API endpoints
Models must follow stk conventions:
import dataclasses and use @dataclasses.dataclass decorator
- Import
Base from stk.extensions, NOT db
- Use
Column(Type) from sqlalchemy directly
- All relationships use
lazy="selectin"
- Include
to_dict() instance method
- Include
async from_dict(self, data) as instance method that mutates self (NOT a classmethod)
- Include
created_at = Column(DateTime, default=datetime.now, nullable=False)
Views must follow the real codebase patterns:
- ALL handlers are
async def
- Use
import orjson as json and return Response(json.dumps(data), content_type="application/json") for list endpoints
- Blueprint-level auth via
@bp.before_request with @auth_required("session") (add @roles_required("admin") if admin-only)
- DB access via
await g.db_session.execute(...) or await g.db_session.get(...)
- Frontend sends
{item: {...}}, extract with json_data.get("item", {})
- Wrap mutations in try/except with
await g.db_session.rollback() on error
- Log mutations:
await Activity.register(current_user.id, "Action", data)
- Return
{"message": "..."} for create/update/delete responses
- Use
PER_PAGE = 25 constant
- Use
log = logging.getLogger(__name__) for error logging
Create template at stk/templates/$ARGUMENTS/index.html or stk/templates/cms/$ARGUMENTS.html:
- Extend
layout.html
- Vue 3 Options API:
data(), methods, mounted(), NOT setup()
- Must include
mixins: [layoutMixin] and delimiters: config.delimiters
- Use
const vuetify = createVuetify(config.vuetifyConfig)
- Call
registerStkComponents(app) before app.use(vuetify).mount("#app")
- Use
v-data-table-server for lists
- Icons: Tabler Icons (
ti ti-*), e.g. ti ti-plus, ti ti-pencil, ti ti-trash, ti ti-x
- Pass server data via
<script type="application/json" id="...">{{ data|tojson|safe }}</script>
- Use
toRaw() from Vue when editing items: const {createApp, toRaw} = Vue
Register the blueprint in stk/app.py:
- Add import at top with other blueprint imports
- Add
app.register_blueprint(bp) in register_blueprints()
Add navigation entry in stk/static/js/navigation.js:
// Simple link (role is singular string, not array)
{ title: '$ARGUMENTS', icon: 'ti ti-<icon>', to: '/$ARGUMENTS', role: 'admin' },
// Or grouped with children
{
title: '$ARGUMENTS', icon: 'ti ti-<icon>', role: 'admin',
children: [
{ title: 'List', icon: 'ti ti-list', to: '/$ARGUMENTS' },
]
},
Generate Alembic migration:
- Run:
uv run quart db revision -m "add $ARGUMENTS tables"
- Review the generated migration for correctness
Verify:
- Run
uv run ruff check --fix . && uv run ruff format .
- Run
uv run python checks.py
Do NOT:
- Use
db.Model, db.Column, db.select(), or any Flask-SQLAlchemy patterns
- Use
from flask import ... or from flask_security import ...
- Use sync handlers (every route must be
async def)
- Use
jsonify() (return dicts or Response objects)
- Use
lazy="dynamic" on relationships (breaks async)
- Forget
await on DB operations
- Use Vue Composition API (
setup(), ref(), reactive()) — use Options API
- Use Material Design Icons — use Tabler Icons (
ti ti-*)
- Send raw data in POST — wrap in
{item: {...}}
- Forget
mixins: [layoutMixin] or registerStkComponents(app) in templates
1---2name: stk-blueprint-23description: Scaffold a new stk blueprint with models, views, templates, and Alembic migration. Use when creating a new feature module, adding a new section to the app, or scaffolding a blueprint.4---56# Scaffold stk Blueprint78Create a complete blueprint for `$ARGUMENTS` in the stk framework.910## Current project state1112Existing blueprints:13!`ls -d stk/*/views.py 2>/dev/null | sed 's|stk/||;s|/views.py||'`1415Registered in app.py:16!`grep -E 'register_blueprint|from stk\.' stk/app.py`1718Navigation items:19!`grep -E 'title:|heading:' stk/static/js/navigation.js 2>/dev/null | head -20`2021## Steps22231. **Create the blueprint directory** at `stk/$ARGUMENTS/`:24 - `__init__.py` (empty)25 - `models.py` with model(s) inheriting from `Base`26 - `views.py` with Blueprint, page route, and CRUD API endpoints27282. **Models must follow stk conventions:**29 - `import dataclasses` and use `@dataclasses.dataclass` decorator30 - Import `Base` from `stk.extensions`, NOT `db`31 - Use `Column(Type)` from sqlalchemy directly32 - All relationships use `lazy="selectin"`33 - Include `to_dict()` instance method34 - Include `async from_dict(self, data)` as **instance method** that mutates self (NOT a classmethod)35 - Include `created_at = Column(DateTime, default=datetime.now, nullable=False)`36373. **Views must follow the real codebase patterns:**38 - ALL handlers are `async def`39 - Use `import orjson as json` and return `Response(json.dumps(data), content_type="application/json")` for list endpoints40 - Blueprint-level auth via `@bp.before_request` with `@auth_required("session")` (add `@roles_required("admin")` if admin-only)41 - DB access via `await g.db_session.execute(...)` or `await g.db_session.get(...)`42 - Frontend sends `{item: {...}}`, extract with `json_data.get("item", {})`43 - Wrap mutations in try/except with `await g.db_session.rollback()` on error44 - Log mutations: `await Activity.register(current_user.id, "Action", data)`45 - Return `{"message": "..."}` for create/update/delete responses46 - Use `PER_PAGE = 25` constant47 - Use `log = logging.getLogger(__name__)` for error logging48494. **Create template** at `stk/templates/$ARGUMENTS/index.html` or `stk/templates/cms/$ARGUMENTS.html`:50 - Extend `layout.html`51 - Vue 3 Options API: `data()`, `methods`, `mounted()`, NOT `setup()`52 - Must include `mixins: [layoutMixin]` and `delimiters: config.delimiters`53 - Use `const vuetify = createVuetify(config.vuetifyConfig)`54 - Call `registerStkComponents(app)` before `app.use(vuetify).mount("#app")`55 - Use `v-data-table-server` for lists56 - Icons: Tabler Icons (`ti ti-*`), e.g. `ti ti-plus`, `ti ti-pencil`, `ti ti-trash`, `ti ti-x`57 - Pass server data via `<script type="application/json" id="...">{{ data|tojson|safe }}</script>`58 - Use `toRaw()` from Vue when editing items: `const {createApp, toRaw} = Vue`59605. **Register the blueprint** in `stk/app.py`:61 - Add import at top with other blueprint imports62 - Add `app.register_blueprint(bp)` in `register_blueprints()`63646. **Add navigation entry** in `stk/static/js/navigation.js`:65 ```javascript66 // Simple link (role is singular string, not array)67 { title: '$ARGUMENTS', icon: 'ti ti-<icon>', to: '/$ARGUMENTS', role: 'admin' },6869 // Or grouped with children70 {71 title: '$ARGUMENTS', icon: 'ti ti-<icon>', role: 'admin',72 children: [73 { title: 'List', icon: 'ti ti-list', to: '/$ARGUMENTS' },74 ]75 },76 ```77787. **Generate Alembic migration:**79 - Run: `uv run quart db revision -m "add $ARGUMENTS tables"`80 - Review the generated migration for correctness81828. **Verify:**83 - Run `uv run ruff check --fix . && uv run ruff format .`84 - Run `uv run python checks.py`8586## Do NOT:87- Use `db.Model`, `db.Column`, `db.select()`, or any Flask-SQLAlchemy patterns88- Use `from flask import ...` or `from flask_security import ...`89- Use sync handlers (every route must be `async def`)90- Use `jsonify()` (return dicts or Response objects)91- Use `lazy="dynamic"` on relationships (breaks async)92- Forget `await` on DB operations93- Use Vue Composition API (`setup()`, `ref()`, `reactive()`) — use Options API94- Use Material Design Icons — use Tabler Icons (`ti ti-*`)95- Send raw data in POST — wrap in `{item: {...}}`96- Forget `mixins: [layoutMixin]` or `registerStkComponents(app)` in templates