Skip to content

docs: presentation pass — README rewrite, working setup instructions, remove course scaffolding - #2

Merged
konradkelly merged 2 commits into
mainfrom
docs/presentation-pass
Aug 13, 2026
Merged

konradkelly merged 2 commits into
mainfrom
docs/presentation-pass

Conversation

@konradkelly

Copy link
Copy Markdown
Owner

Two commits.

1. Remove working notes and course-assignment framing

docs/ held eleven scratch files alongside the real documentation — ideas.md,
notes.md, plan.md, polish.md, options.md, goals.md, serverPlan.md,
priorityImprovements.md, humanImprovements.md, robotImprovements.md. None
of them document the project.

goals.md was course scaffolding (Easy/Goal/Stretch/Impossible tiers, "before
the quarter ends"). Nine places across the two deployment guides linked to it and
inherited that framing, including a line addressed to "if your course requires a
literal EC2 ASG"
. Those now describe the engineering on its own terms — the
Fargate-vs-ASG reasoning was worth keeping, the tier mapping was not.

Two pre-existing broken links to ../deploymentPlan.md are gone as a side
effect. Every remaining internal doc link resolves.

2. README rewrite, and fixing instructions that did not work

The README opened by describing itself as coursework, spent three quarters of its
length on setup, and gave the async job pipeline one line.

Two documented commands were broken:

  • java -jar target/centroid-finder-1.0-SNAPSHOT.jar was the documented way to
    start the server. That jar has no Main-Class and fails with "no main
    manifest attribute"
    . The runnable one is -boot.jar, as the Dockerfile
    already knew. Pre-existing — the old docker run example had it too.
  • Setup built a container network by hand. Replaced with a compose file whose
    defaults match the application's own, plus an init script creating
    centroid_finder_test so mvn -P integration test works locally.

Content: leads with what it does and the threshold GIF, then the algorithm,
then architecture. Documents why video jobs get their own JVM via ProcessBuilder
rather than just their own thread — FFmpeg decodes in native code through JNI,
where a malformed file can take down the whole process, so a crashed subprocess
costs one job instead of the API, and JOB_TIMEOUT becomes a real wall clock.
Also notes the DFS is iterative over an ArrayDeque rather than recursive, and
states the test count (163 across 15 classes).

Verified by running it: mvn clean package, docker compose up -d, both
databases created, server up, GET /api/videos → 200.

docs/ held eleven scratch files alongside the real documentation —
ideas.md, notes.md, plan.md, polish.md, options.md, goals.md, serverPlan.md,
priorityImprovements.md, humanImprovements.md, robotImprovements.md — none of
which document the project. They read as an open working directory rather than
something finished.

goals.md in particular was course scaffolding: Easy/Goal/Stretch/Impossible
tiers and "before the quarter ends". Seven places in aws-deployment-spec.md and
two in backend-deployment.md linked to it and inherited that framing, including
a line addressed to "if your course requires a literal EC2 ASG". Those now
describe the engineering decision on its own terms — the Fargate-vs-ASG
reasoning was worth keeping, the tier mapping was not.

Also drops IMPROVEMENT_SPEC.md, which catalogued this repo's own weaknesses
for my benefit and is not something a visitor should be reading.

Removed docs are preserved outside the repo, not lost. Two pre-existing broken
links to ../deploymentPlan.md are gone as a side effect; every remaining
internal doc link now resolves.

docs/ now holds only real documentation: the AWS deployment spec, the backend
and frontend deployment guides, the video-frame-reader design note, both
architecture diagrams, and the two demo images.
The README opened by describing itself as coursework, spent three quarters of
its length on local setup, and gave the async job pipeline — the most
interesting thing in the project — a single line.

Restructured to lead with what it does and the threshold GIF, then how the
algorithm works, then architecture, then setup. Documents the parts worth
defending: video jobs run in their own JVM via ProcessBuilder rather than just
their own thread, because FFmpeg decoding happens in native code through JNI
where a malformed file can take down the whole process — a crashed subprocess
costs one job instead of the API, and it makes JOB_TIMEOUT a real wall clock.
Also notes the DFS is iterative over an explicit ArrayDeque, not recursive,
and states the test count (163 across 15 classes).

Two documented commands did not work:

- `java -jar target/centroid-finder-1.0-SNAPSHOT.jar` was the documented way
  to start the server. That jar has no Main-Class and fails with "no main
  manifest attribute" — the runnable one is `-boot.jar`, as the Dockerfile
  already knew. Pre-existing; the old `docker run` example had it too. The
  README now names all three jars and what each is for.
- The setup steps built a container network by hand. Replaced with a compose
  file whose defaults match the application's own, so `docker compose up -d`
  then `java -jar …-boot.jar` works with no further configuration. Its init
  script also creates centroid_finder_test, so `mvn -P integration test` runs
  locally without extra setup.

No container_name in the compose file on purpose: a fixed name collides with
whatever the old manual instructions left behind and stops two checkouts
running side by side.

Verified by running it: mvn clean package, docker compose up, both databases
created, server up, GET /api/videos -> 200.
@konradkelly
konradkelly merged commit d109cb3 into main Aug 13, 2026
2 checks passed
@konradkelly
konradkelly deleted the docs/presentation-pass branch August 13, 2026 07:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant