Chapter 15 · Reps

Architecting the Whole System — Reps

← Back to Chapter 15

Chapter 15 — Reps

Conditioning, not grading. Architecture and decision drills this week — not much new code. The muscle you are building is the one Project 14 grades most of all: given real constraints, choose a stack and defend it.

Ground rules:

  1. Write the answers down. On paper or in a file. An architecture decision you keep in your head is one you can’t defend. The page is honest; your head is not.
  2. Every choice gets a because, and every because points at a constraint. “Postgres because it’s good” is not an answer. “Postgres because the write burst exceeds SQLite’s single-writer limit” is.
  3. Time yourself where a rep says to. The final is a timed build. Practice under the clock.
  4. AI/agents are ON (Phase 2) — but these reps are yours to reason through. Use the agent to check your reasoning after you’ve committed to an answer, never to make the call for you. The whole point of this chapter is the call the agent can’t make. Practice making it.

Use the templates in code/: the constraints worksheet, the architecture-doc template, and the worked sample. Lean on them.

Reps 1–3: Naming Constraints and Choosing a Server

Rep 1 — The Seven Questions, Cold

Here is a scenario. Answer the seven constraint questions from §15.1 in writing — no stack yet, just the constraints.

A seminary wants a tool where ~300 students can submit weekly Greek-translation exercises and ~12 professors can read and grade them. Submissions are due Friday at midnight, so there’s a spike of a few hundred submissions in the last hour. Grading happens over the following week, steadily. The IT staff is one person who knows Python. They need it for the term starting in a month.

Answer, in order: (1) users/scale, (2) read/write shape, (3) what must be consistent, (4) budget (dollars and complexity), (5) team, (6) timeline, (7) what changes next. One or two sentences each. Do not name a single technology yet — that’s Rep 2.

Rep 2 — Let the Stack Fall Out

Using your own answers from Rep 1, now choose: a server (Node or FastAPI), a database (SQLite/Postgres/Mongo), and a front-end approach. Write one sentence per choice, each tracing to a specific constraint you named in Rep 1.

Then write the architecture in one paragraph (the §15.3 Step 3 move). If you can’t trace a choice to a constraint, you guessed — go back and find the constraint or change the choice.

Rep 3 — Node vs FastAPI, Three Ways

For each scenario, choose Node or FastAPI and name the one deciding constraint. (There’s a defensible answer for each; the justification matters more than the pick.)

  1. A team of three who have only ever written JavaScript, building a chat-style app with thousands of mostly-idle open connections.
  2. An API whose whole job is to validate complex, deeply-structured submission payloads and reject malformed ones with precise error messages.
  3. An API that must call into an existing Python machine-learning model to score each request.

For each, write: choice + the one constraint that decided it. (Hint: §15.2 Decision 2’s table. Reread the “GIL / single thread chokes on CPU-bound” row — does it apply to any of these?)

Reps 4–6: Choosing the Database

Rep 4 — The Deciding Constraint

For a database choice, the deciding constraint is almost always one of two things. Name them. (Answer in §15.2 Decision 3 — write it from memory, then check.) Then explain in two sentences why “Postgres is more powerful than SQLite” is not a reason to choose Postgres.

Rep 5 — The SQLite Line

State, in one sentence, the exact constraint that pushes a system off SQLite and onto Postgres. (This is Week 11’s Hard-tier lesson.) Then give one scenario where a system has tens of thousands of users but SQLite is still the right call, and say why. (Hint: it’s about the write shape, not the user count.)

Rep 6 — SQLite vs Postgres vs Mongo, Three Ways

For each scenario, choose a database and name the deciding constraint:

  1. A church sign-up tool: 40 groups with hard capacity caps, a burst of a few dozen sign-ups in a few minutes twice a year, near-zero ops budget, relational data.
  2. A public devotional archive: tens of thousands of daily readers, one write per day by staff, each devotional has wildly varying optional fields (audio, questions, image, or none).
  3. A denomination-wide event registration: 120,000 members, thousands grabbing limited seats in the same second, money changing hands, strict no-double-booking.

Write choice + deciding constraint for each. Then notice: these three yield three different answers. That’s the point — the method, not the answer, is the lesson.

Reps 7–8: MVP Scoping and Cost-Counting

Rep 7 — Viable, Lovable, Gold-Plated

Take the seminary translation tool from Rep 1. Write three short feature lists:

  • Minimum Viable: the smallest set that delivers real value (beats the status quo).
  • Minimum Lovable: MVP plus the small polish that makes people want to use it.
  • Gold-Plated: everything anyone might imagine.

