SaaS Hammer reference architecture

Django + Next.jsSaaS Architecture

A fast React product UI paired with Django's business core, without infrastructure you do not need on day one.

Follow one request below: from the browser, through the UI and a token-checked API contract, into the Django core and its data, with slow work branching off to workers.

View pricingRead the docs

Request lifecycle

Reference pattern

  1. 01

    Browser

    A visitor uses the product.

  2. 02

    Next.js UI

    React screens render and prepare the request.

  3. 03

    API contract

    The call crosses the DRF boundary with a short-lived token.

  4. 04

    Django core

    Domain rules, permissions, and data operations run.

  5. 05

    PostgreSQL

    Persistent application data.

  6. 06

    Async work

    Slow or retryable work is dispatched to Celery workers; Beat schedules the recurring jobs.

Boundaries

Next.js for the interface. Django for the core.

Each side owns its own concerns and meets the other at one contract.

Next.js owns the product UI

React and TypeScript make it practical to build interactive screens, compose a design system, and keep frontend work focused.

Django owns the business core

Domain rules, data access, permissions, admin workflows, and API operations stay close to Django conventions.

Design decisions

Decisions that shape the stack.

Three reference patterns worth deciding on purpose, each with the trade-off it asks you to own.

· Decision · Token boundary

Auth crosses an explicit token boundary.

The UI presents a short-lived identity token. Django verifies it before every protected API operation.

Trade-off: You own token refresh, expiry, and revocation decisions instead of relying on a browser session.

Reference checklist

  • Attach a short-lived identity token to each API request.
  • Validate the token and resolve the user at the API boundary.
  • Enforce permissions in Django, not in the UI.
  • Use an exact CORS origin allowlist, never a wildcard.

· Decision · API boundary

Treat the API as a versioned contract.

Django validates input, applies permissions, and coordinates the domain. Next.js calls a stable contract instead of reaching into backend internals.

Trade-off: A contract takes maintenance: the UI and the API now move together through published changes.

Reference checklist

  • Validate input and permissions at the boundary.
  • Keep serialization and domain operations server-side.
  • Treat breaking response changes as contract events, not quick edits.

· Decision · Asynchronous work

Slow work leaves the request path.

A request dispatches work, workers execute it, and Beat schedules the recurring jobs. Imports, emails, syncs, reports, and retryable jobs all live here.

Trade-off: Results arrive outside the response, so progress, failures, and retries need an explicit story.

Reference checklist

  • Dispatch heavy or retryable work to a worker queue.
  • Keep recurring schedules in Beat instead of hand-rolled cron.
  • Design tasks so a retry stays safe.

Topology

Same boundaries, local and production.

The lifecycle above follows one request. Topology is about which services exist, who owns them, and what fails independently.

Local development

One machine, separate processes

  • Next.js web appThe product UI dev server.
  • Django APIThe business core and admin.
  • PostgreSQLLocal application data.
  • RedisQueues and messages for async work.
  • Celery worker + BeatBackground execution and schedules.

Production topology

Separate services, same boundaries

  • HTTPS entriesIn front of Next.js and Django.
  • Django APIThe business core as its own service.
  • PostgreSQLPrivate to the API.
  • RedisQueues as a separate service.
  • Workers + schedulesAsync execution and recurring jobs.

How you host it is a deployment choice. That each concern runs, scales, and fails on its own is not — request, task, and data failures stay isolated in both environments.

Comparison

Match the architecture to the product.

Django + Next.js is the default SaaS Hammer builds toward. It is not a universal winner.

Architecture fit comparison: when each approach fits and what it costs.
ApproachBest whenTrade-off
Pure Django templatesThe interface is server-rendered, interactions are modest, and one Python codebase keeps the team moving.Rich product UI and independently evolving frontend workflows can become harder to organize.
Django + Next.jsSaaS Hammer's ChoiceYou need a React product UI while keeping Django for domain logic, data, permissions, and operations.You own an API contract, two development environments, and an intentional auth strategy.
Pure Next.js backendYour team is all-in on TypeScript and the backend scope is small enough for its chosen server runtime.You give up Django conventions and may need to assemble admin, ORM, background work, and operations separately.

Pre-flight

Validate the seams first.

Four checks worth passing before committing screens, contracts, and infrastructure to the stack.

Choose an auth model first

Decide how the UI and the API trust each other before building screens around it.

Treat the API as a versioned contract

It is a product surface with consumers, not an internal shortcut.

Move slow work off the request path

Anything heavy or retryable belongs in a worker, not the web request.

Decide what runs together

Know which services share a machine locally and run independently in production.

Next steps

Start with a foundation you can reason about.

Explore the SaaS Hammer boilerplate, then use the docs to decide which reference patterns belong in your product.

Request accessView pricing