Backend Development: Two-Week Online Course

A two-week online course on backend development with Python, Django, Django REST Framework and Pydantic, taught on Smarter’s code base. Smarter is a large Django project, with eighteen apps in smarter/smarter/apps/ that share one deliberately rigid layout, more than five thousand unit tests, and patterns that tutorial projects never reach: a broker layer that turns YAML manifests into database rows, Pydantic models for every manifest and contract, a Pydantic Settings class, Celery workers and a beat schedule, and caching with @cache_results. The guardrail app, the newest and cleanest, is the reference that the course reads and changes. There are six 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers Django and its API layer, and week 2 covers manifests, models, testing and background work. See Course Formats and Grading for the format, the grading scale and the course policies, and Backend Development with Python, Django, Django REST Framework and Pydantic for an overview of the subject.

At a Glance

Students

Software developers who know Python and want to learn Django and the patterns of a large backend.

Deployment

Each student runs Smarter from source on their own computer, installed before Live session 1. Live session 1 opens with 15 minutes of installation triage.

Workload

3 hours of instruction and 4 to 6 hours of assignments each week.

Cost

Free, apart from small model charges when students chat with their LLMClients.

Learning Objectives

By the end of the course, students can:

  1. Explain the Django request lifecycle, and navigate a large Django project.

  2. Build and call REST endpoints with Django REST Framework, with authentication and consistent errors.

  3. Explain how Smarter’s brokers turn Pydantic-validated manifests into database rows.

  4. Add a field to a resource end to end, with a migration and tests.

  5. Write management commands and Celery tasks, and test them.

Technical Prerequisites

  • Required: Python: functions, classes, decorators, exceptions, type hints and virtual environments.

  • Required: Git and GitHub: clone, branch, commit, push and pull requests.

  • Required: the Linux or macOS command line, and Docker basics (images, containers, docker exec and docker logs).

  • Required: HTTP and JSON.

  • Required: Smarter installed from source, following the Developer Setup Guide, before Live session 1.

  • Helpful: SQL, YAML, and Visual Studio Code with the Python extension.

Schedule

The files that the lectures refer to are listed in full under Smarter in the Source Code.

Week

Item

Content

1

Lecture 1 (30 min)

Django in one picture. Projects, apps, settings, URLs, middleware, views, models and the ORM. The structure of Smarter’s apps, using guardrail and secret.

1

Lecture 2 (30 min)

The ORM in practice. Querysets, relationships, select_related and prefetch_related, and the Django shell.

1

Lecture 3 (30 min)

Django REST Framework. Serializers, views, authentication, permissions, and Smarter’s REST API and error format.

1

Live session 1 (90 min)

Installation triage, then a live trace of a smarter apply request with a debugger. Pairs trace a describe request. Start Assignment 1.

2

Lecture 4 (30 min)

Pydantic, manifests and brokers. Validation, models and the broker model.

2

Lecture 5 (30 min)

Models, migrations and tests. Adding a field, migrations, SmarterTestBase, and running tests in the container.

2

Lecture 6 (30 min)

Beyond the request. Management commands, Celery tasks, the beat scheduler, caching with @cache_results, and signals.

2

Live session 2 (90 min)

Capstone presentations: each student walks through their pull request for 5 minutes, with 2 minutes of review questions.

Assignment 1 is due at the end of week 1, Assignment 2 in the middle of week 2, and Assignment 3 and the capstone at the start of Live session 2.

Smarter in the Source Code

Every lecture, lab and assignment in this course rests on the files below. Every reference is to the main branch of github.com/smarter-sh/smarter, so that students can open each one during class. Python paths are under smarter/smarter/.

One App, End to End

The guardrail app is the reference implementation that the others follow, and the one that the labs change. Every app in apps/ has the same layout.

Layer

What it does

Where to look

Django model

What is stored: fields, choices, relationships, and an ownership base class that makes every guardrail belong to an account and a user.

guardrail/models/guardrail.py, account/models/metadata_with_ownership.py

Migrations

The schema history. Smarter prefers one regenerated 0001_initial.py per app, and adds a new migration instead for released apps that hold production data.

guardrail/migrations/, smarter-migrations/SKILL.md

Pydantic manifest

What a client sends: the metadata, spec and status of a Guardrail manifest, with types, descriptions and validators. ADR 031.

guardrail/manifest/models/guardrail/

Broker

Turns the manifest into model fields (manifest_to_django_orm()) and back (django_orm_to_manifest_dict()), and implements apply, describe and delete. Smarter Broker Model.

guardrail/manifest/brokers/guardrail.py, lib/manifest/broker/abstract_broker_class.py

DRF serializer and API

Resource-style REST endpoints for guardrails and their events, beside the command-style CLI API that every kind shares.

guardrail/serializers.py, guardrail/api/v1/

Console views

The Django view and template that host the React list page, and the session-authenticated views it calls to list, clone, rename and delete.

guardrail/views/listview/, guardrail/urls.py

Signals and receivers

Events that other apps can react to, kept in signals.py and handled in receivers.py.

guardrail/signals.py, guardrail/receivers.py

Tests

One test module per source module, with test data as YAML.

guardrail/tests/

A second example

The secret app, small enough to map completely in a lab, with Fernet encryption in its model.

apps/secret/

The Request Path

Step

What happens

Where to look

URL

/api/v1/cli/apply/ and the other commands are routed to one view each.

api/v1/cli/urls.py

Authentication

The CLI API requires an API key, checked against its stored hash by a Knox-based authentication class that REST_FRAMEWORK sets as the default.

lib/drf/token_authentication.py, settings/base.py

View

The base view parses the YAML body, finds the broker for the kind, and maps every exception to a status code.

