Flaxon ecosystem

Integration packages

Flaxon keeps integrations outside the core package. Each package is a normal Flaxon plugin: it is loaded once during startup, exposes a focused service on app.state, and leaves routes, authorization, and business rules in your application.

Load plugins at startup

PluginManager.load_plugin() is asynchronous. Register plugins from an @app.on_startup handler; request handlers can then safely access the service through app.state.

from flaxon import Flaxon

app = Flaxon("store")

@app.on_startup
async def load_integrations():
    # await app.plugins.load_plugin(...)
    pass

flaxon-sqlalchemy

Provides one async SQLAlchemy engine and async session factory at app.state.sqlalchemy. It creates the engine at startup and disposes it at shutdown.

pip install "flaxon-sqlalchemy[postgresql] @ git+https://github.com/aldanedev-create/flaxon-sqlalchemy.git"
# For SQLite instead: "flaxon-sqlalchemy[sqlite] @ git+https://github.com/aldanedev-create/flaxon-sqlalchemy.git"

import os

from flaxon import Flaxon
from flaxon_sqlalchemy import SQLAlchemyPlugin
from sqlalchemy import text

app = Flaxon("store")

@app.on_startup
async def load_database():
    await app.plugins.load_plugin(
        SQLAlchemyPlugin(os.environ["DATABASE_URL"])
    )

@app.get("/orders")
async def list_orders():
    async with app.state.sqlalchemy.session() as session:
        result = await session.execute(text("SELECT id FROM orders"))
        return {"orders": list(result.scalars())}

Use an async SQLAlchemy URL such as postgresql+asyncpg://… or sqlite+aiosqlite:///./app.db. Models, migrations, and transaction boundaries remain application responsibilities.

flaxon-stripe

Provides a configured Stripe gateway at app.state.stripe. It exposes the SDK as app.state.stripe.client and verifies incoming webhook signatures with verify_webhook().

pip install git+https://github.com/aldanedev-create/flaxon-stripe.git

import os

from flaxon import Flaxon
from flaxon.exceptions import BadRequest
from flaxon_stripe import StripePlugin

app = Flaxon("billing")

@app.on_startup
async def load_stripe():
    await app.plugins.load_plugin(
        StripePlugin(
            api_key=os.environ["STRIPE_SECRET_KEY"],
            webhook_secret=os.environ["STRIPE_WEBHOOK_SECRET"],
        )
    )

@app.post("/stripe/webhook")
async def stripe_webhook(request):
    signature = request.headers.get("stripe-signature")
    if signature is None:
        raise BadRequest("Missing Stripe signature")
    event = app.state.stripe.verify_webhook(await request.body(), signature)
    return {"received": event["id"]}

Keep Stripe keys outside source control. Make webhook handling idempotent and record or queue the event before returning success.

flaxon-s3

Provides Amazon S3-compatible object storage at app.state.s3, including custom endpoints such as MinIO, R2, or other S3-compatible services.

pip install git+https://github.com/aldanedev-create/flaxon-s3.git

import asyncio
import os

from flaxon import Flaxon
from flaxon_s3 import S3Plugin

app = Flaxon("uploads")

@app.on_startup
async def load_storage():
    await app.plugins.load_plugin(
        S3Plugin(
            bucket=os.environ["S3_BUCKET"],
            region_name=os.environ.get("AWS_REGION"),
            endpoint_url=os.environ.get("S3_ENDPOINT_URL"),
        )
    )

@app.post("/files")
async def upload_file(request):
    body = await request.body()
    await asyncio.to_thread(
        app.state.s3.upload_bytes,
        "incoming/report.pdf",
        body,
        content_type="application/pdf",
    )
    return {"key": "incoming/report.pdf"}

The S3 client is synchronous, so offload network calls with asyncio.to_thread() in async routes. Use server-controlled object keys, constrained IAM permissions, and content limits before reading uploads.

flaxon-postsql

