quickscale-core 0.75.0

Core scaffolding and utilities for QuickScale Django project generator

🚀 QuickScale

You are here: QuickScale README (Project Overview) Related docs: Start Here | Glossary | Decisions | User Manual

---

QuickScale: Compose your Django SaaS.

QuickScale is a composable Django framework for building client SaaS applications. Start with a stable core, add reusable modules, customize themes, and deploy faster—while maintaining the flexibility to create commercial extensions and build a community ecosystem.

---

What is QuickScale?

QuickScale is a Django project generator that creates production-ready SaaS applications with one command. Designed for solo developers and development agencies, it gives you:

• Production-ready foundations: Docker, PostgreSQL, testing, CI/CD, and security out-of-the-box
• One-command deployment: Deploy to Railway with quickscale deploy railway
• Full ownership: Generated projects are 100% yours to customize—no vendor lock-in
• Standardized stack: Build multiple client projects faster with consistent best practices

🧭 Future Vision: QuickScale will evolve to support reusable modules and themes. Today it's a personal toolkit; tomorrow it becomes a community platform when demand emerges. Read the full evolution strategy.

Documentation Guide

Start here for your needs:

• 📖 New user? You're in the right place. This README shows you what QuickScale is and how to get started.
• 🔧 Need commands? See user_manual.md for all commands and workflows
• 🚀 Deploying to Railway? See railway.md for Railway deployment guide
• 📋 Planning a feature? Check decisions.md for the authoritative MVP scope and technical rules
• 🗓️ Timeline & tasks? See roadmap.md
• 🏗️ Project structure? See scaffolding.md for complete directory layouts
• 🎯 Why QuickScale? See quickscale.md for competitive positioning

Quick Reference:

• MVP = Phase 1 (Personal Toolkit)
• Post-MVP = Phase 2+ (Modules & Themes)
• Generated Project = Output of quickscale plan + quickscale apply

See decisions.md - Glossary section for complete terminology and Single Source of Truth reference

Primary Use Cases (MVP):

• Solo Developer: Build client projects faster with production-ready foundations
• Development Agency: Standardize your tech stack across client engagements

Future Use Cases (Post-MVP):

• Commercial Extension Developer: Create and sell premium modules/themes
• Open Source Contributor: Extend the ecosystem with modules and themes

Development Flow

1. quickscale plan myapp → Interactive configuration wizard
2. cd myapp → Navigate to your project directory
3. quickscale apply → Generates production-ready Django project
4. Add your custom Django apps and features
5. Build your unique client application
6. Deploy to Railway with quickscale deploy railway (or use standard Django deployment)

quickscale.yml now uses explicit identity fields:

• project.slug: filesystem/service slug (for directory names)
• project.package: Python package/import name (for Django module paths)

ℹ️ The MVP Feature Matrix is the single source of truth for what's in or out.

What You Get

Running quickscale plan myapp && quickscale apply generates a production-ready Django project with:

• ✅ React + shadcn/ui frontend (TypeScript, Vite, Tailwind CSS) — NEW in v0.74.0
• ✅ Docker setup (development + production)
• ✅ PostgreSQL configuration
• ✅ Environment-based settings (dev/prod split)
• ✅ Security best practices (SECRET_KEY, ALLOWED_HOSTS, etc.)
• ✅ Testing infrastructure (pytest + factory_boy)
• ✅ CI/CD pipeline (GitHub Actions)
• ✅ Code quality hooks (ruff format + ruff check)
• ✅ Advanced quality analysis (dead code detection, complexity metrics, duplication)
• ✅ Poetry for dependency management
• ✅ One-Command Deployment: Deploy to Railway with quickscale deploy railway - fully automated setup

Alternative: Use quickscale plan myapp --theme showcase_html for pure HTML/CSS (simpler projects).

See the complete project structure: scaffolding.md - Generated Project Output

The generated project is yours to own and modify - no vendor lock-in, just Django best practices.

Why QuickScale vs. Alternatives?

✅ Faster than Cookiecutter - One command vs. 30+ interactive prompts ✅ More flexible than SaaS Pegasus - Open source with full code ownership ($0 vs. $349+) ✅ Simpler than building from scratch - Production-ready in 5 minutes vs. days of setup ✅ Railway deployment automation - Competitors require manual platform configuration

QuickScale is a development accelerator, not a complete solution. You start with production-ready foundations and build your unique client application on top.

See competitive_analysis.md for detailed comparison with SaaS Pegasus and Cookiecutter.

---

Installation

QuickScale can be installed in two ways:

Method 1: Install from PyPI (Recommended)

Quick install:

pip install quickscale

