Sample Project Overview

The Django-CFG Sample Project is a comprehensive demonstration of all Django-CFG features and capabilities. This guide walks you through every aspect of the project, from setup to advanced features.

Architecture Overview

What You’ll Learn

• 🚀 Project Creation - Using django-cfg create-project
• ⚙️ Configuration Management - Type-safe settings with Pydantic v2
• 🗄️ Multi-Database Setup - Automatic routing and migrations
• 🎨 Admin Customization - Modern Unfold interface with dashboards
• 📊 API Documentation - Auto-generated OpenAPI/Swagger
• 🔐 Authentication System - OTP-based user management
• ⚡ Background Tasks - ReArq integration
• 📱 Service Integrations - Telegram
• 🐳 Docker Deployment - Production-ready containerization

Quick Start

1. Create the Sample Project

# Create new project
django-cfg create-project "My Django-CFG Demo"
 
# Navigate to project
cd my_django_cfg_demo
 
# The project is ready to run!
poetry run python manage.py runserver

2. Explore the Admin Interface

Visit http://127.0.0.1:8000/admin/

3. Check API Documentation

Visit http://127.0.0.1:8000/api/schema/swagger-ui/ for interactive API docs.

4. Monitor System Health

Visit http://127.0.0.1:8000/cfg/status/ for system health checks.

What’s Included

The sample project includes:

Multi-Database Architecture

Demonstrates sophisticated database routing with separate databases for different apps:

• Main Database - Users, sessions, admin
• Blog Database - Posts, comments, categories
• Shop Database - Products, orders, inventory

See Multi-Database Setup for details.

Modern Admin Interface

Built on the Unfold theme with:

• Custom dashboard with real-time metrics
• Organized navigation structure
• Beautiful UI with Material Design icons
• Responsive design for mobile access

See Admin Interface for customization options.

Comprehensive API

Auto-generated REST API with:

• OpenAPI/Swagger documentation
• JWT authentication
• Endpoint versioning
• Interactive testing interface

See API Documentation for endpoint details.

Service Integrations

Production-ready integrations with:

• Telegram - Real-time notifications and bot commands

See Service Integrations for configuration.

Background Task Processing

ReArq integration for:

• Asynchronous email sending
• Order processing
• Scheduled cleanup tasks
• Scalable worker management

See Background Tasks for task examples.

Project Structure Overview

my_django_cfg_demo/
├── 📁 api/                          # Configuration & Settings
│   ├── 🔧 config.py                 # Main Django-CFG configuration
│   ├── ⚙️ settings.py               # Auto-generated Django settings
│   ├── 🔗 urls.py                   # Root URL configuration
│   └── 📁 environment/              # Environment-specific configs
├── 📁 apps/                         # Django Applications
│   ├── 📝 blog/                     # Blog with posts & comments
│   ├── 🛒 shop/                     # E-commerce with products & orders
│   └── 👥 profiles/                 # User profiles & preferences
├── 📁 core/                         # Core utilities
├── 📁 db/                           # Database files (SQLite)
├── 📁 docker/                       # Docker configuration
├── 📁 static/                       # Static files
├── 📁 templates/                    # Django templates
├── 🎛️ manage.py                    # Django management script
└── 📋 pyproject.toml               # Poetry dependencies

For a detailed explanation of each directory, see Project Structure.

Configuration Architecture

The sample project showcases Django-CFG’s type-safe configuration system:

Configuration Code Example

from django_cfg import DjangoConfig, set_current_config
 
class DjangoCfgConfig(DjangoConfig):
    """Complete Django-CFG sample configuration."""
 
    # Project metadata
    project_name: str = env.app.name
    debug: bool = env.debug
    secret_key: str = env.secret_key
 
    # Multi-database configuration
    databases: Dict[str, DatabaseConfig] = {...}
 
    # Service integrations
    email: Optional[EmailConfig] = EmailConfig(...)
    telegram: Optional[TelegramConfig] = TelegramConfig(...)
 
    # Admin interface
    unfold: UnfoldConfig = UnfoldConfig(...)
 
# Create and register config instance
config = DjangoCfgConfig()
set_current_config(config)

For complete configuration details, see Configuration Setup.

Best Practices Demonstrated

1. Type-Safe Configuration

# ✅ Good: Type-safe configuration
class MyProjectConfig(DjangoConfig):
    email: EmailConfig = EmailConfig(...)
 
# ❌ Bad: Raw Django settings
EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'

2. Automatic Database Routing

# ✅ Good: Automatic routing
post = Post.objects.create(title="My Post")  # Goes to blog_db automatically
 
# ❌ Bad: Manual database selection
post = Post.objects.using('blog_db').create(title="My Post")

3. Module-Based Services

# ✅ Good: Module-based services
email = DjangoEmailService()  # Auto-configured
email.send_simple("Test", "Hello!", ["[email protected]"])
 
# ❌ Bad: Manual configuration
from django.core.mail import send_mail
send_mail("Test", "Hello!", "[email protected]", ["[email protected]"])

Next Steps

Now that you have an overview, explore these topics:

1. Project Structure - Understand the folder organization
2. Configuration Setup - Learn about configuration management
3. Multi-Database Setup - Master database routing
4. Admin Interface - Customize the admin dashboard
5. API Documentation - Explore the REST API
6. Authentication - Implement OTP authentication
7. Background Tasks - Process tasks asynchronously
8. Service Integrations - Connect external services
9. Deployment - Deploy to production with Docker

Related Documentation

• CLI Tools - Manage your project via CLI
• Configuration Guide - Advanced configuration
• Modules System - Available modules
• Built-in Apps - Authentication and more
• Integrations - External services

The sample project demonstrates the full power of Django-CFG - from simple setup to production deployment! 🚀