DEV Community: Anthony Addae

Building Durable, AI-Powered Workflows in Django

Anthony Addae — Fri, 11 Sep 2026 10:31:13 +0000

This tutorial walks through a complete local development path for this project:

Start the Django application and its dependencies with Docker Compose.
Install Git pre-commit hooks so quality checks run before each commit.
Create a product through the workflow API.
Follow the product as Temporal calculates a price, waits for approval, updates the price, and publishes the product.

The intended reader is comfortable opening a terminal but new to Docker Compose and Temporal. You do not need to install Python or PostgreSQL directly on your computer: the local Compose setup runs those application dependencies in containers.

What We Are Building

The project is a Django application backed by PostgreSQL. Product onboarding is asynchronous, so the HTTP request does not perform every step itself. Instead, Django creates the product and starts a Temporal workflow.

The local stack contains:

Service	Purpose	Local address
`django`	Django development server and migrations	http://localhost:8000
`postgres`	Application database	Internal Compose network
`temporal`	Temporal server	`localhost:7233`
`temporal-worker`	Executes workflow code and activities	Internal Compose network
`temporal-ui`	Inspect workflow executions	http://localhost:8088
`mailpit`	Captures development email	http://localhost:8025

The service definitions live in docker-compose.local.yml. Compose gives services stable names on its internal network, which is why Django connects to postgres and the worker connects to temporal instead of localhost.

Prerequisites

Install these tools first:

Docker Desktop, including Docker Compose
Git
just, a command runner used by this repository

Check that they are available:

docker --version
docker compose version
git --version
just --version

Clone the repository and enter it:

git clone https://github.com/klhenams/verbose-spork.git
cd app

Step 1: Check Local Configuration

The Compose file loads environment values from:

.envs/.local/.django
.envs/.local/.postgres

The important local settings are:

POSTGRES_HOST=postgres, because PostgreSQL is another Compose service.
TEMPORAL_HOST=temporal:7233, supplied to the Django and worker containers.
HUGGINGFACEHUB_API_TOKEN, which is optional for this tutorial.

Do not commit real credentials or API tokens. If your checkout does not contain local environment files, create them from your development configuration. The Django file can contain an empty Hugging Face token while learning the workflow; the application has a deterministic cost-based fallback.

Step 2: Start Docker Compose

The repository's justfile selects docker-compose.local.yml automatically:

just up

Under the hood, this runs:

docker compose -f docker-compose.local.yml up -d --remove-orphans

The first start may take a while because Docker builds the Django and PostgreSQL images and downloads Temporal images. The Django container runs python manage.py migrate before starting the development server, so the database schema is prepared automatically.

Check the running containers:

docker compose ps

Open these pages in a browser:

Django: http://localhost:8000
API documentation: http://localhost:8000/api/docs/
Temporal UI: http://localhost:8088
Mailpit: http://localhost:8025

If the application is still starting, inspect the logs:

just logs django
just logs temporal-worker

The worker should eventually log that it is listening on the product-tasks task queue. A Temporal worker must be running for workflow activities to execute; starting only Django is not enough.

Step 3: Install Git Pre-Commit Hooks

pre-commit runs configured checks against staged files before Git creates a commit. This repository declares its hooks in .pre-commit-config.yaml and installs the development dependency from pyproject.toml.

Install the hook inside the Django container so the host machine does not need the project's Python version:

docker compose run --rm django pre-commit install

Run all hooks once against the whole repository:

docker compose run --rm django pre-commit run --all-files

The configuration checks common file problems, applies Django upgrades, runs Ruff linting and formatting, formats pyproject.toml, and validates Django templates with djLint. Some hooks can modify files. Review those changes, stage them, and run the command again until it passes.

To run the checks manually on only staged files:

docker compose run --rm django pre-commit run

The configuration deliberately excludes documentation and migrations from the hook selection. That does not mean documentation cannot be reviewed; it means the project avoids applying code-formatting hooks to those paths.

Step 4: Run the Tests

The justfile provides a containerized pytest command:

just pytest

For the pricing activity tests only:

just pytest app/products/tests/test_workflow_activities.py

The pricing activity has two paths:

With HUGGINGFACEHUB_API_TOKEN, it asks the configured Hugging Face model for a structured PriceSuggestion.
Without a token, it uses a fallback of cost * 1.35, rounded to two decimal places.

That fallback makes the local workflow usable without an external model account.

Step 5: Understand the Product Creation Endpoint

