Software Architecture: Four-Week Online Course

A four-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 and infrastructure that implement 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 twelve 30-minute recorded lectures and a 90-minute live session each week. Week 1 covers describing an architecture, week 2 decisions, their records and the twelve factors, week 3 styles, scalability, data and contracts, and week 4 infrastructure as code, zero trust, AI 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, and a running Smarter (Quick Start or from source) by week 2.

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, and write quality attribute scenarios.

  2. Describe a large system with the C4 model and other views.

  3. Read, verify and write Architecture Decision Records.

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

  5. Compare architectural styles, classic patterns (Model-View-Controller, Model-View-Template and the LAMP stack), integration patterns and data architectures, and recognize infrastructure as code, horizontal scalability, zero trust, extensibility and explicit data models in a real codebase.

  6. Explain architecture for cloud-native and AI applications, including cost as a quality attribute and the model as an untrusted component.

  7. Plan the evolution of an architecture, with fitness functions and migration strategies.

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.

  • Required by week 2: Docker, to run Smarter.

  • Helpful: 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

What architecture is. Decisions, quality attributes, trade-offs and the architect’s role. Principles as a shared vocabulary: the twelve factors, infrastructure as code, horizontal scalability, zero trust, extensibility and data models.

1

Lecture 2

Quality attribute scenarios. Making “scalable” and “secure” specific and measurable.

1

Lecture 3

Describing architecture. The C4 model, other views, and diagrams as code. A first look at Smarter: browser, CLI, API, workers, database, cache, model providers and Kubernetes.

1

Live session 1

Groups draw Smarter’s container diagram from docker-compose.yml and the Helm templates, and compare. Start Assignment 1.

2

Lecture 4

Architecture Decision Records. Nygard’s format, ADR 000, and ADR 004 as an ADR that adopts a whole methodology.

2

Lecture 5

Foundational decisions. Django, Docker, Kubernetes, manifests, the REST API and the broker model.

2

Lecture 6

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 (ADR 007), attached resources, a multi-stage Dockerfile and separate build, release and deploy workflows, stateless processes with sessions in Redis, port binding with uvicorn, four process types, health and readiness probes, logs to standard output (ADR 011), and admin work as manage.py commands and a Kubernetes Job (ADR 010).

2

Live session 2

Review of Assignment 1. A structured debate on one ADR. The instructor assigns factors for the twelve-factor audit. Start Assignment 2.

3

Lecture 7

Styles and extensibility. A pattern review: Model-View-Controller from Smalltalk to the web, Django’s Model-View-Template traced through the Secret model, URLconf, views and templates, the web console’s split of MVC between Django and React, and the LAMP stack beside Smarter’s Debian, uvicorn, MariaDB and Python. Then monolith, modular monolith (one Django app per resource family), microservices, event-driven and serverless. Ports and adapters in the infrastructure service layer, the broker registry of kinds, PluginBase for new plugin types, and Provider manifests for new LLM providers.

3

Lecture 8

Integration, asynchrony and horizontal scalability. Queues, task queues, async tasks, caching, stateless pods and Horizontal Pod Autoscalers.

3

Lecture 9

Data and contracts. The database, Django models for storage and Pydantic models for contracts, the ownership base class that makes every resource belong to an account, and API versioning.

3

Live session 3

Review of Assignment 2, and the class’s twelve-factor scorecard. A trade-off analysis workshop. Capstone proposals discussed. Start Assignment 3.

4

Lecture 10

Infrastructure as code and cloud-native architecture. Terraform and Terragrunt in smarter-infrastructure, a Helm chart validated by a JSON schema, and Smarter itself as a declarative system that turns manifests into DNS records, certificates and ingresses. Observability with logs and the journal.

4

Lecture 11

Zero trust and architecture for AI. ADR 016: every call authenticated, every query filtered by owner, secrets encrypted, network policies, and server-side request forgery blocked. Models as untrusted components, guardrails on input and output, function calling, and cost as a quality attribute. Where Smarter stops short of full zero trust, and why.

4

Lecture 12

Evolving architecture. Technical debt, fitness functions in CI (tests, coverage and pre-commit hooks), strangler migrations, feature flags, and architecture when coding agents write much of the code and the conventions live in CLAUDE.md and skills/.

4

Live session 4

Capstone presentations (about 6 minutes each, with 2 minutes of questions), and a course retrospective.

Assignments 1 to 3 are due before the next live session. Assignment 4 is due in the middle of week 4. The capstone proposal is due before Live session 3, and the capstone at the start of Live session 4.

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 and Scenarios

