Software Architecture: Two-Week Online Course

A two-week online course on software architecture, taught on a large system that records why it is built the way it is: Smarter’s thirty-one Architecture Decision Records, and the code that implements them. The course is organized around the principles that working architects share as a vocabulary, above all The Twelve-Factor App, which ADR 004 makes binding on every pull request, and alongside it infrastructure as code, horizontal scalability, zero trust, extensibility and explicit data models. Every principle is traced to the files that implement it, listed under Principles in the Source Code. There are six 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers describing and reading an architecture and its decisions, and week 2 covers the twelve factors, styles, patterns and evolution. See Course Formats and Grading for the format, the grading scale and the course policies, and Software Architecture for an overview of the subject.

At a Glance

Students

Experienced developers moving toward technical leadership, and advanced computer science students.

Deployment

A clone of the repository. A running Smarter helps students confirm what they read.

Workload

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

Cost

Free.

Learning Objectives

By the end of the course, students can:

  1. Explain architecture as decisions and trade-offs between quality attributes.

  2. Describe a large system with the C4 model.

  3. Explain each of the twelve factors, and judge from the code whether a system follows it.

  4. Recognize infrastructure as code, horizontal scalability, zero trust, extensibility and explicit data models in a real codebase, and say what each costs.

  5. Verify ADRs against code, and recognize drift.

  6. Trace a request through Model-View-Controller, Django’s Model-View-Template and the LAMP stack, and say where a modern system departs from them.

  7. Compare architectural styles and patterns for a given problem, write ADRs, and plan the evolution of an architecture.

Technical Prerequisites

  • Required: at least two years of programming, or equivalent coursework.

  • Required: reading Python, and Git for browsing history.

  • Required: web application fundamentals: HTTP, databases, background jobs and caching.

  • Helpful: Docker and Kubernetes concepts, Django, and a diagramming tool.

Schedule

The file references in the lectures are listed in full under Principles in the Source Code.

Week

Item

Content

1

Lecture 1 (30 min)

What architecture is. Decisions that are hard to reverse, quality attributes and trade-offs. Principles as a shared vocabulary: the twelve factors, infrastructure as code, horizontal scalability, zero trust, extensibility and data models. A first look at Smarter: browser, CLI, API, workers, database, cache, model providers and Kubernetes.

1

Lecture 2 (30 min)

Describing architecture. The C4 model, views, and diagrams as code.

1

Lecture 3 (30 min)

Architecture Decision Records. Nygard’s format, and readings of ADR 001 on Django, ADR 004 on the twelve-factor app (an ADR that adopts a whole methodology), ADR 005 on manifests and ADR 024 on the broker model.

1

Live session 1 (90 min)

Groups draw Smarter’s container diagram together, and compare. Start Assignment 1.

2

Lecture 4 (30 min)

The twelve-factor app. Factor by factor, each shown in Smarter’s code: a settings module per environment, config validated by a Pydantic Settings class, attached resources, a multi-stage Dockerfile, stateless processes with sessions in Redis, four process types, health and readiness probes, logs to standard output, and admin work as manage.py commands and a Kubernetes Job. Smarter’s own twelve-factor guide is read critically.

2

Lecture 5 (30 min)

Styles, patterns and extensibility. A pattern review of Model-View-Controller, Django’s Model-View-Template (the Secret model, URLconf, views and templates) and the LAMP stack that Smarter descends from. Modular monolith (one Django app per resource family), ports and adapters in the infrastructure service layer, the broker model and its registry of kinds, and Django models for storage beside Pydantic models for contracts (ADR 031). Horizontal scalability with autoscalers, caching (ADR 018) and task queues (ADR 030).

2

Lecture 6 (30 min)

Zero trust and evolution. Every API call authenticated, every query filtered by owner, secrets encrypted, network policies, server-side request forgery blocked, and the model treated as untrusted. Then technical debt, API versioning (ADR 023), feature flags (ADR 022), fitness functions in CI, and architecture when coding agents write much of the code and the conventions live in CLAUDE.md and skills/.

2

Live session 2 (90 min)