The workflow-specific endpoint is registered as workflows in the product API router. Because the project includes the API router below /api/, create a product with:

POST http://localhost:8000/api/workflows/

The endpoint requires authentication. Use the API documentation at http://localhost:8000/api/docs/ or obtain a DRF token from the project's authentication endpoint before sending the request.

The request body should include the product fields below. category is an existing category ID:

{
  "name": "Portable Monitor",
  "description": "A lightweight second screen for a laptop.",
  "sku": "MONITOR-PORTABLE-001",
  "price": "0.00",
  "cost": "100.00",
  "stock_quantity": 12,
  "low_stock_threshold": 3,
  "category": 1
}

The initial price is allowed to be a placeholder. The workflow will calculate a suggestion and later write the selected price. The create view saves the product with pending_pricing and starts a workflow with the ID:

product-onboarding-{product_id}

For example, product 42 runs as product-onboarding-42 on Temporal task queue product-tasks.

Step 6: Follow the Workflow Sequentially

The workflow is implemented in app/products/workflows/workflows.py. Its activities are in app/products/workflows/activities.py.

1. Calculate a suggested price

The worker executes calculate_suggested_market_price.

With no Hugging Face token and a cost of 100.00, the fallback suggestion is:

100.00 * 1.35 = 135.00 GHS

The activity returns a structured result containing the suggested price, currency, confidence score, reasoning, and source. If the external model fails, the activity logs the exception and uses the fallback instead.

2. Inspect the suggestion

The API can query the running workflow without changing its state:

GET http://localhost:8000/api/workflows/{product_id}/pricing-suggestion/

Example response:

{
  "suggestion": {
    "suggested_price": 135.0,
    "recommended_margin": "35.0",
    "currency": "GHS",
    "confidence_score": 0.0,
    "reasoning": "Fallback pricing based on product cost.",
    "source": "cost_fallback"
  }
}

The workflow includes a short ten-second pause after pricing so the execution is easy to observe in the Temporal UI. That delay is for demonstration and is not required by the business process.

3. Approve or override the price

The workflow waits for a signal named approve_suggested_price. Send the suggested price as-is or choose another value:

POST http://localhost:8000/api/workflows/{product_id}/approve-price/

Request body:

{
  "price": "129.99"
}

The API translates this request into a Temporal signal. The workflow records the selected price and continues. This is a useful distinction:

A query reads workflow state.
A signal sends an event that changes workflow state.

If no approval arrives before the configured timeout, the workflow automatically selects the suggested price. The default timeout is 24 hours.

4. Update the product price

After approval or timeout, update_product_price stores the final price in PostgreSQL. The product remains controlled by the workflow rather than being published immediately by the HTTP request.

5. Publish with retries

The workflow calls publish_product with a Temporal retry policy:

Maximum of three attempts
Two-second initial interval
Exponential backoff with a coefficient of 2.0

When publishing succeeds, the activity changes the product status to active, and the workflow returns:

{
  "status": "PUBLISHED",
  "final_price": 129.99,
  "was_auto_approved": false
}

Step 7: See the Compensation Path

To exercise the failure path, include the test-only field below when creating a product:

{
  "name": "Failure Demo",
  "description": "Used to demonstrate workflow compensation.",
  "sku": "FAILURE-DEMO-001",
  "price": "0.00",
  "cost": "10.00",
  "stock_quantity": 1,
  "low_stock_threshold": 1,
  "category": 1,
  "test_should_fail_publish": true,
  "test_timeout_seconds": 20
}

The publish activity raises an error deliberately. Temporal retries it three times. When all attempts fail, the workflow executes revert_product_status, which changes the database status to failed_publish, and returns a FAILED_PUBLISH result.

This is a small Saga pattern: after earlier work has changed state, a compensation activity restores a meaningful failure state when a later operation cannot complete.

The test_* fields are passed through by the current API view to make demonstrations and tests predictable. Treat them as development/testing controls, not as production business inputs.

Observe Everything in Temporal UI

Open http://localhost:8088 and find the workflow named product-onboarding-{product_id}. You can inspect:

The workflow status
The activity attempts and retry history
The waiting period for human approval
The final return value
The failure and compensation sequence

This is often easier to understand than reading logs because Temporal shows the workflow's event history as a durable sequence.

Stopping and Resetting the Environment

Stop the containers but keep the PostgreSQL volume:

just down

Stop the containers and delete local volumes, including the database data:

