Project 12 — Design Before You Prompt

“And I saw the holy city, new Jerusalem, coming down out of heaven from God, prepared as a bride adorned for her husband.” — Revelation 21:2

Chapter: 12 — Architecture First Due: End of Week 12 Submit: A link to your code containing design.docx, source files for every class in your architecture, Tests.java (multi-class test suite), and prompts.txt. See Coding 1’s online-coding workflow appendix. Allowed tools: Java 17, JUnit 5, your AI assistant — but only for individual modules, not for architectural decisions. The new discipline: the design document is the first deliverable. It must exist before any code is generated. The grader can tell.

The Setup

This week you architect a small habit tracker — or the equivalent. You will produce a design document (design.docx) before writing a line of code. Then you will implement, prompting your AI for individual methods within the modules you designed.

You are not graded primarily on whether the code works. You are graded on whether the architecture is clean — single-responsibility classes, deliberate interfaces, sensible dependency direction, typed boundaries — and on whether your implementation honors the design you wrote down.

A grader looking at your submission should see: a design.docx that any reasonable engineer could read and implement from; a prompts.txt showing that the AI was asked for individual methods within your designed classes, not for the whole system; an implementation that matches the design; and tests that prove the system works as specified.

This is the highest-stakes Phase 2 project before the final. The skills it tests are the ones that come up in every real engineering interview and on every real engineering team.

Learning Targets

By completing this project, you will demonstrate that you can:

• Produce a clean architectural design document for a small system, before writing code.
• Decompose a problem into single-responsibility classes.
• Identify and define interface seams.
• Specify the data formats that cross module boundaries.
• Direct an AI to implement your architecture rather than letting it invent one.
• Test a multi-class system at both unit and integration levels.

Normal Tier

Goal: Architect, design, and implement a small habit tracker.

The brief

Build a command-line habit tracker. Functional requirements:

• Define named habits (e.g., “scripture,” “exercise,” “call parents”).
• Record a check-in for a habit on a date (default: today; optionally a specific date).
• List all habits with their current streak.
• Compute the streak for a habit (consecutive days ending at “today” on which a check-in exists).
• Persist state across runs (file format your choice — JSON, CSV, or plain text).
• A small CLI with at least these commands: add <habit>, check <habit>, check <habit> <date>, list, streak <habit>, quit.

You may extend the brief if you wish — add features, change the persistence format, change the CLI shape. Document any deviations in design.docx.

Required deliverables

1. design.docx — your design document. Written before any code. Required sections:

   • Brief restatement (3–5 sentences). What you understood the problem to be.
   • Responsibilities list. Every distinct thing the system must do, one bullet each.
   • Class table. For each class: name, one-sentence responsibility (no “and”!), the classes it depends on.
   • Class diagram. ASCII or image. Shows dependency arrows.
   • Public APIs. For every class, the public method signatures. Javadoc-style if useful.
   • Persistence format. The exact bytes that get written. (E.g., for JSON: a concrete example of the file’s contents after two habits with three check-ins each.)
   • Interface(s) and why. Any interface in the design, with a one-paragraph “why this is a seam” justification.
   • Open questions. Things you considered but punted. (Real designs have these. List yours.)

2. One Java file per class in the design. Example:

   • Habit.java
   • HabitTracker.java
   • HabitRepository.java (interface)
   • JsonHabitRepository.java (or whatever your persistence implementation is)
   • Cli.java
   • Main.java

   The exact set will depend on your design. Most submissions will have 4–7 files.

3. Tests.java (or XxxTest.java per class — your choice). At least 15 tests total across the project, including:

   • At least 3 tests for the core domain class (e.g., Habit).
   • At least 3 tests for the collection class (e.g., HabitTracker).
   • At least 2 tests for the persistence implementation (write then read, round-trip).
   • At least 2 tests for the CLI’s command parsing (use a StringReader for input, ByteArrayOutputStream for output).
   • At least 2 integration tests that exercise multiple classes together.
   • At least 3 tests for edge cases (empty habit, never-checked-in habit, two-day-streak-then-skip).

