Semester Project

Required Output Classification

Required output	Classification	Public/private guidance
Runnable project implementation and repository structure	Portfolio candidate	Polish the public repo only after tests pass, secrets are removed, and setup steps work from a clean checkout.
README with setup, inspection, verification instructions, and known limitations	Portfolio candidate	Make this public-facing if the project is safe to share; keep internal coursework notes in a private evidence folder.
Tests, traces, proofs, diagrams, benchmark outputs, or review notes required by the brief	Checkpoint evidence	Keep raw logs, benchmark runs, and reviewer comments private by default; publish summarized or reproducible versions when useful.
ADRs, design memos, runbooks, benchmark reports, and other high-effort engineering writeups	Portfolio candidate	These are worth polishing publicly when they tell a clear tradeoff story; otherwise keep them as private coursework evidence.
Final reflection, retrospective, or carry-forward notes	Checkpoint evidence	Keep candid self-assessment private unless rewritten as a concise public learning note.

Build one small but serious systems artifact that forces you to combine operating-system reasoning with network programming. The goal is not feature count. The goal is evidence that you can trace real behavior across CPU, memory, synchronization, storage, and sockets.

---

Project Brief

Build a concurrent networked service with durable request logging.

The service can be an echo server, tiny key-value server, task queue, chat relay, or similar narrow-scope protocol. Whatever you choose, the project must make you exercise the core ideas from all five modules.

---

Required Capabilities

Your project must include all of the following:

1. Real concurrency

   • Use threads, a thread pool, or an event loop.
   • Explain why you chose that model over the obvious alternatives.

2. Shared-state discipline

   • Protect mutable shared state correctly.
   • Document one race or deadlock risk you considered and how you prevented it.

3. Durable or intentionally non-durable logging

   • Write request or event logs to disk.
   • State exactly what durability guarantee you provide and what would be lost on a crash.

4. Network protocol

   • Use TCP or UDP deliberately.
   • Define the request and response format clearly enough that another person could implement a client.

5. Measurement

   • Record at least one CPU, memory, I/O, and network observation using real tools.
   • Use the observations to explain one bottleneck or tradeoff.

---

Recommended Scope

Keep the feature set small. A good project is:

• one binary or a very small service pair
• a simple text or line-based protocol
• no authentication or database requirement unless you already have those pieces
• runnable on one Linux machine with a short README and test commands

Bad scope is a "production-ready platform" plan that hides the operating-system learning under framework code.

---

Suggested Milestones

Milestone	Deliverable	What To Prove
1	Protocol and architecture note	Why TCP or UDP, why this concurrency model, where shared state lives
2	First working server	Accepts clients, handles requests, returns responses
3	Concurrency hardening	Shared state protected, tests or stress checks added, obvious races removed
4	Logging and crash semantics	Request logging works, durability statement written, failure behavior tested
5	Measurement pass	perf, strace, ss, tcpdump, /proc, or similar evidence captured
6	Final package	README, run steps, tradeoff note, and postmortem on what broke first

---

Required Evidence

Submit or keep with the project:

• source code
• a short README with build and run instructions
• one architecture note, 1-2 pages
• one packet capture or socket-state snapshot
• one measurement note covering at least one of CPU, page faults, lock contention, or I/O behavior
• one failure note describing a bug you hit and how you proved the fix

---

Rubric

Criterion	Standard
OS reasoning	You can explain scheduler, memory, synchronization, and I/O implications of your design
Networking correctness	The service protocol works and you can explain connection behavior clearly
Concurrency safety	Shared-state access is deliberate and defended with code plus reasoning
Durability clarity	Logging behavior and crash guarantees are explicit, not implied
Measurement quality	Claims are backed by traces, counters, or captures rather than intuition alone
Scope control	The project stays small enough that systems reasoning remains visible

---

Stretch Options

Do these only if the core project is already solid:

• add an epoll version if you first built a threaded one, or vice versa
• compare latency under two concurrency models
• compare fsync on every request vs batched flushes
• add a bounded in-memory queue and measure overload behavior

---

Submission Checklist

• The service runs locally from a clean terminal
• The request/response protocol is documented
• Concurrency choices are explained
• Shared-state protections are visible in code
• Logging behavior and crash guarantees are documented
• At least one packet or socket trace is included
• At least one system measurement note is included
• The final write-up states the main bottleneck and one future improvement

---

Production-Style Project Brief

Use this project as a reviewable engineering brief, not only a completion exercise.

Problem statement

Write a one-paragraph statement covering the user, the problem, the constraint, and the outcome this project is meant to produce.

Required evidence

• working artifact or reproducible deliverable
• README with setup, inspection, and verification instructions
• tests, traces, proofs, diagrams, benchmark output, or review notes appropriate to the semester
• decision log with at least three meaningful tradeoffs
• known limitations section with explicit scope cuts

Review questions

1. What is the smallest vertical slice that proves the project works?
2. Which requirement is most likely to be misunderstood by a reviewer?
3. What did you deliberately not build, and why?
4. What evidence would convince someone else that the result is correct?

Done means

The project is done only when another technical reader can inspect the artifact, run or review the verification evidence, and understand the tradeoffs without a live explanation.

---

Weekly Project Milestones

Use these milestones to keep the project from becoming a last-week scramble.

Milestone	Focus	Evidence
Start	Scope the smallest useful slice	problem statement, non-goals, first task list
Early build	Produce a walking version	runnable skeleton, first test, first committed artifact
Middle	Add the hard part	implementation note, trace/proof/benchmark/design decision
Review	Stress the weak point	failure case, debugging note, peer/self review, correction commit
Finish	Package for inspection	README, verification instructions, known limitations, reflection

Answer-Quality Examples

Quality	What it sounds like
Weak	"I built it because the module asked for it."
Acceptable	"It works for the required examples and I can explain the main idea."
Strong	"Here is the tradeoff I chose, the evidence that supports it, and the case where it would fail."
Portfolio-ready	"A reviewer can inspect the artifact, rerun the checks, and understand why this solution fits this semester's goals."

Future Capstone Connection

Before closing this project, write two sentences on how it could help the final capstone: one reusable technical skill and one artifact habit to preserve.

Calibration Materials

Use these learner-visible calibration materials before self-grading or requesting review:

• Answer key and solution outlines
• Rubric, passing standard, strong traits, and weak patterns