Course Intro + Pawtograder Architecture I

Session: Wed Sep 9 · Course Intro + Pawtograder Architecture I · 65 min

Structure (Who's here → How it's graded → The vocabulary → The stack → The debt → Your slate):

• Arc 1: Who's In the Room (~15 min) — introductions, everyone in the room, including the AI conversation
• Arc 2: How This Works (~9 min) — the four bands, what counts as evidence, the two halves of the calendar
• Arc 3: The Vocabulary (~4–8 min) — the six infrastructure building blocks, then a real slide each on "what is a database" and "why is there an EventBridge". Lifted from CS 3100 l21-serverless
• Arc 4: The Stack (~24 min) — the thesis, then diagrams as evidence: inventory, communication, inside Postgres, then autograding and gradebook recalculation as sequences. Closes on the roadmap slide, which tells anyone feeling behind that every box has a date
• Arc 5: Where Complexity and Debt Live (~5 min) — one map slide, and the debt talked over it rather than listed on it
• Arc 6: The Project Slate (~9 min) — projects pinned to areas of the system
• Arc 7: Before Thursday (~3 min) — the one thing they must do tonight
• Takeaways (~2 min)

Narrative spine: You're joining a product that predates you, that real people use this semester, and that ships its first official release in January 2027. Today is the map: what it does, how it's built, where it hurts, and which part of it you might own.

The pitch is gone, on purpose. Everyone enrolled so far came in through an application, and all of them did the pre-application activity. They are already sold on the course, and most have already had Pawtograder running on their own laptop. Spending ten minutes telling them what the product is and why the course is interesting would be telling them what they already did. That time went to introductions instead.

What the cut pitch slides carried that still has to be said — say it inside your own introduction (see the Introductions slide): what Pawtograder is, that it runs ten courses this term including this one, and the blast radius. That's about two minutes of talking.

The architectural thesis is the spine of Arc 4, and it's stated on a slide before any diagram appears:

1. The database is the application — the logic lives in the database, and the database enforces security on the data.
2. We want the application to be sequentially consistent — one coherent order of events; what you just did is what you see.
3. Consistency is hard when you have to wait — so everything crossing the boundary gets a queue, in both directions. We never block on GitHub (outbound), and GitHub never blocks on us: a durable event bus buffers inbound webhooks indefinitely, and a real status page tells humans what happened.

Every diagram in Arc 4 is evidence for one of those three. Say so, and say it again in the takeaways. Students who leave with those three sentences can predict most of the codebase; students who leave with a component list can't.

The timing risk is now real. Fifteen minutes of introductions is worth it on a room this size, but it costs time you have to find elsewhere. The deck as written runs about 74 minutes in a 65-minute room. Pre-commit to the cuts before you walk in rather than discovering them at 11:15. The two designated cuts, in order, buy back six minutes and cost almost nothing (see the cut order below).

Arc 3 is the other variable. Everyone enrolled so far set up local Supabase and Postgres for the pre-application activity, so the floor is higher than it would be in an open-enrollment section. This arc is likelier to take four minutes than twelve. But ask rather than assume. The introductions will already have told you who took 3100 with you and who's coming back from co-op, so you'll know before you get here.

Arc 4 now runs 10 slides and it is over-provisioned on purpose. The designated overflow is one slide:

• "Sequence: How a Gradebook Cell Gets Its Value" — the richest slide in the deck and the easiest to promise for later. Skip it and say one sentence instead.

"How They Talk" is no longer the cut candidate — it was rebuilt with numbered arrows and a legend, and now runs about four minutes instead of eight. Keep it.

Never cut the two claim-3 slides (outbound and inbound). They're the part of the thesis a student can't reconstruct by reading the repo.

Cut order beyond that, in this sequence: drop the "Data Access: Prefer RPCs" slide, then shorten the debt talk over the complexity map to two bullets. Protect Arc 6 — bids are due 9/17 and this is the only session that explains the areas of the system.

Do not buy time back out of the introductions. On a roster this small, this is the session that decides whether the room talks to each other for the next fourteen weeks. If you're behind at 11:00, take it out of Arc 4, which is over-provisioned for exactly this reason.

Two things must not be cut, whatever the clock says:

• Arc 3, the vocabulary. A student who doesn't know what a database is gets nothing from five architecture diagrams. It's load-bearing for the map.
• The roadmap slide that closes Arc 4. It costs 90 seconds and it's what stops a first-generation-to-this-material student from concluding the course isn't for them.

The anti-intimidation thread runs through the whole deck, deliberately, in four places: the fragment on the learning-objectives slide ("describe" and "map" are the verbs), the small right-aligned full session: <date> pointers under the technical slides, the roadmap table at the end of Arc 4, and the "nobody has read all of it" line, which now lives in your own introduction rather than on a slide. If you only land one, land the roadmap.

Tone note: Be honest about the debt. The pitch of this course isn't "come work on our nice codebase," it's "this is what inheriting a real system feels like, and you'll get good at it."

Transition: Reminders first, then what we're doing today.

Reminders

• RELEASED: The Ticket Hunt. Due Wed Sep 16
• RELEASED: Onboarding: Gradebook Column Groups. Due Thu Sep 24
• RELEASED: Project Bids. Due Thu Sep 17

Keep this to 60 seconds. Deadlines and returning feedback only — questions about a specific assignment go to clinic or Discord.

Day one caveat: nothing is due yet, so this slide is really just "the hunt and the column-groups assignment are both live, start reading code."

Transition: Now, today.

CS 4535: Software Design & Delivery

Course Intro + Pawtograder Architecture I

©2026 Jonathan Bell, CC-BY-SA

Framing: Every other software course you've taken started from an empty directory. This one doesn't. You're walking into a running system with users, history, and consequences.

Say that in one sentence and move. Introductions are two slides away, and your own introduction is where you explain the product and its users.

What this session unblocks: They can't bid on a project (due 9/17) until they know what the areas of the system are. That's the real job of today.

