0.3.0

🚀 0.3.0: Major Architecture Overhaul: Multi-Backend Session Management & Comprehensive Documentation

📋 Overview

This release represents a complete architectural transformation of CRUDAdmin, introducing a robust multi-backend session management system, comprehensive testing infrastructure, and professional-grade documentation. This is a major version update that significantly enhances security, scalability, and developer experience.

✨ Major Changes Summary

🔄 Multi-Backend Session Management System

New Module: session/backends/

• 5 Storage Backends: Memory, Redis, Memcached, Database, and Hybrid
• Production-Ready: Horizontal scaling with Redis/Memcached
• Flexible Architecture: Abstract storage interface with pluggable backends
• Enhanced Features: User agent parsing, session persistence, automatic cleanup

# New fluent API for backend configuration
admin = CRUDAdmin(session=session, SECRET_KEY=key)
admin.use_redis_sessions("redis://localhost:6379")
admin.use_memcached_sessions(["localhost:11211"])

🛡️ Enhanced Security & Core Infrastructure

New Module: core/

• core/auth.py: Centralized authentication utilities
• core/rate_limiter.py: IP and username-based rate limiting
• Enhanced Security: CSRF protection, secure cookies, device fingerprinting
• IP Restrictions: Built-in middleware for network access control

📊 Session Architecture

Enhanced session/ Module

• session/storage.py: Abstract storage interface and factory
• session/user_agents_types.py: Advanced user agent parsing
• session/manager.py: Core session management with multi-device support
• Database Integration: Optional session persistence for audit requirements

🏗️ File Structure Transformation

New Core Infrastructure

crudadmin/core/
├── auth.py              # Authentication utilities  
└── rate_limiter.py      # Rate limiting implementation

crudadmin/session/backends/
├── memory.py           # In-memory storage (development)
├── redis.py            # Redis backend (production)
├── memcached.py        # Memcached backend (high-traffic)
├── database.py         # Database persistence (audit)
└── hybrid.py           # Combined memory + database

Enhanced Session Management

crudladmin/session/
├── storage.py          # Abstract storage interface
├── user_agents_types.py # Device fingerprinting
└── manager.py          # Enhanced session management

🧪 Comprehensive Testing Infrastructure

Before: 7 Test Files

tests/
├── test_admin_user_service.py
├── test_core_db.py  
├── test_crud_admin.py
├── test_crud_operations.py
├── test_event_service.py
├── test_session_manager.py
└── conftest.py

After: 15+ Test Files in Organized Structure

tests/
├── admin_user/
│   └── test_service.py
├── auth/
│   └── test_endpoints.py
├── core/
│   ├── test_db.py
│   └── test_rate_limiter.py
├── crud/
│   ├── test_admin.py
│   └── test_operations.py
├── event/
│   └── test_service.py
├── session/
│   ├── test_backends.py         # All 5 backends tested
│   ├── test_integration.py      # Cross-system integration
│   ├── test_manager.py         # Session manager logic
│   └── test_rate_limiter_integration.py
├── test_cache_headers.py
└── conftest.py

Testing Improvements:

• Comprehensive Test Cases across all modules
• Backend-Specific Tests for each storage implementation
• Integration Testing between systems
• Rate Limiting Tests with various scenarios
• Organized Structure for maintainability

📚 Complete Documentation Overhaul

Before: Basic Structure

docs/
├── usage/
│   ├── admin.md
│   ├── getting_started.md
│   ├── monitoring_maintenance.md
│   ├── overview.md
│   └── security_authentication.md
└── api/
    ├── admin_site.md
    ├── crud_admin.md
    ├── model_view.md
    └── overview.md

After: Professional Documentation Site

docs/
├── installing.md           # Step-by-step installation
├── quick-start.md         # 5-minute setup guide
├── usage/
│   ├── overview.md        # Learning progression
│   ├── configuration.md   # Detailed configuration
│   ├── adding-models.md   # Model management
│   ├── admin-users.md     # User management
│   ├── interface.md       # UI guide with screenshots
│   └── common-patterns.md # real-world examples
├── advanced/
│   └── overview.md        # Production features
├── api/
│   ├── events.md          # Event system API (305 lines)
│   ├── session.md         # Session management API (486 lines)
│   ├── admin_site.md      # Enhanced API docs
│   ├── crud_admin.md      # Updated API reference
│   ├── model_view.md      # Complete ModelView docs
│   └── overview.md        # API navigation
└── assets/screenshots/    # 13 UI screenshots
    ├── dashboard-layout.png
    ├── model-list-page.png
    ├── create-form-example.png
    └── ... (10 more)

