🚀 SwX-API

Python FastAPI License: MIT Docker Ready CI/CD Made with ❤️

SwX-API is a production-ready, enterprise-grade FastAPI framework designed for building scalable SaaS applications. With comprehensive authentication, authorization, billing, rate limiting, audit logging, and more, it provides everything you need to build and deploy production applications.

Built with ❤️ for developers who value flexibility, security, and structure.

🎉 Framework Status: Production Ready v2.0.0

✨ Key Features

🔐 Security & Authentication

  • ✅ Domain Separation - Admin, User, and System domains completely isolated
  • ✅ OAuth2 + JWT - Secure token-based authentication with refresh tokens
  • ✅ Social Login - Google, Facebook, and other OAuth providers
  • ✅ Token Security - Audience validation, expiration, and revocation
  • ✅ Secrets Management - Secure handling of sensitive configuration

🛡️ Authorization & Access Control

  • ✅ Permission-First RBAC - Fine-grained access control with team scoping
  • ✅ Policy Engine (ABAC) - Attribute-based access control with conditions
  • ✅ Team-Scoped Permissions - Multi-tenant support with team isolation
  • ✅ Fail-Closed Security - Deny by default, explicit allow

💰 Billing & Entitlements

  • ✅ Feature Registry - Centralized feature management
  • ✅ Plan Management - Flexible subscription plans (Free, Pro, Team, Enterprise)
  • ✅ Entitlement Resolution - Automatic feature access checking
  • ✅ Usage Tracking - Quota and metered feature tracking
  • ✅ Stripe Integration - Payment processing support

⚡ Performance & Scalability

  • ✅ Async Model - Full async/await support for high performance
  • ✅ Rate Limiting - Plan-based rate limits with burst protection
  • ✅ Redis Caching - In-memory caching for improved performance
  • ✅ Background Jobs - Asynchronous job processing with retries
  • ✅ Connection Pooling - Optimized database connections with health checks

📊 Operations & Monitoring

  • ✅ Audit Logging - Immutable security and business event logs
  • ✅ Alerting System - Multi-channel alerts (Slack, Email, SMS, Logs)
  • ✅ Health Checks - Comprehensive health monitoring
  • ✅ Runtime Settings - Database-backed configuration management
  • ✅ Background Jobs - Job queue with retry logic and dead-letter queue

🛠️ Developer Experience

  • ✅ Modular Architecture - Clean separation of core and app code
  • ✅ Base Classes Pattern - BaseController, BaseService, BaseRepository for rapid development (v2.0)
  • ✅ SQLModel ORM - Type-safe database models
  • ✅ Alembic Migrations - Database version control
  • ✅ CLI Tools - swx command for scaffolding with --base flag for modern patterns
  • ✅ Comprehensive Documentation - 50+ documentation files
  • ✅ Testing Tools - Unit tests, integration tests, acceptance tests
  • ✅ Docker Ready - Complete Docker Compose setup

🆕 What's New in v2.0

BaseController / BaseService / BaseRepository

Reduce boilerplate by 80% with the new base classes pattern:

# v2.0 - Modern pattern (recommended)
from swx_core.controllers.base import BaseController
from swx_core.services.base import BaseService
from swx_core.repositories.base import BaseRepository

class ProductRepository(BaseRepository[Product]):
    def __init__(self):
        super().__init__(model=Product)
    # Automatic: find_by_id, find_all, create, update, delete, search, paginate...

class ProductService(BaseService[Product, ProductRepository]):
    def __init__(self):
        super().__init__(repository=ProductRepository())
    # Automatic: get, create, update, delete with events and validation hooks...

class ProductController(BaseController[Product, Create, Update, Public]):
    def __init__(self):
        super().__init__(model=Product, ...)
        self.register_routes()
    # Automatic: GET, POST, PUT, DELETE endpoints...

New Utilities

  • Unit of Work - Transaction management with automatic commit/rollback
  • Filter Builder - Fluent query filtering and sorting
  • Caching Decorators - @cached, @memoize for Redis operations
  • Rate Limiting - @rate_limit_by_ip, @rate_limit_by_user
  • Testing Utilities - ModelFactory, TestClientWithDB, assertions

CLI Improvements

# Generate resources with base classes (recommended)
swx make:resource Product --base

# Generate legacy patterns
swx make:resource Product

See Migration Guide for upgrading from v1.x.

📁 Project Structure