Transition: Here's what you'll be able to do after today.

Learning Objectives

After this session, you'll be able to:

1. Describe the major components of the Pawtograder stack and how one request flows through them
2. Map the project slate onto areas of the system
3. State what you need working before Thursday

Notice what is not on that list. You don't need to understand any of this deeply today — "describe" and "map" are the verbs. Every box on today's diagrams gets its own session later.

Land the fragment before you go any further. Some of the room has never seen a row-level security policy, an event bus, or a Prometheus scrape, and forty minutes of architecture diagrams is exactly how you lose them quietly.

Say it in your own words, but say all three parts:

• Today is orientation. The verbs are "describe" and "map," not "implement."
• Nobody is expected to follow the details, and nothing today is assessed.
• Every single piece has a session with its name on it — you'll see the schedule near the end.

Time allocation:

• Arc 1: Who's In the Room (~15 min)
• Arc 2: How This Works (~9 min)
• Arc 3: The Vocabulary (~4–8 min) — prerequisite for objective 1
• Arc 4: The Stack (~24 min) — objective 1
• Arc 5: Where Complexity and Debt Live (~5 min) — objective 1, honestly
• Arc 6: The Project Slate (~9 min) — objective 2
• Arc 7: Before Thursday (~3 min) — objective 3

Only three objectives today, on purpose. Day one is oriented toward one deliverable and one deadline.

Introductions aren't on the objectives list and that's fine — don't apologize for them or promise they'll be quick. On a roster this small, knowing who everyone is matters more than anything else on the list.

Transition: Before any of that — it's a small room in here. Let's find out who.

Who's In the Room

It's a small room. By December you'll have reviewed each other's code. Let's start there.

Tell us:

1. Your name, and something you did over the summer
2. What you want out of this Fall — in this course, and after it
3. Your relationship with AI tooling: how you use it, how you want to use it, and how you don't

I'll go first.

On question 3: there is no AI restriction in this course. Use anything. I'm asking because nobody has this figured out, and a room's worth of honest answers is a better starting point than a policy.

Fifteen minutes, and protect them. Everyone enrolled, plus you. Roughly 90 seconds each, and you should be the one who models the length — if your own introduction runs five minutes, theirs will too.

Go first, and use your turn to carry what the cut pitch slides used to say. Four things, in about two minutes:

• Who you are and what you work on.
• What Pawtograder is and how long it's existed — say roughly how many students have been graded through it. That number is the credibility hook for the whole semester.
• Who's using it right now: CS 2000, 2100, 3100, 3650, 4530, 5001, 5004, 5008, 5010 — and this course. They'll submit this course's work through the system they're about to change. Break a student view and you've annoyed several thousand people across ten courses. Break an instructor grading view and a course can't return grades that week. Break it in December and you've done it during finals.
• The scale, honestly: about 300k lines of TypeScript, 417 migrations, 62 edge functions, 129 routes — and zero people who have read all of it, including me. Nobody reads it all. You read the part you own and you learn how to find the rest.

Then answer your own question 3 before you ask it of anyone else. They will calibrate to whatever you say, so say the real thing, including the parts where you don't reach for it.

Why question 3 is in the introductions and not on a policy slide. "Use anything" is a permission and nothing more, and a slide announcing it teaches nothing. This room has to compare notes for fourteen weeks, so the first data point is everyone in it saying out loud what they currently do. Expect real spread: someone drives an agent for everything, someone has decided it makes them worse, and both are welcome. Don't adjudicate any of the answers. Just note where the room is.

What you owe them in return, said once at the end of the round — "use anything" is an abdication if we stop there, so name the three things we actually provide:

• Instruction: the agents and workflows session, Wed 10/7 (s12) — structuring context, decomposing across sub-agents, judging when an agent is the wrong tool.
• A forum: a standing channel for prompts, setups, and failures. Treat it as a lab notebook.
• Clinic: bring agent output you're unsure about. "Should I trust this?" is a legitimate use of clinic time.

The practical hook, worth 20 seconds: the repo ships CLAUDE.md and AGENTS.md. Students who point their agent at those two files get dramatically better results than students who don't — good context beats good prompting, and it's the first concrete lesson in this course's AI posture.

Then the accountability line — don't soften it:

"The agent wrote it" isn't a defense at a demo day. You shipped it.

Listen for two things you need later today:

• Who took CS 3100 with you, and who's back from co-op or coming in from elsewhere. That answer sets the length of Arc 3 — four minutes or twelve — and you'd otherwise have to stop and ask for it there.
• Where each person's energy is, such as users and design, infrastructure, data, or product. You're announcing teams on 9/24 off bids you haven't seen yet, and this round is the only unfiltered version of that signal you'll get.

Close the round by saying the roster is still open, because this is the one moment where it lands. Admissions are rolling, there are seats, and the people best placed to fill them are sitting in front of you — they know who in their year would be good at this and would never have heard of the course otherwise. Ask them directly to send someone to the apply page. Two framings that both work: a small team is an advantage and you'd still take a few more, or simply that you'd rather they picked the next teammates than that a seat went empty.

Do not put a headcount on a slide, here or anywhere. The number moves, and a student who hears "there are eight of us" on day one reads a later arrival as a change of plan rather than the normal thing it is.

TODO: Name the actual forum channel once Discord is set up. Also decide whether staff introduce themselves here or at Thursday's working session, where they'll actually be floating.

Deliberate contrast with CS 3100, if it comes up. AI is restricted there in weeks 1–5 because the skill being built is the typing. Here the skill is judgment, integration, and accountability — and the agent doesn't change any of those.

Transition: That's the room. Here's how the room gets graded.

Grading: Four Bands, No Points

Band	Means	Letter
Pass	Trusted to contribute under review	B
Credit	Trusted to exercise judgment, not just execute	A−
Distinction	Trusted to own what ships (four of five)	A
High Distinction	Trusted to extend the system	A, and a letter with something in it