Capstone presentations (about 5 minutes each, with 2 minutes of 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.

Principles 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/.

The Twelve Factors

Factor

How Smarter follows it

Where to look

  1. Codebase

One repository, deployed as local, alpha, beta, next and production. Each environment is a settings module that inherits from base.py, not a branch or a fork. The Helm chart lives in the same repository.

settings/, helm/charts/smarter

  1. Dependencies

Pinned Python requirements per purpose, an npm workspace for the React apps, and a Docker image that installs them into an isolated virtual environment. ADR 015.

smarter/requirements/, package.json, Dockerfile

  1. Config

Every setting is read from the environment, then validated and typed by a Pydantic Settings class. Placeholders such as SET-ME-PLEASE count as missing. ADR 007.

common/conf/settings.py, common/conf/env.py, .env.example

  1. Backing services

MariaDB, Redis, S3 and SMTP are attached by URL and credentials. File storage switches between S3 and the local file system by configuration alone. Email is reached through the infrastructure service layer.

settings/base.py (DATABASES, CACHES, STORAGES), docker-compose.yml

  1. Build, release, run

A multi-stage Dockerfile builds one image. Separate GitHub Actions workflows build it, release the Helm chart and deploy it, and semantic-release versions it. ADR 014, ADR 020.

.github/workflows/, release.config.js, Makefile

  1. Processes

Web processes keep no state between requests: sessions are stored in the Redis cache (SESSION_ENGINE), and uploaded files in S3.

settings/base.py (SESSION_ENGINE, STORAGES)

  1. Port binding

The app serves itself with uvicorn on a configured port. Nothing is injected into a separate web server.

deployment-app.yaml, asgi.py

  1. Concurrency

Four process types (web, worker, infrastructure worker, beat), each its own Kubernetes Deployment, and the web and worker types scaled out by autoscalers. Infrastructure tasks have their own Celery queue. ADR 009.

helm templates (deployment-*.yaml, hpa-*.yaml), workers/celery.py

  1. Disposability

Liveness and readiness probes on /healthz/ and /readiness/, and a graceful shutdown timeout on uvicorn, let Kubernetes replace pods freely.

urls/console.py, deployment-app.yaml

  1. Dev/prod parity

The same image, the same MariaDB and Redis, and the same Celery workers run under Docker Compose and under Kubernetes. Tests replace the cloud with an in-memory provider: a deliberate break in parity, worth discussing.

docker-compose.yml, infrastructure/providers/memory.py

  1. Logs

Logs go to standard output as a stream. Verbose logging is switched on per subsystem with feature flags, not by editing code. ADR 011.

lib/logging/, settings/base.py (LOGGING)

  1. Admin processes

Setup and maintenance run as manage.py commands in the same image, locally or as a Kubernetes Job. ADR 010.

initialize_platform.py, job-init.yaml

Beyond the Twelve Factors

Principle

How Smarter follows it

Where to look

Infrastructure as code

Terraform and Terragrunt create the AWS foundation, and a Helm chart, validated by a JSON schema, deploys the platform. Smarter is itself declarative: a YAML manifest states what should exist, and deploying an LLMClient creates its DNS record, certificate and Kubernetes ingress from a template. ADR 005, Cloud Infrastructure.

smarter-infrastructure, values.schema.json, llmclient/k8s/ingress.yaml.tpl, llmclient/tasks/deploy_default_api.py

Horizontal scalability

Stateless web pods behind Horizontal Pod Autoscalers, shared state in Redis and MariaDB, and slow work moved to Celery workers that scale on their own. ADR 018, ADR 030.

hpa-app.yaml, hpa-worker.yaml, lib/cache/

Zero trust

No request is trusted for where it comes from. API keys are hashed and checked on every call, querysets are filtered by owner, secrets are encrypted with Fernet, middleware blocks probing and brute force, pods talk only where the network policies of smarter-infrastructure allow, and plugin HTTP calls refuse private addresses. The model’s output is untrusted too: guardrails check both the prompt and the reply. ADR 016, Smarter Guardrail.

lib/drf/token_authentication.py, secret/models.py, lib/django/middleware/, plugin/plugin/safe_http.py, guardrail/services/pipeline.py

Extensibility

New resource kinds register a broker. New plugin types subclass PluginBase. New LLM providers that speak the OpenAI protocol are added with a Provider manifest, not code. New clouds implement the CloudProvider interface. ADR 024, How-To: Adding an LLM Provider to Smarter.

api/v1/cli/brokers.py, plugin/plugin/base.py, infrastructure/providers/base.py

Ports and adapters

All DNS, certificate, Kubernetes and email work goes through one facade, and the provider behind it is chosen by configuration. The application never calls the AWS SDK directly.

infrastructure/services/__init__.py, infrastructure/providers/

Data models and contracts

Two kinds of model with two jobs: Django models for what is stored, and Pydantic models for what crosses a boundary (manifests, settings, API contracts). An abstract base adds ownership and permission-aware querysets to every resource. ADR 017, ADR 031.

account/models/metadata_with_ownership.py, lib/manifest/, plugin/manifest/models/

Multi-tenancy

Every resource belongs to an account and a user, and every query is scoped by them. Account Management.

account/models/

Auditability

Every command sent through the API or CLI (apply, describe, delete, deploy and the rest) is written to a journal with its request, response and user. Smarter Journal.

lib/journal/models.py

API first

The CLI and the web console are clients of the same versioned REST API. ADR 006, ADR 023.

api/v1/

Feature flags

Behavior and diagnostics are switched at run time with Django Waffle, without a deployment. ADR 022.

lib/django/waffle/switches.py

Classic Patterns

Pattern

How Smarter follows it

Where to look

Model-View-Controller

Trygve Reenskaug’s pattern from Smalltalk at Xerox PARC (1979), later the shape of almost every server-side web framework: a model holds the data and its rules, a view presents it, and a controller turns input into changes to the model. In Smarter’s web console the pattern is split across the network. Django sends a page shell, a React app in the browser renders the view and handles the user’s actions, and JSON API views act on the models. ADR 019 still limits React to the Workbench; the packages show how far the code has moved since.

react/packages/smarter-secret-list/src/, secret/views/listview/

Model-View-Template

Django’s own version of MVC, which its FAQ calls MTV. The Django view does the controller’s job, the template does the view’s job, and the URLconf with the framework’s request handling is the remaining controller. One resource family shows all three: the Secret model, the URL patterns that route to its views, and the templates they render. ADR 001, ADR 025.

secret/models.py, secret/urls.py, secret/views/detailview.py, templates/react/secret-list.html

LAMP

Linux, Apache, MySQL and PHP (or Perl or Python): the open-source web stack named in 1998, on which much of the early web ran. Smarter is a descendant. The image is built on Debian Linux; MariaDB, the fork of MySQL by MySQL’s original author, is reached through Django’s MySQL backend; Python replaces PHP; and uvicorn, behind a Kubernetes ingress, replaces Apache. What LAMP did not have shows what changed since: Redis, Celery workers, containers, autoscaling and a React front end.

Dockerfile, docker-compose.yml, settings/base.py (DATABASES), llmclient/k8s/ingress.yaml.tpl

Graded Assignments

Assignment 1: C4 Diagrams

Students draw Smarter’s context, container and one component diagram (for example, of the broker layer), confirmed against the code.

Turn in: the diagrams (source and image) and a key.

Criterion

Pts

Exemplary

Developing

Accuracy

8

Confirmed in code and configuration.

Missing or invented parts.

Notation

4

Correct levels and labels.

Mixed levels.

Component diagram

5

Correct responsibilities and interactions.

Superficial.

Clarity

3

Readable.

Cluttered.

Assignment 2: ADR Verification

Students check two ADRs against the code, and report conformance and drift.

Turn in: a two-page report with code references.

Criterion

Pts

Exemplary

Developing

Understanding

5

Accurate summaries.

Misread.

Evidence

7

Specific references.

General.

Judgment

6

Clear verdicts with reasons.

None.

Recommendation

2

Code or ADR to update.

None.

Assignment 3: Twelve-Factor Audit

Students audit four of the twelve factors against the code. For each factor they state what it requires, find where Smarter meets it or falls short, and give a verdict: follows, partly follows, or does not follow. At least one verdict must test a claim in Smarter’s own twelve-factor guide against the code. The instructor assigns factors so that the class covers all twelve, and the findings are combined into a scorecard for the whole system, reviewed in Live session 2.

Turn in: a one-page table (factor, evidence with file and line references, verdict) and a half page on the most important gap found.

Criterion

Pts

Exemplary

Developing

Understanding

5

Each factor’s requirement stated accurately.

Copied or misstated.

Evidence

7

Files, settings and manifests cited for every verdict.

Verdicts without references.

Judgment

5

Distinguishes the letter of a factor from its intent.

Accepts the documentation at face value.

Gap analysis

3

The most important gap, its risk and a remedy.

None.

Capstone Projects

Students choose one, and present it in Live session 2.

Capstone A: An Architecture Review of Smarter

Learning objective. Review a real system against stated quality attributes, and recommend changes with evidence.

Students review Smarter against two quality attributes with scenarios, trace them through the architecture, assess one of the principles in Beyond the Twelve Factors (for example how far Smarter goes toward zero trust), rank the risks, and draft an ADR for the most important recommendation.

What students turn in:

  • A five- to seven-page review with diagrams and scenarios.

  • A ranked risk list and a draft ADR.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Scenarios

20

Specific and measurable.

Vague.

Analysis

25

Evidence-based.

Opinions.

Risks

20

Ranked.

Unranked.

Recommendation

20

Draft ADR, realistic.

Generic.

Presentation

15

Clear and on time.

Overruns.

Capstone B: An Architecture for a New Feature

Learning objective. Design a significant feature that fits an existing architecture, and record its decisions.

Students design a feature Smarter does not have, for example per-team model routing rules, a scheduled report resource, or multi-region deployment. They place it in the architecture with C4 diagrams, show that it keeps to the twelve factors and to Smarter’s other principles (stateless processes, the infrastructure facade, owned resources, a declarative manifest), and write ADRs for its two most important decisions.

What students turn in:

  • A design document with diagrams, and two ADRs.

  • A list of the existing ADRs and principles it depends on, and how it respects them.

  • A five-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Fit

25

Uses existing patterns (brokers, manifests, tasks, the infrastructure facade), and keeps to the twelve factors.

Ignores them.

Design

20

Complete.

Sketchy.

ADRs

25

Real decisions with alternatives.

Descriptions.

Dependencies

15

Identified and respected.

Ignored.

Presentation

15

Clear.

Unclear.

Further Study