🧱 Django Mason Starter

A modern, fully-featured and opinionated Back-End Django Starter Template for medium-sized SaaS (work in Progress).

Features

🤓 Top-notch Developer Experience with tight VS Code integration

• VS Code devcontainers to share the same local environment between all team members with 1-click install
• docker-compose for multiple services (Django, Postgres, Redis, etc.)
• Debug: ipdb + VS Code debug + django-debug-toolbar
• VS Code tests, tasks, and built-in terminal with clean prompt, colors, and aliases.
• Multi linting + auto-formatting + import sorting using Ruff and its VS Code extension
• ipython and django-extensions for using Python in CLI
• Pre-commit githook to ensure code quality
• Poetry setup using a single pyproject.toml file for all config

🫙 Database

• PostgreSQL + dj-database-url
• Custom database UML generation command using D2
• Django safe delete to soft delete objects
• Custom commands (data loading/dumping)

✅ Django best practices

• 12 Factors compliance with django-environ
• Compositional Model Behaviors for DRY, readable, reusable, testable models and querysets.
• Security in mind (settings, cors headers, custom admin url, etc.)
• Clean folders structure, with scaling in mind
• Applicative Parameters (in-db parameters to configure app without pushing code)
• Custom User, custom Exceptions

🪪 CRUD App (a badge management system)

• REST API using django-ninja, with built-in OpenAPI documentation. Uses token-based authentication.
• Unit tests with pytest and factory boy
• Admin

🔨 Other features and custom utils

• Full Celery, including django-celery-beat and django-celery-results
• Soketi websockets server (realtime bi-directional messages)
• Mailing integration with SMTP using Amazon SES
• More custom fields (PriceField, PositionField, PhoneNumberField, etc.)
• Custom models and querysets for Compositional Model Behaviours, Global Permission
• Custom utility functions and decorators

Todo

Django features

• Django social-auth
• Django-fsm (finite state machines)
• Cache mechanisms
• Feature flags

API

• More advanced API features (pagination, other auth, etc.)
• GraphQL example with Strawberry

Testing

• Add a test coverage tool
• 100% test coverage

DX and code quality

• Type hints with django-stubs and strict mode on.
• shell_plus autoreload

CI/CD, Hosting, DNS, Object Storage, Mailing

• All-in-one AWS example
  • AWS serious deployment example using ECS + Fargate with Django / Nuxt / Celery / Redis container + managed services : S3 / RDS (or λ for task execution ?)
  • CI/CD with CodePipeline
  • Route 53 DNS
  • S3 storage management with boto3 and django-storages
  • SES for mails
• Simpler PaaS alternative using Heroku

Monitoring

• Full Stack Monitoring with Highlight.io (Errors, logs, performance monitoring)
• [] CloudWatch (logging / monitoring)

Integrations with other SaaS (it could take some time 😅)

• Payment → Stripe
• Customer Service → Freshdesk or Intercom
• Basic Analytics → Plausible
• Advanced Product Analytics → Mixpanel
• SMS/Phone → Twilio
• CRM: Hubspot
• Intelligent Search → Algolia
• Enterprise chat → Slack
• Team Projects → Notion
• Business Inteligence → Metabase

Documentation

• Add a full documentation to this template (either using a tool like Gitbook or directly in the code)

Related project

• 🧱 Nuxt Mason Starter: the front-end counterpart of this template, using Nuxt.js (vue.js), and Nuxt UI.

Current used versions

• Python 3.11.* (waiting some package compatibility to migrate to 3.12)
• Django 4.*
• Celery 5.*

FAQ

Why not using the front-end part of Django?

For a significant part of medium-sized projects, Django front-end abilities are unfortunately not enough to ensure a great UX/DX, compared to tools like React or Vue. Htmx kind of fills the gap, but it currently lacks a proper integration with Django and a good developer experience. Besides, a Nuxt Mason Starter (cf. above) should be developped to have the front-end counterpart of this template.

What if I (or other team members) are not using VS Code?

The whole DX part of this template is focused on VS Code so you would lose these specific features. Besides, if there are different code editors within your team, you should add configuration tools that work between multiple IDEs, like EditorConfig.

How do you pick the tools of this template?

• I try to pick tools that are suitable for small to medium start-ups. You never should start too big. I try to avoid complex concepts that can be more harmful than useful (kubernetes, micro-services)

• I try to favor multi-usages tools to have less tools in the end. For example, PostgreSQL can be used for sql and nosql, Redis can be used as a message broker and a cache mechanism, etc.

• I try to favor open-source tools which allow the user to self-host tool or using a paying SaaS (like highlight.io)

• When adding integrations, I try to pick the ones that are broadly used rather than the "best" ones.

• I try to avoid in-progress work that should change (That's the reason I prefer using Soeti to django-channels or anything async with Django).

Why Django rather than fullstack JS?

If you're here, you might already be convinced, but let me share my thoughts regardless. While the appeal of full-stack JavaScript lies in using a single language, there's currently no equivalent to feature-rich frameworks like Django, Rails (Ruby), or Laravel (PHP) in the JavaScript world. Building a complex back-end becomes significantly more complicated, as you have to integrate multiple tools. Contrary to what they advertise, frameworks like Next.js are not "full-stack" as they don't offer essential backend building blocks like an ORM, authentication system, or validation.

Furthermore, Python is increasingly being used in projects for data analysis and machine learning, areas where JavaScript doesn't offer an equivalent. In such cases, the "single language" benefit loses its validity.