swx-api-latest-backend/
├── swx_core/              # Framework code (reusable)
│   ├── auth/              # Authentication (admin, user, system)
│   ├── cli/               # CLI commands
│   ├── config/            # Configuration
│   ├── controllers/       # BaseController (v2.0)
│   ├── services/          # BaseService (v2.0)
│   ├── repositories/      # BaseRepository (v2.0)
│   ├── database/          # Database setup and utilities
│   ├── middleware/        # Middleware (CORS, logging, rate limiting)
│   ├── models/            # Framework models (User, Role, Permission, etc.)
│   ├── rbac/              # RBAC system
│   ├── routes/            # Framework routes (admin, user, utils)
│   ├── security/          # Security utilities
│   ├── services/          # Framework services (billing, jobs, alerts, etc.)
│   └── utils/             # Utility functions (pagination, caching, filters...)
├── swx_app/               # Application code (your features)
│   ├── controllers/       # Application controllers
│   ├── models/            # Application models
│   ├── repositories/      # Application repositories
│   ├── routes/            # Application routes
│   └── services/          # Application services
├── migrations/            # Alembic migrations
├── docs/                  # Comprehensive documentation
│   ├── 04-core-concepts/
│   │   ├── BASE_CLASSES.md      # BaseController/BaseService/BaseRepository (NEW)
│   │   ├── UTILITIES.md         # All utility modules (NEW)
│   │   └── USAGE_EXAMPLES.md    # Complete usage examples (NEW)
│   └── 07-extending/
│       └── MIGRATION_GUIDE.md   # v1.x to v2.0 migration (NEW)
├── scripts/               # Utility scripts
├── Dockerfile             # Docker configuration
├── docker-compose.yml     # Docker Compose (development)
└── docker-compose.production.yml # Docker Compose (production)

🚀 Quick Start

Prerequisites

  • Python 3.10+
  • Docker & Docker Compose (recommended)
  • PostgreSQL 12+
  • Redis 6+

Installation

Option 1: Docker (Recommended)

# Clone repository
git clone <repository-url>
cd swx-api-latest-backend

# Copy environment file
cp .env.example .env

# Edit .env with your configuration
# Then start services
docker compose up --build

# Application will be available at:
# - API: http://localhost:8001/api
# - Docs: http://localhost:8001/docs
# - ReDoc: http://localhost:8001/redoc

Option 2: Local Development

# Clone repository
git clone <repository-url>
cd swx-api-latest-backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
# Or using uv (faster)
uv pip install -r requirements.txt

# Copy environment file
cp .env.example .env

# Run database migrations
alembic upgrade head

# Start development server
uvicorn swx_core.main:app --reload --host 0.0.0.0 --port 8001

Initial Setup

After starting the application:

  1. Seed System Data:

    python scripts/seed_system.py

  2. Verify Installation:

    curl http://localhost:8001/api/utils/health-check

  3. Access Documentation:

    • Swagger UI: http://localhost:8001/docs
    • ReDoc: http://localhost:8001/redoc

📚 Documentation

SwX-API includes comprehensive documentation covering all aspects of the framework:

Getting Started

Core Concepts (v2.0)

Security

Extending

📖 See Documentation Index for complete documentation structure.

🛠️ Development

CLI Commands

# Generate resources with base classes (v2.0 - recommended)
swx make:resource Product --base

# Generate resources with legacy patterns
swx make:resource Product

# Database migrations
swx db migrate
swx db revision -m "description"

# Code quality
swx format      # Format code
swx lint        # Lint code

# Interactive shell
swx tinker

📊 Example Usage

Base Classes (v2.0)

# Complete resource in minutes
from swx_core.controllers.base import BaseController
from swx_core.services.base import BaseService
from swx_core.repositories.base import BaseRepository
from swx_core.utils.mixins import FullModelMixin

# Model
class Product(FullModelMixin, table=True):
    name: str
    price: float

# Repository
class ProductRepository(BaseRepository[Product]):
    def __init__(self):
        super().__init__(model=Product)

# Service  
class ProductService(BaseService[Product, ProductRepository]):
    def __init__(self):
        super().__init__(repository=ProductRepository())

# Controller
class ProductController(BaseController[Product, ProductCreate, ProductUpdate, ProductPublic]):
    def __init__(self):
        super().__init__(
            model=Product,
            schema_public=ProductPublic,
            schema_create=ProductCreate,
            schema_update=ProductUpdate,
            prefix="/products",
        )
        self.register_routes()

# Automatic endpoints:
# GET    /products          - List with pagination
# GET    /products/{id}      - Get by ID
# POST   /products          - Create
# PUT    /products/{id}     - Update
# DELETE /products/{id}     - Delete

Authentication

# User domain authentication
from swx_core.security.dependencies import get_current_user

@router.get("/user/profile")
async def get_profile(user: User = Depends(get_current_user)):
    return user

Authorization

# Permission-based access
from swx_core.rbac.dependencies import require_permission

@router.get("/users", dependencies=[Depends(require_permission("user:read"))])
async def list_users():
    ...

Rate Limiting

from swx_core.utils.rate_limit import rate_limit_by_user

@router.get("/api/search")
@rate_limit_by_user(requests=100, window=60)  # 100 req/min
async def search(q: str):
    return await search_service.search(q)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • FastAPI for the excellent web framework
  • SQLModel for the ORM
  • All contributors and users

📞 Support

  • Documentation: docs/
  • Issues: GitHub Issues
  • Discussions: GitHub Discussions

Built with ❤️ for developers who value flexibility, security, and structure.

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.28.1)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ayindealiyu1 from gravatar.com ayindealiyu1

Credits

Author: SwX Team

License

MIT License (MIT)

Requires

Python <4.0, >=3.10

