Core Concepts

The Problem We Solve

Traditional Django Admin Pain Points

The gap: Django Admin is great for 90% of tasks, but hits a ceiling for complex requirements.

The django-cfg Solution

Three-in-One Architecture

One codebase, three interfaces:

• 🌐 Public (/) - Marketing, landing pages
• 👤 User Dashboard (/private) - User features
• ⚙️ Admin Panel (/admin) - Management interface

Dual Admin Strategy

Best of Both Worlds

When to Use Each Tab

Automatic API Generation

Zero-Config TypeScript Clients

What You Get

// ✅ Auto-generated from Django models
import { OrdersClient, Order } from '@/api/generated/orders';
 
const client = new OrdersClient();
 
// ✅ Full TypeScript support
const orders: Order[] = await client.list();
 
// ✅ Type-safe parameters
const order = await client.get(123);
 
// ✅ Validated payloads
await client.create({
  title: "New Order",
  price: 99.99,
  // ❌ TypeScript error if invalid fields
});

Zero manual work - types stay in sync with Django automatically!

Authentication Flow

Seamless JWT Integration

Zero configuration needed - authentication “just works”!

Development vs Production

Auto-Detection Magic

How it works:

1. Django checks if DEBUG=True
2. Quick socket test (0.1s) to see which ports are open:
   • Port 3000 available → Tab 2 shows dev server ✅
   • Port 3001 available → Tab 1 shows dev server ✅
3. No env variables needed - automatic detection!

Deployment Architecture

ZIP-Based Distribution

Why ZIP Instead of Direct Copy?

Winner: ZIP! Smaller images, faster builds, one-time extraction cost.

Theme Synchronization

Cross-iframe Communication

Bidirectional sync:

• Django changes theme → Next.js updates ✅
• Next.js changes theme → Django updates ✅

File Structure Philosophy

Monorepo Organization

django_admin/                    # ONE Next.js project
├── apps/
│   └── admin/
│       ├── pages/
│       │   ├── index.tsx        # 🌐 Public: Landing page
│       │   ├── auth.tsx         # 🌐 Public: Login
│       │   ├── legal/           # 🌐 Public: Terms, Privacy
│       │   │   ├── privacy.tsx
│       │   │   └── terms.tsx
│       │   ├── private/         # 👤 User Dashboard
│       │   │   ├── index.tsx
│       │   │   ├── profile.tsx
│       │   │   └── payments.tsx
│       │   └── admin/           # ⚙️ Admin Panel
│       │       ├── index.tsx
│       │       ├── crypto.tsx
│       │       └── trading.tsx
│       │
│       └── src/
│           ├── components/      # 🔁 SHARED across all
│           │   ├── ui/
│           │   └── forms/
│           ├── layouts/         # 🔁 SHARED layouts
│           │   ├── PublicLayout.tsx
│           │   ├── PrivateLayout.tsx
│           │   └── AdminLayout.tsx
│           └── api/generated/   # 🔁 SHARED API clients
│               ├── orders/
│               └── profiles/

Key insight: Everything is shared - write once, use everywhere!

Scalability Model

From Startup to Enterprise

Growth path:

1. Start simple - Use built-in admin (Tab 1)
2. Add features - Build custom UI (Tab 2)
3. Scale up - Multiple Next.js apps (future)

No migration, no rewrites - just progressive enhancement!

Comparison Matrix

vs Other Solutions

Core Principles

1. Convention over Configuration

# All you need:
nextjs_admin=NextJsAdminConfig(
    project_path="../django_admin",
)
# Everything else has smart defaults!

2. Progressive Enhancement

Start with basics → Add features → Scale up

No big rewrites, no migrations.

3. Zero Lock-in

// It's just Next.js + Django
// No proprietary APIs
// Standard tech stack
// Easy to eject if needed

4. Developer Experience First

• Hot reload in development
• Auto-generated types from Django
• Instant feedback loops
• Zero configuration magic

Real-World Example

E-commerce Platform Evolution

Timeline:

• Day 1-30: Built-in admin for products (Tab 1)
• Day 31-75: Custom sales dashboard (Tab 2)
• Day 76-105: Real-time analytics with WebSocket
• Day 106+: Scale with multiple admins

Total cost: $0 (open source) Total rewrites: 0 (incremental) Developer happiness: 💯

Next Steps

Now that you understand the why and how, let’s get practical:

Philosophy