# django-saas-starter

A production-ready Cookiecutter template for building Django SaaS apps fast.

- **Stack:** Django 6.0.5 + Python 3.14.5 + Tailwind + HTMX + Alpine.js
- **Pragmatic defaults:** auth, payments (optional), email, API, landing pages, and optional pages-owned blog/docs content
- **Deployment-ready:** Docker Compose (local + prod), Render, Fly.io, GitHub Actions (CapRover), and optional DigitalOcean App Platform

## Quickstart

```bash
cookiecutter git@github.com:rasulkireev/django-saas-starter.git
```

Then follow the generated project’s `README.md` for local development + deployment.

Important: in generated projects, run `uv run python manage.py makemigrations` (without app labels) before feature work so all app model changes are captured.

## What you get (high level)

### Core
- ✅ Django 6.0.5
- ✅ Python 3.14.5
- ✅ Environment variables via **django-environ**

### Auth
- ✅ User auth via **django-allauth**
- ✅ Passkey sign in + sign up via **django-allauth MFA** with email-code verification
- ✅ Passkey MFA with recovery-code fallback
- ❓ Social auth via **django-allauth**
  - ❓ Google (preconfigured)
  - ❓ GitHub (preconfigured)

### Frontend
- ✅ **Node.js 24.15.0 LTS** for frontend builds
- ✅ **Tailwind CSS** for styling
- ✅ **HTMX** for server-rendered UI interactions
- ✅ **Alpine.js** for local browser state
- ✅ Minimal Tailwind CLI/staticfiles asset pipeline
- ✅ Optional keyboard shortcut navigation, enabled by default
- ✅ SEO-friendly templates (meta tags, JSON-LD schema, OG images)
- ✅ Bundled `.agents/skills/frontend-ui-quality` guidance for generated Django/Tailwind UI quality checks
- ✅ Bundled `.agents/skills/django-htmx` guidance for AI agents working on Django-native interactivity
- ✅ Root `DESIGN.md` based on Google Labs Code's DESIGN.md format for tool-neutral human/AI design guidance

### Pages & content
- ✅ Landing + pricing + auth pages + sitemap
- ❓ User-facing blog managed by the Pages app
- ❓ User-facing docs content managed by the Pages app

### API
- ✅ API foundation via **django-ninja**
- ✅ Auth modes included (session, token, superuser)

### Database & storage
- ✅ Postgres 18 Docker images preconfigured
- ✅ Redis 8.6.3 Docker image preconfigured
- ✅ `pgvector` enabled
- ✅ `pg_stat_statements` enabled
- ❓ S3-compatible media storage (includes Minio for local + prod)

### Email & communication
- ✅ Email via **Anymail** + **Mailgun** (Mailhog for local)
- ✅ Styled UI message component
- ❓ MJML for email templating
- ❓ Apprise for internal/admin notifications to Slack or other channels

### Dev experience
- ✅ Python dependency management with **uv** and a generated `uv.lock`
- ✅ Docker Compose (local + prod)
- ✅ Terminal-first local development path without Docker for humans and AI agents
- ✅ Agent-friendly Compose service targets with configurable local ports for multi-repo work
- ✅ PGSandbox MCP guidance for disposable local Postgres testing from AI agents
- ✅ Fly.io app config (`fly.toml`) with web + worker process groups
- ✅ Makefile helpers
- ✅ pytest
- ✅ Pre-commit: ruff + djlint
- ✅ Lockfile-backed npm installs and frontend linting in generated CI
- ✅ Generated CI split into parallel Python quality, frontend, and pytest jobs
  with pytest-only settings for local cache/media/task isolation
- ✅ Generated `docs/quality.md` command matrix plus Makefile quality targets
  for local CI and touched-area checks
- ✅ Generated high-risk coverage reporting target with a configurable
  `COVERAGE_FAIL_UNDER` baseline
- ✅ `pyscn` static analysis Makefile targets + CI gate
- ✅ Automated deploy to **CapRover** via **GitHub Actions**
- ❓ Automated deploy to **DigitalOcean App Platform** via `.do/app.yaml` + **GitHub Actions**
- ❓ Optional CI workflow (runs pre-commit, ESLint, frontend build, `pyscn`,
  Django checks, and pytest on PRs and pushes to main)

### Observability & analytics
- ✅ Python stdlib logging (console in dev, structured JSON in prod)
- ✅ Canonical privacy-aware request/job/domain event fields for APM portability
- ❓ Sentry
- ❓ Healthcheck endpoint
- ❓ PostHog product analytics and batched OTLP log export

### AI
- ✅ Tool-neutral `DESIGN.md` design source of truth for humans and AI coding agents
- ✅ Tool-neutral `AGENTS.md` workflow for coding agents
- ✅ Tool-neutral generated `docs/quality.md` local CI and touched-area command
  contract for humans and AI coding agents
- ✅ Cross-agent frontend UI quality workflow for generated Django templates, Tailwind CSS, responsive states, accessibility, motion, and design-system alignment
- ✅ Cross-agent local development workflow for no-Docker terminal, service-backed, and multi-repo agent work
- ✅ Repo-scoped `.agents/skills/django-htmx` workflow for HTMX with Django templates, forms, and Alpine.js coordination
- ✅ Nested `AGENTS.md` guidance for generated Pages app content
- ✅ Cross-agent Alpine.js skill for Django templates and HTMX coordination
- ✅ Cross-agent Django Ninja skill for API endpoints, schemas, routers, authentication, OpenAPI docs, and tests
- ✅ Cross-agent Django Q2 skill for background tasks, schedules, workers, Redis, and ORM broker fallback
- ✅ Cross-agent PGSandbox MCP skill for disposable local Postgres checks with `DATABASE_URL`
- ✅ Cross-agent agent reliability workflow, task templates, code tours, and
  eval seed docs for repeatable AI-assisted implementation and verification
- ❓ Pydantic AI via OpenRouter for in-app agents
- ❓ Cross-agent Pydantic AI skills from `pydantic/skills`, gated by `use_ai`
- ❓ OpenRouter model presets via `OPENROUTER_MODEL_FAST` and `OPENROUTER_MODEL_SMART`

## Philosophy

This template aims to be:
- **Boring to maintain** (standard Django patterns, explicit config)
- **Fast to ship** (common SaaS pieces already wired)
- **Easy to extend** (clear app boundaries and sensible defaults)

## Contributing

Issues and PRs are welcome. If you’re proposing a bigger change, open an issue first so we can align on scope.

### Running template tests

This repo includes pytest-based tests that generate a project via Cookiecutter and assert the expected files are present/removed for various options.

```bash
uv run --group test pytest
```