MIT licensed

MVCLM React-Django

A starter kit for shipping React and Django applications. Authentication, admin tooling, operational controls, and a tested Docker setup for both local development and production.

React 19 Django 5.2 TypeScript PostgreSQL 16 Docker Compose nginx + certbot

What Is Included

The foundation most projects rebuild from scratch, already working.

Authentication

✅ Google registration and sign-in

✅ Local registration with email and password

✅ Google and local accounts handled as one

✅ Email verification for local accounts

✅ Password reset by email link

✅ Authentication in a secure HTTP-only cookie

✅ JWT with CSRF protection

✅ Refresh-token rotation, blacklisted on sign-out

✅ Account self-delete with type-to-confirm

Admin

✅ Users list with sort, search and pagination, hand-rolled with no extra dependencies

✅ User edit page with role, status and delete controls

✅ Analytics: signup chart, auth-method breakdown, key metrics, recent signups

✅ App Settings page for operator-controlled toggles

Operations

✅ Maintenance mode: a site-wide banner plus gated authentication endpoints

✅ Demo mode blocks destructive actions, for public showcase deployments

✅ Fake-user generation in buckets of ten, and a delete-all helper

✅ Contact form with a honeypot and a Reply-To header

Developer Experience

✅ Full Docker Compose stack: database, backend, frontend, nginx, certbot

✅ Vite hot module replacement through a container bind-mount on Windows, macOS and Linux

✅ Let's Encrypt auto-renewal through a certbot sidecar on a twelve-hour loop

✅ A flash-toast and inline-banner hybrid for user feedback

How It Is Laid Out

A standard Django and Vite layout. Backend apps map to domain concerns; the frontend source is organised by responsibility.

backend/
  config/         # settings, URLs, ASGI/WSGI
  users/          # User model, auth, admin endpoints
  app_settings/   # maintenance + demo flags
  contact/        # contact form endpoint

frontend/src/
  api/            # fetch wrapper, 401-refresh guard
  auth/           # AuthContext, route wrapper
  app-settings/   # context + maintenance banner
  flash/          # toast provider + stack
  layouts/        # public and admin layouts
  components/     # shared UI primitives
  pages/          # route pages

Getting Started

Requirements

Docker

git

That is the whole list. Node, Python and PostgreSQL all run inside containers, so nothing has to be installed on the machine to work on this.

One Thing To Know

The development stack installs the frontend packages inside the container, so the host folder stays empty. An IDE will then flag every JSX file, because the TypeScript service cannot resolve the types. Run the install once on the host after cloning and it stops.

Installation

# Clone and start the stack
git clone https://github.com/jaanus-saarnak/mvclm-react-django.git
cd mvclm-react-django
cp .env.example .env
docker compose up

# In a second terminal
docker compose exec backend python manage.py migrate
docker compose exec backend python manage.py createsuperuser

# Optional, so the IDE resolves types
cd frontend && npm install

Then open http://localhost:8080. Everything is served from a single origin behind nginx, which is what lets the authentication cookie work the same way locally and in production.

Decisions Worth Knowing About

Why it is put together the way it is.

Tokens live in cookies, not in storage

Authentication rides in an HTTP-only cookie with CSRF protection, so no token is reachable from JavaScript. Refresh tokens rotate, and the old one is blacklisted at sign-out.

One origin, locally and in production

nginx fronts both the API and the frontend, so there is no CORS configuration to get wrong and the cookie behaves the same in both places.

The admin table is hand-rolled

Sorting, searching and pagination are written out rather than pulled from a table library, so there is no dependency to upgrade and nothing to fight when the columns change.

Operators get switches, not a redeploy

Maintenance mode and demo mode are toggles on an App Settings page rather than environment variables, so turning the site off does not mean shipping a new build.

License

MIT. Use it, change it, ship it, sell what you build with it.