4. prompts.txt — chronological log of every prompt you sent. Especially important this project: the grader will check that your prompts were for individual methods or classes, not for “build me the system.” A prompts.txt that begins with “build me a habit tracker” loses major points.

Grading rubric — Normal (out of 100)

Note: 25 of the 100 points are for design.docx and another 15 are for evidence the design was actually followed during implementation. Design is most of the grade. Code that works but ignores its own design loses substantial points.

Medium Tier (+up to 25% extra credit)

M1. Two persistence implementations

Implement two HabitRepository implementations:

• JsonHabitRepository — writes a JSON file.
• InMemoryHabitRepository — keeps everything in memory; save and load operate on the in-memory state. Useful for tests.

(You may substitute any second backend — TextHabitRepository writing CSV, XmlHabitRepository, whatever. Two real implementations of the same interface, both functional.)

Show in design.docx how the rest of the system is unaffected by the swap. Show in Tests.java a test that demonstrates the same logic working against both implementations (parameterized test or two copies of the test, your choice).

This rep proves the interface is real — it’s actually doing the seam work you designed it for.

M2. Two-pass design log

In design.docx, include both the draft design (Pass 1) and the refined design (Pass 2) as separate sections. Write a paragraph explaining what changed between them and why.

The point is to show your design process, not to hide the early version. A grader reading your two passes can tell whether you actually refined or whether the “refinement” was theater. Be honest.

Hard Tier (+up to 25% additional extra credit)

H1. Classmate code review on your design

Hand design.docx (only — no code yet) to a classmate. Ask them to do a 20-minute code review of the design alone. Provide them with the architecture-checklist questions from §12.10 and §12.7.

Document the review in design-review.docx:

• The reviewer’s name and the date.
• Every comment they made.
• For each comment, your response: accept-and-change, accept-but-defer, reject-and-explain.
• A diff of design.docx if you made changes after the review.

This rep teaches the discipline of defending architecture. You will not always agree with the reviewer; that’s fine. The discipline is to engage — to articulate your reasoning when you reject a suggestion and to make real changes when the reviewer is right.

H2. Make a change the architecture makes easy

After implementing the full system, pick a small feature change that should be easy given your architecture:

• “Add a prune command that removes habits with no check-ins in the last 30 days.”
• “Add a new persistence backend (a CSV one, since you already have JSON).”
• “Add a --quiet flag to the CLI that suppresses non-error output.”

Implement it. Document in design-change.docx how many files you had to touch, and explain why your architecture made it that easy (or, honestly, why it was harder than you expected).

This rep proves to you that good architecture pays off in maintenance time, not just in feeling good about the diagram.

Submission

Submit one URL via the course portal.

Project structure:

project-12/
├── design.docx                    (required, written FIRST)
├── design-review.docx             (Hard H1 only)
├── design-change.docx             (Hard H2 only)
├── prompts.txt                   (every prompt, timestamped)
├── src/
│   ├── Habit.java
│   ├── HabitTracker.java
│   ├── HabitRepository.java
│   ├── JsonHabitRepository.java
│   ├── InMemoryHabitRepository.java  (Medium M1)
│   ├── Cli.java
│   └── Main.java
└── test/
    └── (test files, one per class or one master Tests.java)

Reflection block at top of design.docx

<!--
Project 12 — Design Before You Prompt

Tier targeted:    Normal / Medium / Hard
Class count:      N
Interface count:  M
AI assistant:     [name, version]

Honest accounting:
  - I wrote this design.docx before sending any prompts to the AI.
    (The timestamp on the first commit / file creation should support this claim.)
  - I prompted the AI per-method or per-class, never for "the whole system."
  - I made [N] design changes during implementation. They are documented in
    [where — design.docx, design-review.docx, or design-change.docx].