Each band is a published list of things you've demonstrably done. Every band requires the one below it. You declare which you're working toward on Oct 1, and you can change it either way until Dec 3.

There's no way to reach an A while being weak at one of the eight outcomes.

Lead with what is gone. No points, no weighted average, no category you can be weak in and average your way past. Students have never seen this and won't believe it until you say it twice.

Say where Pass sits, because it is the thing they will misread. Completing Pass means you shipped to production, reviewed six PRs, wrote three postmortems, taught a reading, and cut a vertical slice in onboarding. That is a B: it is the work the course asked for and you did all of it. Credit and Distinction are what you add on top. Nobody gets a C for doing the whole course.

Land the fragment. Pass is the comprehensive band: it requires all eight learning outcomes at minimum standard, and Credit, Distinction and High Distinction each require everything below. So there's no route to an A that skips operations, or code review, or talking to a user. A thousand points couldn't do that, because points average.

The question you will get: "so what do I actually have to do?" Answer: read the band lists in the syllabus, they're published and they're the whole contract. Don't recite them here.

The second question you will get is whether High Distinction is worth chasing when Distinction already earns an A. Say the honest thing: everyone who asks gets a reference letter, and always has. What High Distinction changes is what the letter can truthfully say.

Cite the source if anyone asks whether this is invented: task-oriented portfolio assessment, Cain, Grundy and Woodward, European Journal of Engineering Education 43(4), 2018. It's not a local experiment.

The line that used to live on the cut "Deal" slide, and is worth keeping somewhere: I define the minimum for an A; you decide the minimum for your goals. It'll be tested in week 3 when someone asks "is this enough?" The answer is: enough for what you said you wanted — which is why you just told the room what you want out of the semester.

Transition: So what do you actually hand in? Almost nothing.

What That Means In Practice

Almost nothing here is a submission. You're graded from the things professional work produces anyway: pull requests, review threads, commit history, design notes, postmortems, dashboards.

In December you write a Learning Summary Report: the band you're claiming, and a link to the artifact that satisfies each requirement. I verify the claim rather than re-grading the work, because the work was already reviewed when it happened.

Which makes the report quick to write if you did the work, and unwritable if you didn't.

This is the slide that answers "how do I know where I stand." Three checkpoints, Oct 14, Nov 5 and Dec 3. At each one you get a written per-student judgment: on track for your declared band, yes or no, and why. Promise them bluntness now so it's not a shock in November.

Say why the checkpoints are blunt. A lenient midpoint isn't kindness. It moves the bad news to a week when nobody can act on it.

Attendance is the one thing that is not a band requirement. It's a gate: it earns nothing on its own and it caps your letter regardless of which band you complete. Point at the table in the syllabus and move on.

Transition: The calendar has two very different halves.

Two Phases, Two Rhythms

Weeks 1–3: Onboarding

• Lecture every session
• The Ticket Hunt: file two, triage two. Due 9/16
• Column Groups: everyone builds the same feature, alone. Due 9/24
• Bids due 9/17 · teams announced 9/24

Weeks 4–14: Studio

• Mon: standup + clinic
• Wed: tech talk or student presentations
• Thu: team work, game day, or demo day
• Demos every two weeks. Game days unannounced.
• You will hold two roles: a project team and a cross-project function

Feature freeze is Mon Nov 23. Weeks 13–14 are hardening, documentation, and ops playbooks for the January handoff. Nothing new lands after the freeze.

Flag the async week now (Oct 2–13): instructor at OOPSLA/ISSTA. Three async sessions and a two-week sprint they plan on Oct 1. Students who miss this announcement lose two weeks.

Game days: say only that they exist and are graded on response, not on being unbroken. Don't explain the mechanics; the surprise is the pedagogy.

The two-roles bullet needs 30 seconds and no more. Every student is on a project team and also on one cross-project function (release and CI, accessibility, observability, or docs and handoff), one member per project team. The function is a standing responsibility, not a second project. Detail lands at studio kickoff on Sep 28. Today they only need to know it exists, because it changes how they read the slate. If anyone asks why: it is how TUM runs iPraktikum, it is roughly Team Topologies, and it is how most companies they will join are organized, including the failure modes.

Say the team arithmetic here rather than making them wait for Arc 6: on today's roster that's two teams, and two of the seven projects. It changes how they listen to the slate and it stops one person deciding they've already got a team of one. Say "on today's roster" and mean it — the number moves if late enrollments land, and you don't want to walk that back on Sep 24.

Transition: That's the rhythm. Before the map, ninety seconds on what the pieces of a map even are.

Before the Diagrams: The Vocabulary

Cloud platforms give you a standard set of parts. Every architecture diagram you'll see this semester is made of these six, and nothing else.

Database

Structured data you can query

ours: Postgres

Object storage

Files too big for a database

ours: Supabase Storage

Queues and event buses

Work that waits its turn

ours: pgmq, EventBridge

Cache

A fast copy of hot data

ours: Upstash Redis

API gateway

One front door, with a lock

ours: the Supabase gateway

Observability

Logs, metrics, traces

ours: Sentry, Prometheus

Plus one more: serverless compute — code that runs on demand and then disappears. Ours are the edge functions.

Every one of these six gets its own session — schedule at the end of today

Lifted from CS 3100 l21-serverless, "Infrastructure Building Blocks." If your section took 3100 with you they have seen this grid; say so, and move faster.

Why this arc exists at all: the next four slides name Postgres, edge functions, pgmq, EventBridge, Realtime and Prometheus in the space of about a minute. A student who isn't sure what a database is stops following at slide one and never says so.

Do not lecture the grid — name each box in one sentence and move. Four to eight minutes for the whole arc, and with this cohort it's likely the short end. Every one of them stood a Postgres and a Supabase stack up on their own laptop for the pre-application activity, so "database" and "object storage" are not abstractions to them.