api/v1/cli/views/base.py, api/v1/cli/views/apply.py

Broker registry

A map from each kind, such as Guardrail, to its broker class.

api/v1/cli/brokers.py

Loading the manifest

YAML or JSON is parsed and checked for required keys before Pydantic validates it.

lib/manifest/loader.py

The response, and its record

Every response, success or error, is written to the journal.

lib/journal/http.py, lib/journal/models.py

Beyond the Request

Topic

What Smarter does

Where to look

Settings

Every setting is read from the environment and validated by a Pydantic Settings class. ADR 007.

common/conf/settings.py, settings/

Management commands

A SmarterCommand base class, and commands that create accounts, users and API keys, load built-in data and initialize the whole platform. ADR 010.

lib/django/management/base.py, account/management/commands/

Celery tasks and beat

Tasks on named queues, run by the worker containers, and a beat schedule that aggregates charges, evaluates budgets, purges old guardrail events and reconciles self-hosted models and vector databases. ADR 030.

workers/celery.py, workers/celerybeat.py

Caching

@cache_results builds a cache key from the function and its arguments, stores results in Redis, and can invalidate them. ADR 018.

lib/cache/decorators.py, lib/cache/lazy_cache.py

Testing

SmarterTestBase, which has no transaction rollback, so tests delete what they create, and an in-memory provider in place of every cloud call. ADR 013.

lib/unittest/base_classes.py, smarter-python-testing/SKILL.md

Adding a resource kind

The list of every file a new kind touches, from the Pydantic model to the React list page. New Feature Checklist.

smarter-sam-resource/SKILL.md

Graded Assignments

Assignment 1: Request Trace

Students trace an apply request and a describe request from the HTTP call to the database, and draw both as sequence diagrams with file and function names.

Turn in: the diagrams and the curl commands and responses, in a Markdown file in their fork.

Criterion

Pts

Exemplary

Developing

Accuracy

8

Every step correct, with file and function names.

Steps missing or out of order.

Evidence

4

Confirmed with logs or a debugger.

Inferred only.

Comparison

4

Explains where the two requests share code and where they differ.

Two unrelated diagrams.

API calls

4

Correct calls and explained responses.

Incorrect or unexplained.

Assignment 2: ORM Report

Students write a function that reports, for each account, the number of resources of each kind, first naively, then with as few queries as possible, and measure the number of queries of each version.

Turn in: a pull request against their fork with both versions, a test, and the query counts.

Criterion

Pts

Exemplary

Developing

Correctness

6

Both versions give the same, correct results.

Results differ or are wrong.

Optimization

6

Uses aggregation or prefetching; query count is constant.

Fewer queries, but still one per account.

Measurement

4

Query counts measured, for example with assertNumQueries.

Guessed.

Test

4

Tests results and cleans up its data.

No test, or leaves data behind.

Assignment 3: A New Field

Students add an optional field to the Guardrail resource end to end, with tests.

Turn in: a pull request against their fork, with passing tests and hooks.

Criterion

Pts

Exemplary

Developing

Completeness

7

Pydantic model, Django model, migration and broker updated.

A layer missing.

Tests

6

Validation and round trip tested; app tests pass.

No tests, or existing tests broken.

Conventions

4

Matches the surrounding code; pre-commit passes.

Inconsistent, or hooks fail.

Pull request

3

Clear description of what, why and how tested.

Empty description.

Capstone Projects

Students choose one, and present the pull request in Live session 2.

Capstone A: A Feature with an API, a Command and a Task

Learning objective. Build a feature that crosses the layers of a backend, from model to API to background work, with tests and documentation.

Students add a “last used” timestamp to Secrets: it is updated when a secret is read by a plugin or connection, reported by describe, and a management command and a scheduled Celery task list secrets unused for a configurable number of days.

What students turn in:

  • A pull request with the model change and migration, the broker and API changes, the command, the task, tests and documentation.

  • Passing tests (python manage.py test smarter.apps.secret) and hooks.

  • A five-minute walkthrough in Live session 2.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Correctness

25

Timestamp updated in every read path; command and task correct.

Some read paths missed.

Design

15

Writes are cheap and do not slow reads noticeably; explained.

A write on every read, with no thought to cost.

Tests

25

Model, API, command and task tested; Celery and time mocked properly.

Partial tests, or tests that depend on the clock.

Code quality and docs

20

Follows the app’s patterns; docstrings and docs page updated.

Inconsistent or undocumented.

Walkthrough

15

Clear explanation of the design and trade-offs.

Reads the diff aloud.

Capstone B: A Read-Only Reporting Endpoint

Learning objective. Design and build a REST endpoint that is secure, efficient, documented and tested.

Students add an endpoint under Smarter’s API that returns a summary of the caller’s account: the number of resources of each kind, prompts in the last 30 days, and spending against budgets. It must authenticate with an API key, show only the caller’s account, be built from a Pydantic response model, and appear in the Swagger documentation.

What students turn in:

  • A pull request with the view, the URL, the Pydantic response model, tests and documentation.

  • Example curl calls and responses.

  • A five-minute walkthrough in Live session 2.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Security

25

Authenticated, and scoped to the caller’s account, with a test that proves it.

Authenticated, but leaks other accounts’ data or is untested.

Correctness and efficiency

20

Correct figures; constant number of queries.

Correct, but one query per resource.

API design

15

Pydantic response model, consistent with the existing API and errors.

Hand-built dictionaries, inconsistent naming.

Tests

25

Success, empty account, unauthenticated and other-account cases.

Happy path only.

Docs and walkthrough

15

Appears in Swagger and the docs; clear walkthrough.

Undocumented.

Further Study