Provides an asyncpg PostgreSQL pool at app.state.postsql. The pool opens at startup and closes at shutdown.

pip install git+https://github.com/aldanedev-create/flaxon-postsql.git

import os

from flaxon import Flaxon
from flaxon_postsql import PostSQLPlugin

app = Flaxon("catalog")

@app.on_startup
async def load_postgres():
    await app.plugins.load_plugin(
        PostSQLPlugin(os.environ["DATABASE_URL"], min_size=2, max_size=10)
    )

@app.get("/products")
async def list_products():
    rows = await app.state.postsql.fetch(
        "SELECT id, name FROM products WHERE category = $1 ORDER BY id",
        "books",
    )
    return {"products": [dict(row) for row in rows]}

Use $1, $2, and later positional parameters with asyncpg; never interpolate user input into SQL. Despite its package name, PostSQL is a PostgreSQL integration.

Additional official plugins

These packages are also part of the Flaxon ecosystem. They are independently versioned; use the package repository as the source of truth for options and compatibility, and load plugin packages from an async startup handler in the same way as the integrations above.

flaxon-ai

AI and LLM integration for Gemini, OpenAI, and local Flax/JAX models. Install pip install "flaxon-ai[all]", load FlaxonAIPlugin, then generate, chat, stream, or create embeddings through app.state.ai. Keep provider keys in environment variables and apply rate limits to public AI routes.

flaxon-mobile

Mobile device registration and FCM-oriented push notifications. Install pip install "flaxon-mobile[all]", configure FlaxonMobilePlugin with the FCM settings you use, and work with device registration and push delivery through app.state.mobile. Authenticate device registration and do not expose push sends to untrusted clients.

flaxon-oauth-google

Google OAuth 2.0 authorization-code flow. Install pip install flaxon-oauth-google, configure GoogleOAuthPlugin with a client ID, client secret, and registered redirect URI, then direct users to /auth/google/login. The callback must exactly match the URI registered in Google Cloud, and secrets must stay outside the repository.

flaxon-inertia

Inertia.js integration for React, Vue, and Svelte frontends. Install pip install flaxon-inertia, load InertiaPlugin with the root template and asset version, and render an Inertia page using the integration's inertia.render("Page", props) interface. Pair it with the matching Inertia client adapter in your frontend project.

flaxon-fyr

Fyr.js frontend integration. Install pip install flaxon-fyr, load FyrPlugin, and render a Fyr application from a route with request.app.state.fyr.render_app(...). The plugin supplies the Fyr CDN URL; your page still owns its JavaScript controller and HTML template.

flaxon-debug-toolbar

Development request inspection and optional Three.js visualizations. Install pip install "flaxon-debug-toolbar[three]" when you need its visuals, load DebugToolbarPlugin only for a debug environment, and never expose a debugging toolbar on a public production deployment.

flaxon-sentry

Sentry error and performance reporting. Install pip install flaxon-sentry, load SentryPlugin with the DSN, environment, and release, then use app.state.sentry_plugin for manual captures or breadcrumbs when needed. Use a non-development DSN only in the environment you intend to report from.

flaxon-pytest

Pytest fixtures and assertions for Flaxon applications. Install pip install flaxon-pytest in the test environment, then use fixtures such as flaxon_client, flaxon_async_client, and flaxon_websocket_client in test functions. It is a test helper package, not a runtime plugin to load on app.plugins.

Choose one database layer

Use flaxon-sqlalchemy when you want SQLAlchemy models, sessions, or SQLAlchemy's database portability. Use flaxon-postsql for direct, asyncpg-native PostgreSQL queries. Do not load both for the same database unless you intentionally manage separate pools and connection limits.

Deployment checklist

• Load credentials and URLs from the deployment environment or a secret manager.
• Use the exact package version you have tested after the first PyPI release.
• Start the application through flaxon run app:app so lifespan startup and shutdown run.
• Keep authorization, validation, retries, observability, and error handling in the application layer.