The framing that makes it stick: these are design patterns for infrastructure. You don't build them, you rent them and compose them. The pattern is the same whether the system is a monolith or serverless; what changes is who operates it.

Two boxes get their own slide because they're the two students actually stumble on: what a database is, and why there's an event bus in front of our webhooks. The other four are one sentence each.

You already know who's in front of you from the introductions. Set the pace from that rather than asking again here.

Transition: Start with the one that everything else leans on.

What a Database Actually Is

Somewhere to put data that survives a restart — and, more importantly, somewhere you can ask questions of it. The right kind depends entirely on the questions.

Relational (SQL)

Rows, columns, and relationships between tables. Powerful queries, real transactions, rigid schema.

Postgres, MySQL

SELECT s.*, a.title
FROM submissions s
JOIN assignments a
  ON s.assignment_id = a.id
WHERE s.student_id = ?

Document (NoSQL)

JSON-shaped blobs. Flexible schema, fast to start, weak at questions that span records.

MongoDB, Firestore

{
  student: "alice",
  scores: [85, 92, 78]
}

Key-value

Fetch by key. Blazing fast, no queries at all.

Redis, DynamoDB

GET user:12345
SET session:abc {...}

Why Postgres, reason 1: our questions are relational

"Every submission by this student, across every assignment, with the assignment title."

That's a join, and joins are what SQL is for.

Reason 2: it can enforce the rules itself

Postgres has row-level security — a policy attached to the table.

"A student sees only their own submissions" becomes a property of the rows, not something every query has to remember.

Reason 2 is the bigger one, and it shapes almost everything else you'll see today.

Full session: Mon 9/14 — Architecture II: Supabase, RLS & Student-Data Privacy

Adapted from CS 3100 l21-serverless, "Databases: Structured Data Persistence."

Lead with the query, not the technology. The choice follows from the questions you need to ask. Our questions — submissions by student, averages by section, who hasn't submitted — are all relationships between students, courses, assignments and submissions. A document store makes you fetch everything and filter in application code.

The tradeoff, said once: relational gives you powerful queries and transactions at the cost of a rigid schema. Document gives you a flexible schema at the cost of query power. Key-value gives you speed and nothing else.

Note that we use all three. Postgres is the database, Redis is a cache, and there's plenty of jsonb inside Postgres. "Pick one" isn't the lesson; "pick per job" is.

Reason 2 is the one to spend time on, and it is the point of putting this slide in the deck at all.

The usual way to answer "can this person see this row?" is a WHERE clause somewhere in application code — which means every query has to remember, every new client has to remember, and one forgotten check is a data leak. Row-level security inverts that: the policy lives on the table, so the database answers the question whether or not the caller thought to ask it.

Make it concrete without teaching it yet: the same SELECT runs by a student and by an instructor and comes back with different rows. Nothing in the application changed.

Say plainly that this is why we picked Postgres, not just that Postgres happens to have it. Given the data we hold — real grades for ten courses — we wanted authorization to be a property of the data rather than a convention in the code. That's a design decision with a cost, and they'll meet the cost on Monday: the check runs once per row, so a policy that calls a function is a performance cliff.

This is deliberate foreshadowing of claim 1 of the architectural thesis, two arcs from now ("the database is the application, and it enforces security on the data"). Plant it here and the thesis slide lands as a confirmation rather than a surprise. Don't explain RLS mechanics yet — that's Monday's whole session.

Transition: Second one. Something has to happen when GitHub wants to tell us something.

Webhooks, Queues, and Why There Is an EventBridge

A webhook is just an HTTP POST that someone else sends you, when something happens on their side. No magic. GitHub calls us; we didn't ask.

A queue or event bus sits in the middle and holds the message. The sender is done once it's accepted; delivery is somebody else's problem.

So: if we're deploying when a student pushes, a raw webhook is lost forever. GitHub gives up quickly. EventBridge keeps trying long after GitHub would have stopped and we pay for the privilege.

Comes back on Thu 9/24 (Monitoring) and Thu 10/22 (Game Day 1)

Adapted from CS 3100 l21-serverless, "Message Queues: Asynchronous Communication." The queue idea is the same; the specific instance is ours.

Define the word before using it. "Webhook" is spoken twenty times this semester and never defined. It's an inbound HTTP POST you didn't initiate. That's the whole concept.

Then the actual reason we have an event bus, which is the answer to "why not just let GitHub call us directly?":

• GitHub retries a failed webhook for a limited window, then drops it.
• A deploy, a bad migration, or a cold start can easily outlast that window.
• A dropped push means a submission that was never graded, and no error anywhere — nobody is watching GitHub's delivery log.
• EventBridge decouples GitHub's delivery from our availability, and its redelivery window is much longer.

Worth stating: our github-repo-webhook function only accepts the EventBridge envelope, not a raw GitHub POST. That surprises people who try to curl it.

The general principle, which is the transferable bit: a queue converts "you must be up right now" into "you must be up eventually." That's the same retry-and-backoff idea, but bought rather than built — and you'll meet it again inside Postgres, where pgmq does exactly this for gradebook recalculation.

Plant the flag here: this is claim 3 of the architectural thesis, two slides away. Say "hold that thought" rather than explaining it now.

Callback: ask them to remember this slide on Game Day 1, where the failure is precisely an event that never arrived and produced no error.

Transition: That's the vocabulary. Now the actual map.

Pawtograder Has One Architectural Thesis

1. The database is the application. The logic lives in the database, and the database enforces security on the data.

2. We want the application to be sequentially consistent. One coherent order of events. What you just did is what you see.

3. Consistency is hard when you have to wait. So everything crossing the boundary gets a queue, in both directions. The outside world is allowed to be on fire — and so are we.

Every diagram for the rest of today is one of these three claims.

Give them the thesis before the diagrams, not after. Five architecture diagrams with no thesis is trivia. The same five diagrams as evidence for three claims is an argument they can actually hold on to — and can disagree with, which is better.