Students draw Smarter’s context, container and one component diagram, and write five quality attribute scenarios that the architecture should satisfy.

Turn in: the diagrams and the scenarios.

Criterion

Pts

Exemplary

Developing

Diagram accuracy

7

Confirmed in code and configuration.

Invented parts.

Notation

4

Correct levels and labels.

Mixed.

Scenarios

6

Source, stimulus, response and measure for each.

Vague goals.

Clarity

3

Readable.

Cluttered.

Assignment 2: ADR Verification

Students verify three ADRs against the code and the git history, including when each was implemented and whether it has drifted. One of the three is ADR 004, checked for the factors that the instructor assigned in Live session 2.

Turn in: a three-page report with code and commit references.

Criterion

Pts

Exemplary

Developing

Understanding

4

Accurate summaries.

Misread.

Evidence

7

Code and commit references.

General.

Judgment

6

Verdicts with reasons.

None.

Recommendations

3

Specific.

None.

Assignment 3: Principles Audit

Students audit four of the twelve factors and one principle from Beyond the Twelve Factors (for example zero trust or horizontal scalability) against the code. For each 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. Then they analyze the most important gap and its main remedy against their quality attribute scenarios, in a short trade-off matrix.

Turn in: a one-page table (principle, evidence with file and line references, verdict), and a two-page analysis of the most important gap, with the matrix.

Criterion

Pts

Exemplary

Developing

Evidence

7

Files, settings and manifests cited for every verdict.

Verdicts without references.

Judgment

5

Distinguishes the letter of a principle from its intent, including the guide’s claims.

Accepts the documentation at face value.

Trade-off matrix

5

Options scored against scenarios, with reasons.

Scores without reasons.

Writing

3

Clear.

Disorganized.

Assignment 4: An ADR of Your Own

Students write an ADR for a real decision in their own work, with context, alternatives and consequences, and a fitness function that would detect if the decision were violated.

Turn in: the ADR in the format of ADR.

Criterion

Pts

Exemplary

Developing

Context

4

Clear forces.

Missing.

Alternatives

6

Fairly compared.

None.

Consequences

5

Good and bad.

Benefits only.

Fitness function

5

Automatable and specific.

Vague.

Capstone Projects

Students choose one, propose it before Live session 3, and present it in Live session 4.

Capstone A: An Architecture Review of Smarter

Learning objective. Carry out an architecture review of a real system in the style of an architecture tradeoff analysis, and make evidence-based recommendations.

Students review Smarter against three quality attributes with prioritized scenarios, trace each through the architecture, complete the class’s twelve-factor scorecard, assess how far Smarter goes toward one principle in Beyond the Twelve Factors, identify risks, sensitivity points and trade-off points, and recommend changes with draft ADRs and fitness functions.

What students turn in:

  • A seven- to ten-page review with diagrams and a utility tree of scenarios.

  • Risks, sensitivity points and trade-off points.

  • A complete twelve-factor scorecard, with code references.

  • Two draft ADRs with fitness functions.

  • A six-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Scenarios

15

Prioritized and measurable.

Vague.

Analysis

25

Evidence-based, through code and configuration, including the scorecard.

Opinions, or the documentation restated.

Risks and trade-offs

20

Sensitivity and trade-off points identified.

Risks only.

Recommendations

20

Draft ADRs and fitness functions.

Generic.

Presentation

20

Clear and on time.

Overruns.

Capstone B: Architecture for a New Product on Smarter

Learning objective. Design the architecture of a new system that builds on an existing platform, and record its decisions.

Students design a product built on Smarter’s API, for example a multi-tenant customer support service, or an internal AI portal for a university. They produce scenarios, C4 diagrams down to components for the most important container, ADRs for its three key decisions, and a migration or rollout plan. The design keeps to the twelve factors and to Smarter’s principles, and uses its resources through the REST API rather than rebuilding them.

What students turn in:

  • A design document with scenarios and diagrams.

  • Three ADRs with fitness functions.

  • A rollout plan, and a six-minute presentation.

How it is graded (100 points):

Criterion

Pts

Exemplary

Developing

Scenarios

15

Drive the design.

Absent or ignored.

Design

25

Complete, with responsibilities and interfaces.

Sketchy.

Use of the platform

15

Uses Smarter’s resources and API appropriately.

Rebuilds what exists.

ADRs

25

Real decisions, alternatives, fitness functions.

Descriptions.

Rollout and presentation

20

Realistic plan, clear presentation.

Missing.

Further Study