Or with Poetry:

poetry add quickscale

Then use directly:

quickscale plan myapp
cd myapp
quickscale apply

Method 2: Install from Source

For those who prefer building from source:

git clone https://github.com/Experto-AI/quickscale.git
cd quickscale
./scripts/install_global.sh

Then use directly:

quickscale plan myapp
cd myapp
quickscale apply

Both methods use the same command syntax: quickscale plan, quickscale apply, etc.

---

For Contributors

If you want to contribute to QuickScale development, see the Development Guide for setup instructions.

---

🚀 5-Minute Quickstart

Want to see QuickScale in action right now? Here's the fastest path to a working Django SaaS:

# 1. Install QuickScale
./scripts/install_global.sh

# 2. Create your project configuration
quickscale plan myapp
# → Accept defaults: theme (showcase_react), no modules, Docker enabled

# 3. Generate and enter the project
cd myapp
quickscale apply
# → Docker services auto-start! (default: docker.start=true)

# 4. Setup and verify
quickscale manage migrate
quickscale manage createsuperuser
quickscale ps  # Check services are running

# 5. Open http://localhost:8000

That's it! 🎉 You now have a production-ready Django SaaS running with Docker + PostgreSQL.

Note: Services started automatically during quickscale apply. No need to run quickscale up manually!

Prefer native Python? After step 3, run:

poetry install
poetry run python manage.py migrate
poetry run python manage.py runserver
# Open http://localhost:8000

---

Understanding Docker Auto-Start

When does quickscale apply start Docker automatically?

✅ Services auto-start (no quickscale up needed):

• First-time project generation
• When docker.start: true in quickscale.yml (default)
• When --no-docker flag is NOT used

❌ Manual start required (quickscale up needed):

• You set docker.start: false during quickscale plan wizard
• After stopping services with quickscale down
• When running quickscale apply --no-docker
• Adding modules to existing project (incremental apply)

Example - No manual start needed:

quickscale plan myapp  # Accept defaults (docker.start: true)
cd myapp
quickscale apply       # ← Docker services auto-start!

# Already running - just check status:
quickscale ps
curl http://localhost:8000  # ✅ Works immediately

Example - Manual start needed:

quickscale plan myapp
# During wizard, set: "Docker start? [Y/n]: n"
cd myapp
quickscale apply       # Services do NOT start

# Must start manually:
quickscale up

Docker configuration options in quickscale.yml:

docker:
  start: true   # Auto-start services during apply?
  build: true   # Rebuild images? (slower but ensures latest)

• start: true + build: true → Full rebuild + start (slowest, most reliable)
• start: true + build: false → Start with cached images (faster)
• start: false → Manual control with quickscale up

Need more details? See Docker Workflows Guide for comprehensive scenarios and troubleshooting.

---

Full Documentation & Setup

# Install QuickScale globally
./scripts/install_global.sh

# Create a configuration interactively
quickscale plan myapp
# → Select theme, modules, Docker options
# → Generates quickscale.yml in myapp/ directory

# Navigate to project and execute the configuration
cd myapp
quickscale apply

Choose your development workflow:

Option 1: Docker (Recommended for production parity)

# Start all services (backend + database)
quickscale up

# Run migrations
quickscale manage migrate

# Create superuser
quickscale manage createsuperuser

# View logs
quickscale logs -f backend

# Open a shell in the container
quickscale shell

# Stop services
quickscale down

Visit http://localhost:8000 - Your app is running in Docker with PostgreSQL!

Option 2: Native Poetry (Simpler for quick testing)

# Install dependencies
poetry install

# Run migrations
poetry run python manage.py migrate

# Start development server
poetry run python manage.py runserver

Visit http://localhost:8000 - Your app is running natively!

For complete command reference and workflows, see the user_manual.md.

Code Quality Analysis

QuickScale includes comprehensive code quality checks:

# Run quality analysis
./scripts/check_quality.sh

# View reports
cat .quickscale/quality_report.md     # Human-readable
cat .quickscale/quality_report.json   # Machine-readable

Detects:

• Dead code (unused imports, functions, variables)
• High complexity (cyclomatic complexity >10)
• Large files (>500 lines warning, >1000 error)
• Code duplication (>6 similar lines)

Exit codes: 0 (clean), 1 (warnings), 2 (critical)

Learn More

• decisions.md - Technical specifications and implementation rules
• quickscale.md - Strategic vision and competitive positioning
• competitive_analysis.md - Comparison vs SaaS Pegasus and alternatives
• roadmap.md - Development roadmap and implementation plan
• user_manual.md - Commands and workflows
• contributing.md - Development workflow and coding standards