Build Bubble

The build, in order

1. 1

   Project, accounts and the admin

   hideshow

   Signup, login, logout and password reset all work, and you can edit data through the admin, before you write a single feature.

   1. 1.1Create the project and point it at PostgreSQL

      Start the project, add psycopg, and set the database from environment variables. Never commit a settings file with credentials in it.

      Files config/settings.py.env.example

      terminalcopy

      python -m venv .venv
      pip install django psycopg[binary] python-dotenv
      django-admin startproject config .
      python manage.py migrate

   2. 1.2Wire the built-in auth views and a real email backend

      Include django.contrib.auth.urls, add templates for login and the reset flow, and configure SMTP against a transactional provider. Send yourself a reset to prove it.

      Files templates/registration/

      terminalcopy

      python manage.py createsuperuser

   3. 1.3Lock the admin down before you forget

      Move it off /admin, require staff status, and confirm an anonymous request gets a login page. Turn DEBUG off outside local development and set ALLOWED_HOSTS.

      Files config/urls.py

   done when · tick each as it passes

   • Signup, logout and login all succeed
   • A password reset email reaches a real inbox and the link works
   • An anonymous request to the admin returns a login page, not data
   • The application refuses to start with DEBUG True when the environment says production

   watch out

   • Django's password reset does nothing visible without a working email backend, and the development console backend makes it look like it worked. Point it at a real transactional provider now, or you will discover this the week you launch.

   next phase
2. 2

   Your data model and migrations

   hideshow

   Your real tables exist, with constraints the database enforces rather than the form.

   1. 2.1Write the models with database constraints

      Define the models and add Meta.constraints for the invariants. A CheckConstraint for a positive price and an ordered date range costs three lines and holds forever.

      Files app/models.py

      terminalcopy

      python manage.py makemigrations
      python manage.py migrate

   2. 2.2Register everything in the admin

      list_display, search_fields and list_filter for each model. This is the closest analogue to Bubble's data tab and it is worth ten minutes.

      Files app/admin.py

   3. 2.3Seed realistic data

      A management command that creates a few users, listings and bookings so every later screen has something to render and every query has rows to be slow against.

      Files app/management/commands/seed.py

      terminalcopy

      python manage.py seed

   done when · tick each as it passes

   • Migrations apply cleanly to an empty database
   • A booking with an end before its start is rejected by the database
   • makemigrations reports no pending changes after migrate
   • The seed command populates every model and is safe to run twice

   watch out

   • Validating only in the form leaves the database willing to hold nonsense the moment anything else writes to it, including a management command or the admin. Put the rule in a constraint and let the form report the violation.

   next phase
3. 3

   Screens and workflows

   hideshow

   A visitor can complete the main journey end to end without you touching the admin.

   1. 3.1Build the core screens with forms

      List, detail and create. Use ModelForm so validation lives with the model. Keep templates thin.

      Files app/views.pytemplates/

   2. 3.2Add HTMX for the interactive parts

      Load HTMX from a vendored file rather than a content delivery network, and return HTML fragments from views. No build step, no bundler.

      Files static/htmx.min.js

   3. 3.3Authorise in the view and test it

      A test that logs in as user B and posts to user A's object, expecting a refusal. This is the test that catches the mistake everyone makes.

      Files app/tests/test_permissions.py

      terminalcopy

      python manage.py test

   done when · tick each as it passes

   • The main journey completes without touching the admin
   • Posting to another user's object is refused
   • A double form submit does not create two records
   • Every form shows field errors rather than a server error page on bad input

   watch out

   • Hiding a button in a template is not authorisation. Anyone can post to the URL. Check ownership and permission inside the view, and write a test that posts to another user's object and expects a refusal.

   next phase
4. 4

   Payments

   hideshow

   Money moves, and your database agrees with Stripe about what happened.

   1. 4.1Create a Checkout session server side

      Never trust a price from the client. Look the amount up from your own database and pass it to Stripe.

      Files app/payments.py

      terminalcopy

      pip install stripe

   2. 4.2Handle the webhook as the only source of truth

      Verify the signature with the endpoint signing secret, then update state. Exempt this view from CSRF, because it is a server to server call, and rely on the signature instead.

      Files app/webhooks.py

   3. 4.3Make the handler idempotent and test replay

      Store the processed event id and ignore duplicates. Use the Stripe command line tool to replay an event and assert nothing changes the second time.

      terminalcopy

      stripe listen --forward-to localhost:8000/webhooks/stripe/
      stripe trigger checkout.session.completed

   done when · tick each as it passes

   • A test payment marks the record paid only after the webhook
   • Replaying the same event leaves exactly one paid record
   • A bad signature is rejected with a 400
   • Closing the tab after payment still results in a paid record

   watch out

   • Marking the order paid on the success redirect is the classic and expensive mistake. The visitor can close the tab, and the redirect can be replayed. The webhook is the source of truth and the redirect is only a nice screen.

   next phase
5. 5

   Background work and email

   hideshow

   The things that should not block a request stop blocking it, and failures are visible.

   1. 5.1Add an outbox table

      Rows with state, attempts and last error. Views write rows; the command sends them. This is what makes retries and visibility possible.

      Files app/models.py

   2. 5.2Write the send command

      Select pending rows, send, mark sent or failed with the error text. Cap attempts and back off.

      Files app/management/commands/send_outbox.py

      terminalcopy

      python manage.py send_outbox

   3. 5.3Schedule it and prove idempotence

      A cron entry every minute. A test that runs the command twice against one pending row and asserts one send.

   done when · tick each as it passes

   • The request returns without waiting on email
   • A failed send is a row with an error, retried on the next run
   • Running the command twice sends once
   • Attempts are capped so a permanently bad address stops being retried

   watch out

   • Reaching for Celery and Redis on day one adds two services to operate for work that a cron entry handles at this size. Add the queue when a command is too slow or needs retries within seconds, and not before.