Repository navigation
docs: presentation pass — README rewrite, working setup instructions, remove course scaffolding - #2
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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. Noneof them document the project.
goals.mdwas course scaffolding (Easy/Goal/Stretch/Impossible tiers, "beforethe 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.mdare gone as a sideeffect. 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.jarwas the documented way tostart the server. That jar has no
Main-Classand fails with "no mainmanifest attribute". The runnable one is
-boot.jar, as the Dockerfilealready knew. Pre-existing — the old
docker runexample had it too.defaults match the application's own, plus an init script creating
centroid_finder_testsomvn -P integration testworks 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
ProcessBuilderrather 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_TIMEOUTbecomes a real wall clock.Also notes the DFS is iterative over an
ArrayDequerather than recursive, andstates the test count (163 across 15 classes).
Verified by running it:
mvn clean package,docker compose up -d, bothdatabases created, server up,
GET /api/videos→ 200.