Documentation Features:

• Extensive New Content with detailed examples
• Interactive Examples with copy-paste code
• Real-World Patterns: E-commerce, blog, enterprise examples
• Visual Guides: 13 screenshots of admin interface
• API Reference: Complete function documentation
• Production Guides: Security, scaling, deployment

🔧 Backend Performance Comparison

Backend	Use Case	Performance	Persistence	Scalability	Memory Usage
Memory	Development	Fastest	No	Single Instance	High
Redis	Production	Very Fast	Optional	High	Low
Memcached	High-Traffic	Very Fast	No	High	Low
Database	Audit/Compliance	Good	Yes	Medium	Medium
Hybrid	Enterprise	Fast	Yes	High	Medium

🛠️ Breaking Changes & Migration

Simplified Migration

# Before: Basic setup
admin = CRUDAdmin(session=session, SECRET_KEY=key)

# After: Same basic setup works + new capabilities
admin = CRUDAdmin(session=session, SECRET_KEY=key)

# New: Production-ready backends
admin.use_redis_sessions("redis://localhost:6379")
admin.use_database_sessions(cleanup_interval_minutes=30)

Key Changes

• JWT Removed: Replaced with secure session-based authentication
• Enhanced Security: CSRF protection, rate limiting, IP restrictions
• New Dependencies: Optional Redis/Memcached support
• Improved Performance: Cached sessions reduce database load

📦 New Dependencies & Installation

Optional Dependencies

[project.optional-dependencies]
redis = ["redis>=4.0.0"]
memcached = ["pymemcache>=4.0.0"]

Installation Options

# Basic installation (memory backend)
pip install crudadmin

# Production with Redis
pip install "crudadmin[redis]"

# High-traffic with Memcached  
pip install "crudadmin[memcached]"

# Full installation
pip install "crudadmin[redis,memcached]"

🎯 Performance & Security Improvements

Performance

• ⚡ Faster Authentication: Session validation vs JWT verification
• 📊 Reduced Database Load: Cached sessions reduce queries
• 🔄 Background Cleanup: Automatic session expiration
• 💾 Memory Efficient: Configurable storage backends

Security

• 🛡️ CSRF Protection: Built-in token generation/validation
• 🚦 Rate Limiting: Login attempt protection
• 🌐 IP Restrictions: Network-based access control
• 🔒 Secure Cookies: HttpOnly, Secure, SameSite
• 📱 Device Tracking: Enhanced user agent parsing

🧪 Testing & Quality

# Run all tests
pytest tests/ -v

# Test specific backend
pytest tests/session/test_backends.py -k redis

# Coverage report
pytest tests/ --cov=crudadmin --cov-report=html

Quality Metrics:

• Comprehensive Test Coverage across all modules
• Type Hints: Complete type annotation coverage
• Documentation: Every API function documented
• Examples: Real-world usage patterns included

🔮 Foundation for Future Features

This architectural overhaul enables:

• Role-Based Access Control (RBAC)
• Advanced Session Analytics
• Custom Authentication Providers
• Enhanced Audit Logging
• Multi-Tenant Support
• Horizontal Scaling

📖 Resources

• 📚 Full Documentation: https://benavlabs.github.io/crudadmin/
• 🚀 Quick Start Guide: Get running in 5 minutes
• 💡 Common Patterns: Real-world implementation examples
• 🔧 API Reference: Complete function documentation

---

Summary: This PR transforms CRUDAdmin from a basic admin interface into a production-ready, scalable admin system with enterprise-grade features, comprehensive documentation, and extensive testing coverage.

What's Changed

• Major Architecture Overhaul by @igorbenav in #4
• add test action by @igorbenav in #5

Full Changelog: v0.2.0...v0.3.0

0.2.0

What's Changed

• Remove jwt bug fixes by @igorbenav in #2
• update pyproject to 0.2.0 by @igorbenav in #3

