Skip to content

1. Hello, Project Pulse

Due Friday, September 4, at the beginning of class. Individual work. 4% of your grade.

This is your first day on a codebase you did not write, which is what your first day at a job looks like. Nobody will explain the system to you. You will have an agent that answers every question instantly and is sometimes wrong, and you will be expected to produce something small, correct, and defensible by the end of the week.

You are not being asked to fix anything important. You are being asked to prove you can read unfamiliar code, catch your agent being confident and wrong about it, and file the kind of issue an engineer would act on.

Your assignment repository

You do not work in the public Project Pulse repository. Fork this one instead:

https://github.com/tcu-cosc-40943/hello-project-pulse

Same code, class copy. Press Fork, keep the defaults, and it lands in your own account. Your issue, your branch, and your pull request all live in your fork.

Then change two settings. GitHub's defaults are wrong for this assignment, and they go wrong differently. The first stops you: a new fork has no Issues tab, so there is nowhere to file. The second does not stop you: your pull request opens against the class repository rather than your own, and nothing tells you it went to the wrong place.

1. Turn Issues on in your fork

A new fork has its Issues tab disabled. This assignment requires you to open an issue, so switch it on: Settings → General → Features → Issues.

Do not file it on the class repository instead. Issues are enabled there, so it will work, and it is the obvious move when your own fork has no tab. Your issue counts only in your fork.

2. Point your pull request at your own fork

When you open a pull request, GitHub sets the base repository to tcu-cosc-40943/hello-project-pulse, not yours. Change the base repository dropdown to your own fork and the base branch to main. Miss it and you have opened your pull request against the class repository, in front of everyone, and it is not your submission.

Already forked?

Press Sync fork at the top of your fork's file list before you start, so you have the current code and the pull request template. It is one click while you have no commits of your own.

What you submit

One pull request in your own fork, linked to one issue you opened there. Submit the pull request's URL to TCU Online by the beginning of class on the due date. That link is your submission; the issue, the diff, and the pull request description are what get graded. Nothing else is uploaded.

Part 0: Clone your fork and get it running

This is your first time with Project Pulse, and it is a real application: a Vue frontend, a Spring Boot backend, MySQL and Mailpit in Docker. Budget an evening, and start this week rather than the night before.

Fork first, then clone your fork. There is no reason to clone the public Project Pulse repository at all; your fork is the same code, and it is where every commit you make has to end up.

  1. Fork the repository and turn Issues on, per the two settings above.
  2. Install the toolchain, step 1 of the setup instructions. The README assumes it and does not name versions; a JDK other than 21 is the usual reason a first build fails.
  3. Clone your fork, then follow the README in your fork. It carries the whole procedure: Docker, the backend, the frontend, the ports, and the test logins. Read it there rather than anywhere else, since it is the copy that matches your code.
  4. Log in as the test student the README names.
  5. Point your agent at the clone and confirm it can read the code, step 3.

Getting it to start is the goal. Understanding it is Part 1.

Stuck? Post in the Slack help channel

Setup problems are the one thing here you should not work through alone, and they are almost never unique to you. Post the exact command you ran and the exact error text, not a description of it. Do this the day you get stuck, not on Thursday night.

If you are still blocked, keep going. Parts 1 through 3 need the source, not a running application: you can read the code, catch the agent, file the issue, and make the change from the clone alone. Say in your pull request that it would not start and what you tried. A setup failure should cost you the reproduction steps in your issue, not the assignment.

Part 0 carries no points of its own.

Part 1: Read one package with the agent

Pick one backend package under backend/src/main/java/team/projectpulse/ or one frontend feature under frontend/src/. Reasonable choices:

Area Where to look
Performance tracking activity (weekly activity reports), evaluation (peer evaluations), rubric
Org and enrollment model course, section, team, student, instructor
Shared platform system (the Result envelope, StatusCode, ExceptionHandlerAdvice), security, user
Requirements module anything under ram/, for example document, requirement, usecase, glossary, collaboration
Frontend under frontend/src/: apis/<feature> (the per-feature API clients), pages, components, stores, router

Ask the agent to explain that package: what it is responsible for, how a request flows through it, what it depends on. Then read the code and check the explanation against it.

You are looking for one specific thing: a claim the agent made that the code does not support. It might be wrong, or too confident about something it could not have known, or true of the framework in general but not true of this code. It will not be flagged as uncertain. That is the point of the exercise.

