appkit-bpmn-server python.instructions.md

Python Development Instructions

Project Overview

This is a Python 3.13 project using:

• Reflex - Web framework for building reactive UIs
• FastAPI - High-performance web framework
• SQLAlchemy 2.0 - Database ORM
• Alembic - Database migrations
• Pydantic - Data validation
• uv - Package and project manager

Setup and Installation

# Install dependencies
make install
# or
uv sync

Development Workflow

Running the Application

# Start development server
make reflex
# or
uv run reflex run

# Start with debug logging
make reflex-debug
# or
uv run reflex run --loglevel=debug

# Production mode
make reflex-prod
# or
uv run reflex run --env prod

Testing

# Run tests
make test
# or
uv run pytest

# Run tests with coverage
uv run pytest --cov=app --cov=appkit_assistant --cov=appkit_commons --cov=appkit_imagecreator --cov=appkit_mantine --cov=appkit_ui --cov=appkit_user

Note: Tests should be written in tests/ directory following the pattern test_*.py.

Linting and Formatting

# Check code style
make check
# or
uv run ruff check .
uv run ruff format --check .

# Auto-fix linting issues
make lint
# or
uv run ruff check --fix .

# Format code
make format
# or
uv run ruff format .
uv run ruff check --fix .

Database Migrations

# Check current migration status
make alembic
# or
uv run alembic current

# Apply migrations
make db-migrate
# or
uv run alembic upgrade head

# View migration history
make db-migrate-history
# or
uv run alembic history

# Rollback one migration
make db-migrate-down
# or
uv run alembic downgrade -1

Code Style Guidelines

Logging

CRITICAL: Never use f-strings in logger calls. Use string formatting with parameters instead.

import logging

log = logging.getLogger(__name__)

# ✅ CORRECT
log.info("Loaded items: %d", count)
log.error("Failed to process user: %s", user_id)
log.debug("Processing request with params: %s, %s", param1, param2)

# ❌ INCORRECT - DO NOT USE
log.info(f"Loaded items: {count}")
log.error(f"Failed to process user: {user_id}")