Welcome to Platform Django

A project template for building modular monolith Django applications with modern frontend tooling.

This template establishes architectural patterns that work for small teams and large organizations. The modular monolith approach means deploying a single unit while keeping clear boundaries between domains.

New here? Start with Why This Template? to understand the philosophy, or jump to Project Generation Options if you’re ready to generate a project.

Introduction

• Why This Template?
  • The Challenge of Platform Architecture
  • What This Template Provides
  • Supporting Research
  • Further Reading
• The Modular Monolith
  • What is a Modular Monolith?
  • Why Not Microservices (Yet)?
  • Why Not a Traditional Monolith?
  • The Best of Both Worlds
  • Supporting Research
  • Further Reading
• Architecture Overview
  • Project Structure
  • Domain Boundaries
  • Scaling Pathways
  • Supporting Research
  • Further Reading
• UI Architecture Philosophy
  • The Core Principle
  • Tier 1: Django Templates (Simple)
  • Tier 2: Vite-Based SPAs (Interactive)
  • Tier 3: Pre-Built Static Assets (Marketing)
  • Choosing the Right Approach
  • The Monorepo Advantage
  • Further Reading

Getting Started

• Project Generation Options
• Configuration
  • How django-environ Works
  • Settings File Layering
  • The .env File
  • Configuration by Environment
  • Best Practices
  • See Also
• Settings Reference
  • Other Environment Settings

Local Development

• Getting Up and Running Locally With Docker
  • Prerequisites
  • Before Getting Started
  • Build the Stack
  • Run the Stack
  • Execute Management Commands
  • (Optionally) Designate your Docker Development Server IP
  • Configuring the Environment
  • Tips & Tricks

Deployment

• Deployment on Heroku
  • Script
  • Notes
  • Optional actions
• Deployment on AWS
  • Overview
  • Monorepo Infrastructure Layout
  • Choosing Between ECS and EKS
  • Core AWS Resources
  • Terraform Modules Approach
  • Terragrunt for Environment Management
  • ECS Deployment Pattern
  • EKS Deployment Pattern
  • CI/CD Patterns
  • Secrets and Configuration
  • See Also

Guides

• Adding Modules to the Modular Monolith
  • Overview
  • Project Layout
  • Creating a New Module
  • Module Structure
  • Best Practices
  • See Also
• Django Admin as an Operator Panel
  • Overview
  • Practical Enhancements
  • When Django Admin Works Well
  • Acknowledging Limitations
  • The Natural Progression
  • See Also
• Authentication
  • Overview
  • How Authentication Works
  • Custom Adapters
  • Single Sign-On (SSO)
  • AWS Cognito Integration
  • API Authentication
  • Multi-Factor Authentication
  • Configuration Reference
  • See Also
• Module Boundary Enforcement
  • Overview
  • Import Enforcement with import-linter
  • Programmatic Testing with grimp
  • Lightweight Enforcement with Ruff
  • Database Boundary Enforcement
  • Combining Enforcement Layers
  • See Also
• Service Layer Patterns
  • Overview
  • The Core Principle
  • Where Business Logic Should NOT Live
  • Writing Services
  • Writing Selectors
  • Module Structure
  • Common Pitfalls
  • Testing Services and Selectors
  • See Also
• API Development
  • Overview
  • Django REST Framework (Default)
  • GraphQL
  • django-ninja
  • Choosing the Right Approach
  • See Also
• Type-Safe API Integration
  • Overview
  • Backend Setup
  • Frontend Setup
  • Using Generated Code
  • Query Hooks
  • Mutation Hooks
  • Common Patterns
  • Development Workflow
  • Alternative: Orval for Full Client Generation
  • Breaking Change Detection with oasdiff
  • Summary
• Event-Driven Architecture
  • Overview
  • The Event Bus
  • Defining Events
  • Registering Handlers
  • Publishing Events Safely
  • Integrating with Celery
  • Django Signals vs Domain Events
  • Scaling the Event Bus
  • Event Sourcing vs Event-Driven Architecture
  • Summary
• Production Patterns
  • Zero-Downtime Migrations
  • Feature Flags with django-waffle
  • Celery Patterns for Event-Driven Systems
  • Combining Patterns
  • See Also
• Observability and Structured Logging
  • Overview
  • The Problem with Plain Text Logs
  • Structured Logging with structlog
  • OpenTelemetry Integration
  • Exporting to Backends
  • Production Configuration Patterns
  • Common Patterns
  • Summary
• Model Auditing and Version History
  • Overview
  • Choosing an Approach
  • django-simple-history
  • django-auditlog
  • Integration with Domain Events
  • Testing Audit Functionality
  • Performance Considerations
  • Common Patterns
  • See Also
• Product Analytics with PostHog
  • Why PostHog?
  • Architecture Overview
  • Environment Configuration
  • Frontend Setup
  • Backend Setup
  • Reverse Proxy Configuration
  • Automatic Tracking: Page Views & Sessions
  • User Identification
  • Custom Event Tracking
  • Session Replays & Heatmaps
  • Feature Flags
  • Privacy & GDPR Compliance
  • Summary
• Multi-Tenancy with Organizations
  • Overview
  • The Organizations App
  • Models
  • Tenant Context
  • Query Filtering
  • Deployment Modes
  • Integration with Users
  • Domain Events Integration
  • API Endpoints
  • Testing Patterns
  • Common Pitfalls and Security
  • Summary
• Code Quality
  • Quick Reference
  • Python/Django Tools
  • Frontend Tools
  • Git Hooks with Lefthook
  • IDE Integration
  • Customization
• Testing
  • Pytest
  • Coverage
  • Testing Event-Driven Code
  • Test Organization
  • See Also
• E2E Testing with Playwright
  • When to Use E2E Tests
  • Where Playwright Fits in the Monorepo
  • Key User Flows to Test
  • Handling Authentication in E2E Tests
  • Running Tests Against Different Environments
  • CI/CD Integration
  • Best Practices
  • See Also
• Data Ingestion and Integration Patterns
  • Overview
  • Bulk Data Ingestion
  • Near Real-Time Ingestion
  • Integration Module Structure
  • Testing Integration Code
  • Production Considerations
  • See Also
• Document
  • Generate API documentation
  • Setting up ReadTheDocs
• Websocket
  • Usage
• LangChain & LangGraph Integration
  • Overview
  • Architecture Patterns
  • Installation & Setup
  • Building Your First Chain
  • LangGraph for Agent Workflows
  • RAG (Retrieval Augmented Generation)
  • Integration Patterns
  • Streaming Responses
  • Testing Agents
  • Production Considerations
  • Common Patterns
  • See Also

AI Development

• AI-Driven Development with Claude Code
  • Why Claude Code for Development
  • The Planning Workflow
  • Quality Gates as AI Guardrails
  • Parallel Development with Worktrees
  • GitHub Integration
  • Putting It Together
  • Quick Reference

About

• Maintainer guide
  • Automated updates
  • GitHub Actions workflows
  • Template testing
  • Template updates with Copier
• Roadmap: Features Documented But Not Yet Implemented
  • Module Boundary Enforcement
  • Production Patterns
  • Observability
  • Testing
  • Type Safety
  • API Frameworks
  • Developer Experience
  • Infrastructure as Code
  • Contributing
• FAQ: How Much Rust?

Indices and tables

• Index

• Search Page