just prune

Use just prune carefully. The next just up starts with an empty database and will need to run migrations and recreate any sample data.

Troubleshooting

The workflow never advances

Check the worker:

just logs temporal-worker

The worker must connect to temporal:7233 and register the product-tasks queue. If only the Django container is running, the workflow can start but its activities cannot be picked up.

Django cannot connect to PostgreSQL

Inside Compose, use postgres as the database host, not localhost. Check that the database health check has passed:

docker compose ps postgres

The pricing suggestion is not from Hugging Face

That is expected when HUGGINGFACEHUB_API_TOKEN is empty or the model request fails. The cost-based fallback is intentionally part of the local implementation.

Pre-commit changes a file

Review and stage the change, then run the hook again:

git diff
git add -A
docker compose run --rm django pre-commit run

What to Read Next

The central idea is simple: Django accepts the request and records intent, while Temporal coordinates the long-running work, human decision, retries, and compensation. Docker Compose makes that entire system reproducible on a developer laptop.

Open Source Is People: A Python & Django Year

Anthony Addae — Wed, 31 Dec 2025 10:31:03 +0000

For years I stood just outside the circle, watching talks, mentoring quietly, and cheering from the edges. In 2025, I finally stepped into the light.

This is my first-ever blog post. Good people of Python Ghana community kept nudging, “Start a blog.” The last gentle push came from the Djangonaut Space program. So here it is: the beginning of a habit of showing up, reflecting, and documenting the journey. I also share photos on my photoblog, @maaddae.

My First Step: Django Girls Ho 2017

It started in 2017, in Ho. I showed up as a Django Girls mentor for a workshop organized by Noah Alorwu. One room, a handful of laptops, and the quiet buzz of first lines of code, something clicked. That day opened a door.

It opened the door to a welcoming community of people who build, teach, and support each other. For years after that, I stayed involved mostly through mentorship. I taught when I could, encouraged beginners, and contributed quietly.

But in 2025, something shifted. I felt ready to take a bolder step forward.

Starting the Year With Mentorship Once Again

Just like in 2017, 2025 began with people.

Django Girls Koforidua 2025

I joined as a mentor, helping participants build their first Django applications. The moment a beginner connects the dots, from views to templates to a working app, never gets old. That spark keeps me returning.

Django Girls Ho 2025

Later, I coached at Django Girls Ho. It felt like coming home: nostalgic, grounding, and inspiring. Open source, at its best, is made of patience, kindness, and shared growth.

Building Community Through Speaking and Organizing

Then the year nudged me forward, beyond mentorship, into roles that stretched me.

PyCon Ghana 2025

I served as a programme co-organizer for PyCon Ghana: reviewing talks, shaping the agenda, supporting speakers. I also spoke and joined a panel. Wearing both hats taught me how much care it takes to craft a meaningful conference.

PyHo Conference 2025

I returned to speak at PyHo, one of Ghana’s most vibrant Python gatherings. The warmth and curiosity there always feels like home.

PyCon Africa 2025

I was selected to speak at PyCon Africa, a milestone I celebrated. Then, an airport desk and a paperwork snag turned celebration into absence. It stung, but the community’s support turned the moment into fuel rather than a full stop.

Joining the Django Software Foundation

A quiet, meaningful milestone followed: I became an Individual Member of the Django Software Foundation.

For someone who has loved Django for years, that recognition felt like a promise: to keep contributing, to engage deeply, to show up.

Djangonaut Space: A Transformative Chapter

Another turning point: I was accepted into Djangonaut Space and joined Team Neptune. With mentors who’ve shaped Django, I submitted my first pull request to the framework. It came back with review comments, welcomed notes on how to do better. I am committed to keep going beyond the program.

It wasn’t just technical. It connected me to the heart of the framework I’ve relied on for years, and to the people who keep it alive.

Why This Year Matters to Me

Looking back, 2025 feels like a year of showing up: learning, teaching, sharing, and stepping further in.

I started the year mostly mentoring. I end it as a mentor, speaker, organizer, contributor, and a community member actively shaping the spaces that shaped me.

Writing this blog is part of that growth, and I hope to keep it up.

The Road Ahead

As I look forward, I hope to continue:

contributing to Django core
supporting Django Girls workshops
speaking at Python and Django events
mentoring upcoming developers
strengthening local and global communities

Open source has room for everyone. I am grateful that I found my place, and I hope this encourages someone out there to start their own journey too.