Claim 1 is a real position, not a description. Most teams put logic in the application tier and treat the database as storage. We did the opposite, deliberately. Say that it's a choice, that it has costs, and that they'll feel both this semester:

• Upside: authorization can't be forgotten, because it's not in the code path — it's in the rows. Business rules can't be bypassed by a second client.
• Cost: the logic is in SQL, in 417 migrations, and it's harder to read, test and refactor than TypeScript. You can't understand a feature by reading only the TypeScript.

Claim 2 is what users actually demand, even though they would never use the phrase. A grader saves a rubric check and expects the total to be right. An instructor releases grades and expects every student to see the same thing.

Claim 3 is the interesting one, and it's the one that explains the shape of the whole system — every queue, every worker, every retry. It gets two slides, because it runs in both directions: we never block on GitHub, and GitHub never blocks on us.

How to use this slide later: when a student asks "why is this an edge function and not a server action," or "why is there a queue here," point back at this slide. Nearly every "why is it like this?" resolves to one of the three.

Transition: Claim one. And it's stranger than it sounds.

The Stack: Everything In Play

Level 0: the inventory. No arrows yet, on purpose.

They now have the vocabulary from Arc 3, so this slide is just naming our specific instances of it. Don't re-explain the categories — point at each box and say which building block it is:

• Next.js — the whole frontend, one app, App Router
• Postgres — the database, but also more than that (two slides from now)
• Edge Functions — the serverless compute. Deno, and only for talking to the outside world
• GitHub App + Actions — repos, and the machine that actually runs autograding
• Discord — help-request and regrade notifications
• Chime — video in the office hours queue
• Sentry + Prometheus/Grafana — the observability box, answering "what threw?" and "what is trending?"

The grouping is the argument. Column 3 is the stuff that can break without us doing anything, and column 4 is the only reason we would notice. That framing pays off at s07 and on every game day.

Three minutes, maximum. If Arc 3 landed, this slide is fast; if you find yourself re-teaching a category here, Arc 3 was too fast.

Transition: Now the interesting part — who talks to whom, and how.

How They Talk

1. rpc() — most reads and writes
2. Realtime broadcast — nothing polls
3. functions.invoke()
4. service-role available, prefer user-role
5. pg_cron + pg_net — the database calls out
6. webhook, via EventBridge
7. dispatch grade.yml
8. OIDC-authenticated callback

Left off on purpose: Discord and Chime hang off the edge functions, Sentry collects exceptions from both tiers, Prometheus scrapes the functions.

Eight numbered arrows, three boxes. Point at numbers, not at labels — that's the whole reason the labels moved into the legend.

Narrate four of the eight, as evidence for the thesis. Skip the rest:

• 1 and 2 together — rpc() down, Realtime back up. That round trip is 90% of the app, and nothing polls. Claim 1: the work happens in the database.
• 5 — pg_cron + pg_net, the database calling the edge functions. This is the one that surprises everyone. Claim 1 again: the DB is also the scheduler.
• 6 — the webhook arrives through EventBridge, never from GitHub directly. Claim 3, inbound.
• 8 — the grading callback is OIDC-authenticated, so we trust what the repo proves rather than who called us.

Then the question: which of these eight can fail silently? Take two answers and don't resolve it. It's the setup for s07 and Game Day 1.

Timing gate: you should leave this slide by about 11:05, and it should take about four minutes now.

The four things left off the diagram are in the footnote, deliberately — they were what made the earlier version unreadable, and they're all "one function talks to one vendor," which needs no picture. The inventory slide already showed them.

Transition: Two of those arrows point into the database. Let's go inside it.

The Database Is the Application

Authorization, business logic, queueing, scheduling and fan-out all live in Postgres. Not in the app.

Full session: Mon 9/14 — Architecture II: Supabase, RLS & Student-Data Privacy

This is the slide that reframes the whole codebase for them. Students arrive assuming the Next.js app is the system and the database is storage. It's the other way around.

Four claims, in order:

1. RLS is authorization, and it runs per row inside the query — Monday's whole session.
2. Triggers are business logic. A rubric check landing is what enqueues a recalculation.
3. pgmq is a queue living in the database, and pg_cron is the thing that wakes workers up.
4. Realtime broadcast is the fan-out, and it's itself authorized per channel.

Consequence worth stating plainly: you can't understand a feature here by reading only the TypeScript. The migrations are load-bearing.

Claim 1, restated as the thing they should remember: authorization isn't a code path you could forget to call. It's a property of the rows.

Transition: That's claim one. Claim two is what we want in exchange — and claim three is what stops us having it.

Consistency Is Easy Until You Have To Wait

Block on the outside world

Commit, then enqueue

The transaction only depends on Postgres. Postgres is up, so we are up — and the work that needs GitHub happens whenever GitHub comes back.

GitHub had a worldwide outage on August 17. Grading kept queueing.

Queues, retries and dead letters in depth: Thu 9/24 — Monitoring & Incident Response

This is claims 2 and 3, and it is the most useful slide in the deck for predicting how the codebase looks.

Layout note: the two lanes are deliberately two separate diagrams in a two-column grid, so they sit side by side for direct comparison. A single mermaid graph with two subgraphs stacks them vertically, which loses the contrast — don't merge them back.

Define sequential consistency in one sentence, without the formalism: everyone sees the same one order of events, and a read reflects the writes that came before it. A grader saves a rubric check; the total is correct on the next read. No "refresh and hope."

Then the tension, which is the whole point. Inside one Postgres transaction, that guarantee is nearly free — that's what a database is for. The moment a request has to call GitHub, Discord, Chime or AWS, you're choosing:

• Wait — and your consistency now depends on somebody else's uptime, their rate limits, and their p99.
• Enqueue — commit what you own, hand the rest to a queue, and let a worker retry.