What I'd change about the design after living with it:
  [one paragraph]
-->

What the grader will do

1. Open design.docx and read end to end. Form opinion on architecture before reading any code.
2. Open prompts.txt and check: do the first prompts ask for individual methods/classes, or do they ask for “the system”?
3. Open each Java file. Verify it matches the design.
4. Run the tests. Verify they pass.
5. Run the CLI. Try a few commands. Verify behavior matches the spec in design.docx.
6. (Medium) Confirm both persistence implementations work.
7. (Hard) Read design-review.docx and/or design-change.docx.
8. Score against the rubric.

A great submission is one where the grader can finish reading design.docx and predict, with high accuracy, what each Java file will contain. That is what “implementation matches design” looks like.

Hints (Read These If You’re Stuck)

• “How long should design.docx be?” Aim for 2–4 pages. Less than 1 page and you skimped on a section. More than 5 and you’re over-designing for a small project.

• “How many classes is the right number?” For a small habit tracker, 5–8 is typical (Habit, HabitTracker, HabitRepository, one or two implementations, Cli, Main). Fewer than 4 and you probably under-decomposed. More than 10 and you’re probably over-decomposing.

• “Should Habit be a record or a class?” Either works. A record is concise and immutable; a class supports mutable check-ins (with the check-in set being a private field). The chapter showed it as a class with checkIn(date) — that’s fine. If you make it a record, the check-in operation lives on HabitTracker instead. Both are valid; pick one and stick with it.

• “The AI keeps suggesting things outside my design.” Tighten your prompts. Use the negative-constraint patterns from Chapter 10: “Implement only this method. Do not add helper classes. Do not add fields. Do not change other methods in the class.”

• “My architecture changed during implementation.” That’s normal. Architecture rarely survives first contact with implementation 100% intact. The discipline is to update design.docx when it changes, not to leave it pretending the design didn’t shift. The grader can compare your final design to your final code — make them match.

• “How long should this project take?” Normal: 6–10 hours. The design eats 1–2; the implementation and tests eat the rest. Medium: +2–4 hours for the second persistence. Hard: +3–5 hours for the review/change exercises.

What Mastery Looks Like (Beyond the Rubric)

The rubric tells you what to do. Here’s what to aim for:

A great Project 12’s design.docx is a document a different student could implement from. That is the test of design: a stranger reading it can produce code with the same architecture as yours.

A great Project 12’s prompts.txt shows the senior/junior workflow at its best: every prompt is for one focused method or class. The AI is doing implementation, not architecture. The grader reading the log can see the directing, not just the typing.

A great Project 12’s interface (the HabitRepository) is actually swappable. Even if you only ship one implementation, the rest of the system should work with mockit or a hand-written fake. If swapping the implementation requires changing other classes, the interface isn’t doing its job.

A great Project 12’s tests don’t only test methods — they test the boundaries. A test that constructs a Cli with an in-memory repository and runs a sequence of commands, then asserts the in-memory state, is testing the architecture working as a system. Those are the most valuable tests.

A great Project 12 produces code you would be willing to maintain for a year. That is the standard. Not “code that works for the demo.” Code that the next engineer (probably future-you) does not curse.

When You’re Done

1. Re-read design.docx. Could a fellow student implement from it?
2. Re-read prompts.txt. Is every prompt scoped to a method or class? Or did you slip into “the whole thing”?
3. Run the CLI for ten minutes. Try every command. Try weird inputs. Does it hold up?
4. Run all the tests. All pass?
5. Submit.
6. Read Chapter 13. Now we turn to what to do when the AI’s answer is wrong.

Coach’s Note — This is the project that proves whether you’ve internalized the senior/junior model. Students who do Project 12 honestly find that their entire workflow has changed by the end of it — design first, prompt second, review third, test fourth, ship fifth. That five-step rhythm is the working senior’s day, every day, for years. Get it into your hands here. The capstone will assume you have it.

Build well. See you Monday.