Write down the claim, and write down the file and line that settles it. Both go in your pull request. If the first package you pick gives you nothing, say so and describe what you checked. A documented "I could not catch it here" beats a fabricated catch, and it is the only version of that answer that scores.

Part 2: Open a well-formed issue

Checking the agent is also how you find something worth filing, because it forces you to read closely enough to notice where the code is not what it should be.

What to look for. Project Pulse states its conventions, and the most useful finding is a place that departs from one:

  • The Result envelope: every API response is wrapped, and the frontend's shared Axios instance unwraps it. A response or a caller that does not follow this is a real finding.
  • Converter<S, T> DTO conversion, written explicitly. There is no Lombok and no MapStruct in this codebase, on purpose.
  • /api/v1 routing, uniform across controllers. Each controller declares it as the placeholder ${api.endpoint.base-url}, resolved from application.yml, so searching the Java for a literal /api/v1 returns nothing.
  • Per-feature API clients under frontend/src/apis/<feature>/, going through the shared Axios instance rather than calling the network directly.

Failing that: code whose name or comment disagrees with what it does, logic duplicated across two services that should share it, a literal that should be a named constant, or an error path that swallows the information a caller needs.

What not to file. Formatting and whitespace. Anything you found by asking the agent for "code smells" and did not verify yourself. Sweeping rewrites. Anything you cannot point at a line for.

Security findings do not go in a public issue

If you find something with security or privacy consequences, do not open an issue about it. Email b.wei@tcu.edu instead. Publishing a vulnerability where anyone can read it, before the owner can fix it, is how you get fired in your first month. A disclosure by email is graded the same as an issue.

The shape of a good issue. This is the shape, not a real finding, so do not file this one:

Title: ActivityController returns a raw list instead of the Result envelope

Body: ActivityController.getActivitiesByTeam returns List<ActivityDto> directly, while every other endpoint in the package returns Result. The frontend's shared Axios instance unwraps Result, so the client for this one call has to special-case the response shape.

To see it: log in as a student, open the team activity view, and compare the network response for this call against any other /api/v1 call.

Suggested fix: wrap the return in Result with the matching StatusCode, and drop the special case in the frontend client.

Note what that does. It names the file and the method. It says what the code does and what the convention says. It gives a reason to care that is not "this is bad style." It tells the reader how to see it themselves. It proposes a fix without demanding one. Compare it to "the activity module has poor error handling and several code smells," which nobody can act on.

Part 3: Make the change and open the pull request

Branch off main in your fork, make the fix, and open a pull request that closes your issue. Check the base repository dropdown before you press Create, per the warning above.

Keep it small. One file is normal. If your diff runs past about fifty lines, you picked the wrong finding. Small is not a consolation prize here: choosing a change you can fully defend is the skill being assessed.

Your pull request description carries three things.

  1. What you changed and why it is right. Argue for the change. Do not narrate the diff, which the reviewer can already read.
  2. What you deliberately did not change. You will have noticed other things. Naming them and leaving them alone is a professional move, not an admission.
  3. What the agent got wrong, from Part 1: the claim, and the file and line that disproves it.

The pull request template in your fork gives you these as headings, plus a check on the base repository. Then say what you delegated and what you kept, in a sentence or two. "The agent drafted the fix and I rewrote the null handling because it silently returned an empty list" costs you nothing and is worth writing.

How it is graded

Points
The issue. Does it name a real problem precisely enough to act on without asking you a question? 35
The change and the argument for it. Is the fix correct, appropriately small, and defended rather than described? 35
Catching the agent. Did you verify an explanation against the code, and can you show the line that settles it? 20
Mechanics. Branch, linked issue, clean commits, readable writing. 10

Not the bar: it ran

An agent can produce a passing version of every part of this in ten minutes. That is the floor. The grade is for the finding you chose, the changes you decided against, the claim you caught, and whether you can explain the diff to someone who did not write it. Expect to be asked in class.

Leave the pull request open. Do not merge your own. Your fork is yours, so nothing stops you, but merging is not the assignment; it is reviewed and graded as submitted, the way it would be at work.

Your fork is public, and so is everyone else's. Read your classmates' work if you want, after you have filed your own; what you cannot do is submit a finding you did not make. That is the explanation test, and it is asked in class.

If your fix is genuinely good, you may be invited to open it against the real Project Pulse as an actual contribution. That is not part of the grade, and it is not something you should ask for. It is something a small number of these earn.

Late work takes a 15% penalty per day and is not accepted more than two days late. See the syllabus.