We enqueue. That is why the system looks the way it does — pgmq inside Postgres, pg_cron waking workers, EventBridge in front of the webhooks, circuit breakers per GitHub org, dead-letter queues behind the gradebook.

The live example, and it is genuinely recent:

• Aug 17, 2026: GitHub had a worldwide outage starting about 9:40 AM EDT — website, API, Actions, Pull Requests, plus SAML/OIDC auth and SCIM. Root cause was traffic hitting a new peak while a component in their Central US data center failed to scale.
• Sep 1, 2026 — nine days ago: commit-processing delays and degraded Pull Request performance.
• Neither of those is hypothetical, and neither is under our control. The design question isn't "how do we stop GitHub failing" but "what do our users experience while it does."

TODO — check githubstatus.com on your way to class. If GitHub is degraded that morning, open with it. It's the best possible cold open for this slide and it costs nothing.

The honest caveat, worth 30 seconds: async isn't free. You have traded a blocking failure for an eventual one, and eventual failures are much harder to see. That's the exact setup for Game Day 1, where CI has been dead for hours and nothing logged an error.

Transition: That's us surviving them. Now the mirror image — them surviving us.

And We Are Allowed To Be On Fire Too

The same trick, pointed inward. Nothing outside should have to wait on us either.

For machines: a durable buffer

GitHub's webhooks land on an event bus, never on us directly.

• Buffers and retries with backoff
• Dead-letter queue for what still fails
• Durable audit trail, and replay
• Smooths a burst of pushes into a rate we can take

We can be down for a deploy, a migration, or a bad afternoon. The events wait.

For humans: an honest status page

A real page, served instead of the app.

• HTTP 503 with a Retry-After header
• Title, message and an ETA, set per window
• Refreshes itself, so nobody sits reloading
• Runs on its own replicas — it survives what took the app down

Users find out what happened and when we're back.

And we choose honest downtime over a half-working app: a read-only database is "unavailable, but unpredictably so."

Planned windows and rollback: Thu 9/17 · incident response: Thu 9/24

This is the second half of claim 3, and it is the half students never think about. Everyone can see why we should not block on GitHub. Almost nobody asks what GitHub experiences when we are the broken one.

The machine channel. GitHub's webhooks go to an EventBridge bus, and the bus talks to github-repo-webhook — never GitHub straight to us. The bus buffers, retries with backoff, dead-letters what won't go, keeps an audit trail, and lets us replay. It also smooths bursts, so a wave of push and workflow_run events can't flatten the function.

Worth being concrete about the security shape, because it explains the code: there are two secrets guarding two different hops. GITHUB_WEBHOOK_SECRET verifies GitHub's HMAC at the ingress. EVENTBRIDGE_SECRET guards the last hop — the function checks that header and does not re-verify the GitHub signature. That's why you can't point the GitHub App's webhook URL at the function and why curling it fails.

The human channel. During a planned window the web-host ingress is repointed at the maintenance Service. That page has its own replicas with topology spread, precisely so it stays up during the node drain that took the app down. It answers 503 with Retry-After, and the title, message and ETA are set per window.

Then the design argument, which is the actually interesting part — from docs/operations/planned-maintenance.md:

• The tempting move is to stay up read-only against the standby. For us that's a trap.
• Nearly every real user action is a write: submitting, autograder result writes, grade and regrade saves, help-queue updates, even auth and session writes.
• Read-only means those fail scattered across the UI — some pages load, then an action 500s with cannot execute INSERT in a read-only transaction.
• That's more confusing than being cleanly down, and it generates more support load, not less.
• So: honest downtime. Short window, clear page, come back whole with reads and writes together.

The transferable lesson, and say it in these words: availability isn't a number, it's what your users experience. "Up but lying" is worse than "down and honest."

TODO: the page's support info is whatever you put in the per-window message. Decide whether you want a standing Discord or support link baked into the template before January.

Transition: Enough claims. Two real jobs, end to end.

Sequence: How Autograding Works

CI in depth: Wed 9/23 · what it tests: Thu 9/24

Read this as the thesis in action. Every write lands in Postgres immediately; everything that needs GitHub is a separate hop that's allowed to fail and be retried. That's claim 3 with fourteen steps attached.

Three edge functions are hiding behind "Edge Functions": github-repo-webhook, autograder-create-submission, autograder-submit-feedback. Say the names — students will grep for them.

The five beats worth pausing on:

• Step 5: we dispatch the workflow. The student's push doesn't trigger grade.yml on its own.
• Step 7: the action authenticates with a GitHub OIDC token, which proves which repo the commit came from.
• Step 9: it gets back a one-time URL to download the private grader repo. That's how the solution stays secret.
• Step 10: grading is driven by pawtograder.yml in the grader repo.
• Step 14: nothing polls. Again.

The honest aside: create-submission unzips the student repo inside an edge isolate with a 256MB heap cap. A student who commits node_modules or a Gradle cache kills the worker mid-request. That class of failure is exactly what this course is about.

Transition: Now the one that generates the most support tickets.

Sequence: How a Gradebook Cell Gets Its Value

Queues, retries and dead letters again on Thu 9/24 — Monitoring

Why this diagram and not a simpler one: this is the most-complained-about part of the product, and every complaint is really about this pipeline.

The expression language is mathjs plus custom functions — mean, sum, countif, drop_lowest, case_when. mean weights by max_score; missing counts as zero unless excused; an override beats a computed score. Those semantics are why "my grade is wrong" tickets are hard.

Steps 8 through 10 are the interesting failure mode. Updates carry an optimistic version. Lose the race, get re-enqueued with backoff, and after too many attempts the row lands in a dead-letter queue. A row can sit flagged as recalculating with nothing scheduled to pick it up — that bug was real.

Say the number out loud: a class of 500 students with 40 columns is 20,000 cells, and a change to one column recalculates every dependent column for every student. That's the whole performance story in one sentence.