Then draw the line: which list would you actually ship for the term starting in a month, and why? (Constraint #6 — timeline — should drive this.)

Rep 8 — Count the Cost of a Feature

Pick one feature from your “Gold-Plated” list in Rep 7 — say, “email reminders the night before the deadline.” Count its cost with the three questions from §15.5:

  1. What does it cost to build?
  2. What does it cost to maintain?
  3. What does it cost to leave out (the real user pain of not having it)?

Then make the call: in or out for the MVP? Defend it in one sentence. Connect it back to Luke 14:28 — the builder who counts the cost before starting.

Reps 9–10: The Agent Boundary and the Constraint Flip

Rep 9 — Flip a Constraint

Take the church sign-up tool from Rep 6.1 (FastAPI + SQLite + plain JS, as worked in §15.3). For each flip below, state which architecture choices change and which stay the same:

  1. The user count jumps from 1,200 to 120,000 with simultaneous sign-ups.
  2. The team is replaced by one volunteer who only knows JavaScript.
  3. Each group now has wildly varying custom fields (some need childcare info, some a skills survey, some nothing).

For each flip, write: what changes, what stays, and why. This is the §15.3 Step 4 move — and it’s the part of the architecture doc that proves you understand the method.

Rep 10 — Sort the Work: Agent vs Human

Here are ten tasks from a capstone build. Sort each into AGENT can own it or HUMAN must decide it, using the §15.6 table. Then, in one sentence each for the HUMAN tasks, say why the agent can’t own it.

  1. Scaffold the FastAPI project structure.
  2. Decide whether this app needs Postgres or SQLite.
  3. Generate the CRUD endpoints from a schema you wrote.
  4. Decide what the three database tables are and how they relate.
  5. Write the migration script from your data model.
  6. Decide whether the capacity check needs to be inside a transaction.
  7. Draft tests for the sign-up endpoint’s described behavior.
  8. Decide whether to ship a waitlist feature for the MVP.
  9. Refactor a module without changing behavior.
  10. Decide whether this whole tool is the right thing to build at all.

(Check: the AGENT pile should be all execution of a defined task; the HUMAN pile should be all judgment under constraint. If you put a “decide” task in the AGENT pile, reread §15.6.)

Rep 11 — Read the Agent’s Silent Mistake

The trap of agentic AI isn’t that it refuses judgment calls — it’s that it makes them silently and confidently. Here is a sign-up endpoint an agent produced for the §15.3 tool (Python/FastAPI/SQLite, pseudocode-ish):

@app.post("/litman-books/groups/{group_id}/signup")
def signup(group_id: int, member_id: int):
    cur = db.execute(
        "SELECT count(*) FROM signups WHERE group_id = ?", (group_id,)
    )
    count = cur.fetchone()[0]
    cap = db.execute(
        "SELECT cap FROM groups WHERE id = ?", (group_id,)
    ).fetchone()[0]
    if count >= cap:
        raise HTTPException(409, "Group is full")
    db.execute(
        "INSERT INTO signups (group_id, member_id) VALUES (?, ?)",
        (group_id, member_id),
    )
    db.commit()
    return {"status": "ok"}

It uses parameterized SQL (good — no injection). It returns sensible status codes. It looks fine. It contains the exact bug the tool exists to prevent. Find it. Write down: (1) what the bug is, (2) the realistic scenario that triggers it, (3) the fix. (Hint: §15.6’s third Common Bug. Think about two requests arriving at the same instant for the last seat. Where does the check happen relative to the insert?)

This is the human’s job — the agent wrote fluent, plausible, subtly-wrong code, and only the architect who owns the consistency judgment catches it.

Done? One Last Thing.

From scratch, no looking, in 20 minutes, write a full one-page architecture document for this brand-new problem:

A small Christian school (~250 families) wants a tool where parents can sign up for parent-teacher conference slots. Each teacher publishes a set of 15-minute slots on a given evening; each slot holds one family; once a slot is taken it’s gone. Parents browse their child’s teachers and grab open slots. The school office (two staff, one knows a little Python) runs it. Conferences are in three weeks.

Your doc must contain, per §15.8:

  1. The problem in one paragraph.
  2. The seven constraints, answered.
  3. The stack (server + database + front end), each choice traced to a constraint.
  4. At least two constraint-flips that would change a choice.
  5. The MVP scope line — what’s in the lovable build, what you’re cutting.

Use code/architecture-doc-template.txt for the shape and code/sample-architecture-doc.txt as your worked reference. Watch the clock.

If you can do this cold — constraints → stack → defense → flips → scope, in twenty minutes — you are ready for the capstone’s architecture document. That document is what the final grades most of all.

(Notice the consistency constraint hiding in this problem: one slot, one family, gone once taken. That’s the last-seat race again. Where in your stack do you enforce it? That sentence is the difference between an A and a tool that double-books a teacher’s evening.)

Up next: Write a full architecture doc for the capstone scope you’ll pick, using the code/ templates — first, before any code. Then read Chapter 16 and Project 14 — the capstone. The architecture doc you write this week is the deliverable the final grades most of all. Do it well.