🚀 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.16.3.tar.gz (1.0 MB 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.16.3-py3-none-any.whl (650.5 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for swx_core-2.16.3.tar.gz
Algorithm Hash digest
SHA256 5b97a534b87e2c3c3989d0eb68a83949e2cec54f13f2e0971e19d64bc8963656
MD5 67bd084c07a96638e979adcd54c54016
BLAKE2b-256 eb31b5a724fd9f80384e720c5720ac1d01a9594bfc5d0bed200db1e35fbabb9e

See more details on using hashes here.

File details

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

File metadata

  • Download URL: swx_core-2.16.3-py3-none-any.whl
  • Upload date:
  • Size: 650.5 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.16.3-py3-none-any.whl
Algorithm Hash digest
SHA256 b261237d8953d0f900084332cdd96096843f4345d5675fde93b014964c29399a
MD5 272f2bccf72fe682618de44f409d1c60
BLAKE2b-256 85aee812625222af454edbadc76ba1999c598ce776af36c02e745ef1636bb7f3

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

This release

2.16.3 This release

2 files

2.16.2

2 files

2.16.1

2 files

2.15.6

2 files

2.15.5

2 files

2.15.4

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