This is where sequential consistency gets expensive, and that is the point of showing it. Claim 2 says a grader's save should be immediately correct everywhere. Delivering that across 20,000 cells means optimistic versioning, backoff, and a dead-letter queue — the machinery in steps 8 through 10. The guarantee isn't free; this diagram is the invoice.

Treat this as the backup slide. If you're past 11:12, skip it and say the one sentence instead: "the same queue pattern runs inside Postgres for the gradebook, and it's the hardest part of the system." Then point at the roadmap slide.

Transition: One convention falls out of all of this, and it will shape your first PR.

Data Access: Prefer RPCs

For data operations, reach for a Postgres RPC before a server action or an edge function.

RPC in Postgres

• Runs next to the data
• Authorization already applies
• One round trip
• The default for reads and writes

Edge function

• For integrations that call out: GitHub, Discord, AWS
• Not a general data path
• Deno, so no @/ alias and no Node imports

Types come from the schema. After a migration, run npm run client-local — never hand-edit the generated types.

Frame this as a consequence, not a rule. If the database is the application, then data access belongs in the database — an RPC runs next to the data with authorization already applied. A server action that queries Supabase directly moves logic back out into the app tier, which is the thing claim 1 rejects.

Why it is on the day-one deck at all: it's the single convention most first PRs violate. A student adds a route handler that queries Supabase directly, and review sends it back.

