About & Inspiration¶

Why SmallStack Exists¶

Django SmallStack was born from a simple observation: Django's admin interface is packed with excellent, production-ready components that most developers never use outside the admin itself.

Think about it. Django ships with:

• A complete authentication system with login, logout, password reset
• Polished form rendering and validation
• A clean, responsive theme with dark mode support
• Date pickers, autocomplete widgets, and rich form controls
• Consistent navigation patterns and breadcrumbs
• Message/notification systems

Yet when developers start a new Django project, the first thing many tutorials tell them is: "Install these third-party packages for authentication, forms, and styling."

The Controversy About Django Admin¶

There's ongoing debate in the Django community about using the admin in production. The concerns are valid:

• "The admin is for trusted users only"
• "Don't expose admin to end users"
• "Admin isn't meant for customer-facing features"

We agree. SmallStack doesn't expose Django's admin interface to regular users. Instead, it takes a different approach:

Use the admin's components, styles, and patterns without using the admin interface itself.

What We Borrow From Admin¶

The Theme System¶

Django admin's CSS is well-organized with CSS custom properties (variables) for colors, spacing, and effects. SmallStack builds on this foundation, extending it with:

• Consistent light and dark modes
• Mobile-responsive layouts
• Additional components for common UI patterns

Form Handling¶

Django's form system is powerful but often underutilized. SmallStack shows how to:

• Render forms with proper styling using built-in widgets
• Handle validation and display errors elegantly
• Use the same form patterns that power the admin

Authentication¶

Django's django.contrib.auth is battle-tested and secure. Instead of reaching for third-party packages, SmallStack demonstrates:

• Custom user models that extend Django's system
• Profile management with the built-in user framework
• Password reset flows using Django's views

Navigation & Layout¶

The sidebar, topbar, and breadcrumb patterns in SmallStack mirror Django admin's proven UX patterns, giving your app a familiar, professional feel.

What SmallStack Is NOT¶

• Not a CMS - It's a starting point, not a content management system
• Not an admin replacement - The Django admin still exists for staff users
• Not a framework - It's a project template you can customize freely

The Philosophy¶

1. Use what Django gives you - Before adding a package, check if Django already has it
2. Keep it simple - Avoid over-engineering; add complexity only when needed
3. Stay close to Django - Follow Django conventions so the ecosystem works for you
4. Production-ready defaults - Secure settings, proper static file handling, Docker support

Who Is This For?¶

• Developers who want a clean starting point without reinventing the wheel
• Teams tired of setting up auth, profiles, and theming from scratch
• Anyone who appreciates Django's built-in capabilities
• Projects that need a professional look without a heavy frontend framework

Built With Standard Django¶

SmallStack uses remarkably few dependencies:

Package	Purpose
Django 6.0+	The web framework
python-decouple	Environment variable management
Pillow	Image handling for profiles
markdown	Help system documentation

No heavy JavaScript frameworks. No complex build systems. Just Django doing what Django does best.

AI-Ready Development¶

SmallStack ships with AI skill files — structured documentation designed to help AI coding assistants quickly understand and extend the codebase. Whether you're using Claude, GitHub Copilot, or other AI tools, these skill files provide:

• Project conventions — Naming patterns, file organization, and coding standards
• Step-by-step guides — How to add apps, create templates, extend the theme
• Code examples — Working patterns for common tasks

When you ask an AI assistant to add a feature or fix a bug, pointing it to the relevant skill file in docs/skills/ gives it the context needed to generate code that fits your project's style.

This isn't about replacing developers — it's about accelerating development with AI as a collaborative tool. SmallStack was itself developed with AI assistance, and we've baked that workflow into the project.

Learn more: Extending with AI covers skill files, prompting strategies, and best practices for AI-assisted development.

Getting Involved¶

SmallStack is open source. If you share this philosophy of leveraging Django's strengths, we'd love your contributions:

• Report issues and suggest improvements
• Share how you've extended it for your projects
• Help improve the documentation

The goal is simple: Help developers build better Django apps faster, using tools that already exist.