Provides Extra

ai billing dev extended jobs monitoring prod

Tags

api async fastapi framework jwt oauth rbac rest

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swx_core-2.15.4.tar.gz (971.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

swx_core-2.15.4-py3-none-any.whl (639.6 kB view details)

Uploaded Python 3

File details

Details for the file swx_core-2.15.4.tar.gz.

File metadata

  • Download URL: swx_core-2.15.4.tar.gz
  • Upload date:
  • Size: 971.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for swx_core-2.15.4.tar.gz
Algorithm Hash digest
SHA256 45e3eed73d347f1cded917bdd75fbab22309fb10c030152e1cdf4523cd17dcba
MD5 ce5226e09e83a66e4b35b219fd5b597b
BLAKE2b-256 9def2c9beb4395156a76930b2a0a9aa1f2c2867388f89472ff14a66124d41050

See more details on using hashes here.

File details

Details for the file swx_core-2.15.4-py3-none-any.whl.

File metadata

  • Download URL: swx_core-2.15.4-py3-none-any.whl
  • Upload date:
  • Size: 639.6 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for swx_core-2.15.4-py3-none-any.whl
Algorithm Hash digest
SHA256 84e0d1f0d76570e732152470155b1f8c28114ca73ac0ff42f252a81f238e246a
MD5 24124268d4e9bcdb60d723dd4d3adff4
BLAKE2b-256 24d9df2a9be7fa85f2f4942e03fa0c7684d2a89895c4c2eeb800be2320803249

See more details on using hashes here.

Release history Release notifications | RSS feed

2.28.1

2 files

2.28.0

2 files

2.27.0

2 files

2.26.16

2 files

2.26.15

2 files

2.26.14

2 files

2.26.13

2 files

2.26.12

2 files

2.26.11

2 files

2.26.10

2 files

2.26.9

2 files

2.26.8

2 files

2.26.6

2 files

2.26.5

2 files

2.26.4

2 files

2.26.3

2 files

2.26.2

2 files

2.26.1

2 files

2.26.0

2 files

2.25.3

2 files

2.25.2

2 files

2.25.0

2 files

2.24.0

2 files

2.23.5

2 files

2.23.4

2 files

2.23.3

2 files

2.23.2

2 files

2.23.1

2 files

2.23.0

2 files

2.22.10

2 files

2.22.9

2 files

2.22.8

2 files

2.22.6

2 files

2.22.5

2 files

2.22.4

2 files

2.22.3

2 files

2.22.2

2 files

2.22.1

2 files

2.22.0

2 files

2.21.4

2 files

2.21.3

2 files

2.21.2

2 files

2.21.0

2 files

2.20.2

2 files

2.20.1

2 files

2.20.0

2 files

2.19.16

2 files

2.19.15

2 files

2.19.13

2 files

2.19.12

2 files

2.19.11

2 files

2.19.9

2 files

2.19.8

2 files

2.19.7

2 files

2.19.6

2 files

2.19.5

2 files

2.19.3

2 files

2.19.2

2 files

2.19.1

2 files

2.19.0

2 files

2.18.0

2 files

2.17.0

2 files

2.16.6

2 files

2.16.5

2 files

2.16.4

2 files

2.16.3

2 files

2.16.2

2 files

2.16.1

2 files

2.15.6

2 files

2.15.5

2 files

This release

2.15.4 This release

2 files

2.14.3

2 files

2.14.2

2 files

2.14.1

2 files

2.14.0

2 files

2.13.0

2 files

2.12.0

2 files

2.11.0

2 files

2.10.1

2 files

2.9.0

2 files

2.8.0

2 files

2.7.45

2 files

2.7.44

2 files

2.7.43

2 files

2.7.42

2 files

2.7.41

2 files

2.7.40

2 files

2.7.39

2 files

2.7.38

2 files

2.7.37

2 files

2.7.36

2 files

2.7.35

2 files

2.7.34

2 files

2.7.33

2 files

2.7.32

2 files

2.7.30

2 files

2.7.29

2 files

2.7.28

2 files

2.7.26

2 files

2.7.25

2 files

2.7.24

2 files

2.7.23

2 files

2.7.22

2 files

2.7.21

2 files

2.7.20

2 files

2.7.19

2 files

2.7.18

2 files

2.7.17

2 files

2.7.16

2 files

2.7.15

2 files

2.7.14

2 files

2.7.13

2 files

2.7.12

2 files

2.7.11

2 files

2.7.10

2 files

2.7.8

2 files

2.7.7

2 files

2.7.6

2 files

2.7.5

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.7.0

2 files

2.6.0

2 files

2.5.0

2 files

2.4.0

2 files

2.3.16

2 files

2.3.15

2 files

2.3.14

2 files

2.3.13

2 files

2.3.12

2 files

2.3.11

2 files

2.3.10

2 files

2.3.9

2 files

2.3.8

2 files

2.3.7

2 files

2.3.6

2 files

2.3.5

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.1.7

1 file

2.1.6

2 files

2.1.5

2 files

2.1.4

2 files

2.1.3

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page