The Deno gotcha is worth 20 seconds: files under supabase/functions/ are Deno. The @/* path alias doesn't work there. Students lose an afternoon to this exactly once.

Do not get into TableController here. It gets a whole session on 9/16, Architecture III: The Client, which is where the frontend conventions live.

Transition: That's the whole map. Before we go anywhere else — a word to anyone who feels behind.

Today Is the Map. The Detail Comes Later.

What you saw today	Where it gets a whole session
Databases, RLS, student-data privacy	Mon 9/14 — Architecture II
The frontend: App Router, types, TableController	Wed 9/16 — Architecture III: The Client
Migrations, down paths, rollback	Thu 9/17 — Architecture IV: Deployment
CI/CD, feature flags, dark launches, trunk-based development	Wed 9/23 — Software Processes & Continuous Delivery
E2E and visual acceptance testing	Thu 9/24 — Testing
IaC, drift, Sentry/Grafana, incident response	Thu 10/1 — Tech Talk: Operations
Agents, context, sub-agents	Wed 10/7 — Tech Talk: Agents & Workflows
Risk registers, release readiness	Wed 11/18 — Tech Talk: Risk & Release Readiness
All of it, under time pressure	Game days — 10/22, 11/5, 11/19

Today's only job is that the picture makes sense. If you can point at a box and say roughly what it does, you're exactly where you should be.

This slide is the antidote to the last twenty minutes. Some of the room has just watched five architecture diagrams go by and quietly concluded they're behind. They aren't. Say so directly.

Deliver it as reassurance, not as a syllabus reading. Don't read the table aloud — put it up, let them scan it, and make the point out loud:

"Nothing on the left is something you were supposed to absorb today. Every row has a date next to it. Today I only wanted you to see how the pieces connect."

Then the honest version of the same point: none of us understood this system on day one either. The thing you're practising this semester is working usefully inside a system you only partly understand — which is the actual job, and is why "describe" and "map" were the verbs on the objectives slide.

Do NOT cut this slide. It costs 90 seconds and it's the difference between a student who asks a question in clinic on Monday and one who quietly assumes this course isn't for them. If you're short on time, cut the gradebook sequence instead and point at this table.

Callback: this pairs with the fragment on the learning-objectives slide. If you skipped that one, land it here instead.

Transition: That's the happy path. Now the part the brochure leaves out.

Complexity Is Not Evenly Distributed

The claim: size and difficulty are different axes. components/ is big and boring. lib/ is smaller and is where people get hurt.

TODO — this is the slide that needs your judgment, not mine. The colors above are my inference from reading the repo. Correct them. Which three or four regions do you actually consider hazardous, and why? Candidates from the code: the gradebook query language, the realtime controller hierarchy, the autograder submission path, and the RLS policy surface.

Then connect it forward, but honestly: some of these hot regions have a project pointed at them and some don't. The gradebook and the ops surface are hazardous and off the slate this term — say so. "We know, and we chose not to send a team at it in a release semester" is a more credible thing to hear than a slate that claims to cover everything.

---

THE DEBT TALK LIVES HERE — deliberately no slide for it. Say it over this map, off the cuff, pointing at regions. A bulleted list of your own product's failings on screen reads as an apology; the same words spoken over a diagram read as candour. Nothing here is a secret and nothing here is an accident — it's what shipping under a deadline with student labour produces.

Raw material, in your words, as much or as little as you want:

• 417 migrations with no squash point — schema history is effectively append-only.
• Gradebook performance degrades with class size, and it fails at both ends: the query layer and the 1000-row React table.
• RLS policies that call functions — correct, and a performance cliff. Monday's whole session.
• Local dev fragility — the pinned CLI version, stale Docker volumes, audit partitions. They meet this tomorrow.
• Uneven test coverage — 46 Playwright specs against 129 routes.
• Observability gaps — failures that produce no error anywhere. This is the Game Day 1 premise.

The line worth landing, whatever else you cut: every codebase they'll ever join looks like this, and the ones that claim otherwise are lying or new.

Why this matters more than it looks: students who believe you're being straight with them about the state of the system will bring you a real problem in week 6 instead of hiding it. This is the two minutes that buys you the semester.

Transition: Which brings us to what you might own.

Seven Projects, Seven Parts of the System

Project	Where it lives	What you'd be doing
Usability Strike Force	app/, components/	Studies with real users, then shipping the redesign
Accessibility Strike Force	student pages, tools/a11y-judge/	WCAG AA against real screen readers, then fixing what fails
Office Hours Reconceptualization	help queue, Realtime, Chime	Full product redesign, research through deploy
Docusaurus Integration	plugins/, public APIs	Schedule sync, embedded polls, search across two ecosystems
Paper Exam Generation & Grading	mostly new code	Variant generation, barcodes, scan ingest, OCR, grader UX
GitHub → Forgejo Migration	GitHub App, repo automation, CI	Provisioning, permissions, a migration path for live courses
Coder Workspaces Integration	auth, provisioning, grading actions	SSO and one-click cloud dev environments

Every project spans the full lifecycle. None of them is only frontend or only backend.

This slide is the whole reason today happens before 9/17. Bids are ranked preferences; teams are announced 9/24.

Give each project about 60 seconds and do not improvise. Say the arithmetic out loud before you start: today's roster is two teams, so two of these seven run and five don't. If you skip that, someone spends the week falling in love with a project that never happens. The bid is what decides which two survive. The honest pitch for each:

• Usability: the product works and isn't pleasant. Fixing that requires talking to users, which most engineers won't do.
• Accessibility: WCAG AA on student pages, tested against real assistive technology rather than a linter. The NVDA and VoiceOver lanes in tools/a11y-judge/ pass today but still need a resync ladder to walk a page cleanly — so the work is both fixing pages and making the oracle honest. Frame it as a testing problem, not a compliance checklist.
• Office hours: designed under assumptions that no longer hold. Real greenfield design inside a live system.
• Docusaurus: the least glamorous, the most reusable — this very site is the client.
• Paper exams: a Gradescope replacement. The biggest scope on the slate: document generation, image processing, handwriting OCR, grader UX. Say out loud that it's the most likely to under-deliver, and that real courses want it anyway.
• Forgejo: GitHub Classroom is deprecated, so this is the strategic one. Account provisioning, permissions automation, CI, and a path that doesn't break courses mid-semester.
• Coder: one-click cloud dev environments, aimed at intro courses where local setup is the barrier. If you found Thursday painful, this is you fixing it for CS 2000.

The two projects that are NOT here, and students who read the old planning notes will ask: gradebook performance and operations. Both are hazardous, both matter, and neither gets a team in a release semester. Saying that plainly is more credible than pretending the slate covers everything.

Students bid far more sensibly once they know how many projects can actually run, and saying so now is kinder than letting them discover it on Sep 24. It also changes what a bid is: with two teams, their second and third choices are load-bearing.

One upside of a small roster worth naming: you can build the teams around what people said they wanted this morning. Say that you'll do it — it makes the bids more honest.

Transition: Two dates, then one thing to do tonight.

What Happens Next

• Wed Sep 16 — Ticket hunt due. The pool you build is the pool we all draw from.
• Thu Sep 17 — Project bids due. Ranked preferences across the slate.
• Thu Sep 24 — Teams announced. Column groups due.
• Mon Sep 28 — Studio kickoff: charters, backlog, estimation.
• Thu Oct 1 — Declare your target band.

Between now and 9/17 you'll have run the app locally, filed a ticket or two from the hunt, and read code in at least two of those seven areas. Bid on the basis of that, not on the basis of this slide.

The framing matters: bids are informed by the week's work, not by the pitch. Students who hunt in an area they're curious about make much better bids.

Transition: So — Thursday.

Before Thursday

Come to Thursday ready to get Pawtograder running.

• Bring a laptop with Node 22 (use nvm) and Docker installed
• A fresh clone of pawtograder/platform if you get to it — main has moved since the application
• You don't have to have it working by then. Thursday is when we do that part together
• If you do get a head start, click through the app as a user and note one thing that's wrong
• Being stuck is a fine outcome, being stuck silently is not

Thursday is a working session, not a lecture. Whatever is already installed when you sit down is time you get back for code.

Do not turn this into an overnight assignment. Most of the room stood this stack up once already for the application, so the instinct is to ask them to do it again tonight. Resist it. The ask is that they turn up able to do it: a laptop, Node, Docker installed. The setup itself is what Thursday is for, and a student who spent last night fighting Docker alone is worse off than one who arrives fresh and does it with help in the room.

Say the reason out loud, because it changes what they hear. Installing Docker takes an hour of downloading and no thinking. Doing it in a room with staff and everyone else takes twenty minutes and teaches them who to ask. The only thing that can't happen in the room is the download.

The one thing worth doing beforehand, if they have time: a fresh clone. main has moved since they applied, the pinned Supabase CLI version matters, and stale Docker volumes are the most common way a setup that worked in August stops working in September. Frame it as a head start, not a requirement.

Say that you expect breakage and that Thursday exists to fix it collectively. Students who think they're supposed to succeed alone won't post in Discord.

The "note one thing that's wrong" bullet is optional on purpose. For anyone who does get there, it leads into the ticket hunt, due 9/16, and into a bid grounded in something they actually saw. Nobody is behind for skipping it.

TODO: Confirm the Discord invite is in the syllabus and on this slide before class.

Transition: Three things to take away.

Key Takeaways

1. The database is the application. The logic lives there, and it enforces security on the data.
2. We want sequential consistency, so nothing waits on anyone else. Commit what we own, queue what leaves the building, buffer what arrives — and when we're down, say so honestly.
3. Complexity is concentrated, and the debt is not a secret. Working well inside it is the skill this course grades.

Thursday: get it running, together. Then ship something.

Takeaways 1 and 2 are the thesis, deliberately repeated. If they remember nothing else from today, those two sentences let them predict most of the codebase — and let them ask a sharper question when something doesn't fit.

Close on the fragment. Don't add a fourth takeaway.

Transition: Tomorrow we all get our hands dirty.

Up Next

Thu Sep 10 — Working Session: Local Dev & the Contribution Workflow

Today was the map. Tomorrow you get the keys: the app running locally, and a first ticket claimed.

Before then:

• The Ticket Hunt — due Wed Sep 16
• Onboarding: Gradebook Column Groups — due Thu Sep 24
• Project Bids — due Thu Sep 17

Close on the transition, not the reminders — students should leave knowing what today was for.