Full Changelog: v0.1.1...v0.2.0

0.1.1

Full Changelog: v0.1.0...v0.1.1

0.1.0

CRUDAdmin

Modern admin interface for FastAPI with built-in authentication, event tracking, and security features

---

CRUDAdmin is a robust admin interface generator for FastAPI applications, offering secure authentication, comprehensive event tracking, and essential monitoring features. Built on top of FastCRUD and SQLAlchemy, it helps you create production-ready admin panels with minimal configuration.

Documentation: https://igorbenav.github.io/crudadmin/

Warning

CRUDAdmin is still experimental.

---

Features

• 🔒 Session-based Authentication: Secure session management with inactivity timeouts and concurrent session limits
• 🛡️ Built-in Security: IP restrictions, HTTPS enforcement, and secure cookie handling
• 📝 Event Tracking: Comprehensive audit logs for all admin actions with user attribution
• 🏥 Health Monitoring: Real-time system status dashboard with key metrics
• 📊 Auto-generated Interface: Creates admin UI directly from your SQLAlchemy models
• 🔍 Smart Filtering: Type-aware field filtering and efficient search
• 🌗 Modern UI: Clean interface with dark/light theme support

Requirements

Before installing CRUDAdmin, ensure you have:

• FastAPI: Latest version for the web framework
• SQLAlchemy: Version 2.0+ for database operations
• Pydantic: Version 2.0+ for data validation

Installing

pip install crudadmin

Or using poetry:

poetry add crudadmin

Usage

CRUDAdmin offers a straightforward way to create admin interfaces. Here's how to get started:

Define Your Models and Schemas

models.py

from sqlalchemy.orm import DeclarativeBase
from sqlalchemy import Column, Integer, String

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String, unique=True)
    email = Column(String)
    role = Column(String)

schemas.py

from pydantic import BaseModel, EmailStr

class UserCreate(BaseModel):
    username: str
    email: EmailStr
    role: str = "user"

class UserUpdate(BaseModel):
    email: EmailStr | None = None
    role: str | None = None

Set Up the Admin Interface

main.py

from contextlib import asynccontextmanager
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from crudadmin import CRUDAdmin
import os

# Database setup
engine = create_async_engine("sqlite+aiosqlite:///app.db")
session = AsyncSession(engine)

# Create admin interface
admin = CRUDAdmin(
    session=session,
    SECRET_KEY=os.environ.get("ADMIN_SECRET_KEY"),
    initial_admin={
        "username": "admin",
        "password": "secure_password123"
    }
)

# Add models to admin
admin.add_view(
    model=User,
    create_schema=UserCreate,
    update_schema=UserUpdate,
    allowed_actions={"view", "create", "update"}
)

# Setup FastAPI with proper initialization
@asynccontextmanager
async def lifespan(app: FastAPI):
    # Initialize database tables
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    
    # Initialize admin interface
    await admin.initialize()
    yield

# Create and mount the app
app = FastAPI(lifespan=lifespan)
app.mount("/admin", admin.app)

Enable Event Tracking

admin = CRUDAdmin(
    session=session,
    SECRET_KEY=SECRET_KEY,
    track_events=True,
    admin_db_url="postgresql+asyncpg://user:pass@localhost/admin_logs"
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    await admin.initialize()  # Creates event tracking tables
    yield

Configure Security Features

admin = CRUDAdmin(
    session=session,
    SECRET_KEY=SECRET_KEY,
    # Security settings
    allowed_ips=["10.0.0.1"],
    allowed_networks=["192.168.1.0/24"],
    secure_cookies=True,
    enforce_https=True,
    # Session settings
    max_sessions_per_user=5,
    session_timeout_minutes=30
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    await admin.initialize()  # Initializes security features
    yield

Current Limitations (coming soon)

• No file upload support yet
• No custom admin views (model-based only)
• No custom field widgets
• No SQLAlchemy relationship support
• No export functionality

Similar Projects

• Django Admin: The inspiration for this project
• Flask-Admin: Similar project for Flask
• Sqladmin: Another FastAPI admin interface

License

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

Contact

Igor Benav – @igorbenav – [email protected]
github.com/igorbenav