Project 4B: Wordnet (Design)
Lectures needed for this project:
- Lecture 17 (Extends, Sets, Maps, and BSTs)
- Lectures 21, 22 (Graph Traversals and Implementations)
Partner policy: No partners. Discussing ideas with other students is allowed, but code sharing is not allowed, and the solutions you submit should be your own work! More details on the policies page.
LLM policy: LLMs should not write any part of your design document, including your diagram. You may only ask browser-based chatbots high-level, conceptual questions, and you must never paste the spec or skeleton code into an LLM. See more info in the LLM policies page for more details.
In this project, you’ll design your approach to Wordnet, the rest of the NGordnet tool.
Task 0: Wordnet Spec
Before getting started, please read the Project 4C: Wordnet (k == 0) and Project 4D: Wordnet (k != 0) specs. You won’t be able to begin the next tasks without understanding the Wordnet spec first!
Task 1: Checkpoint
Project 4B: Wordnet Checkpoint is a conceptual assignment testing your understanding of Wordnet. We recommend completing this before designing your project.
Complete the Project 4B: Wordnet Checkpoint. You have unlimited submissions until the deadline and explanations will be shown upon entering the correct answers. You may not extend the checkpoint$^*$, as this is intended to help you get started on the rest of the project.
$^*$Students with DSP accommodations may extend the checkpoint
CS 47B students: Even if you are pairing with a partner for Project 4, you must complete the checkpoint individually.
Task 2: Technical Design Doc
Project 4B: Wordnet Design is a design assignment for you to plan your approach for Wordnet before implementing it.
For your design document, you must include each of these components from the rubric below. The sections follow the structure of design documents used in industry: an overview, the data and components involved, how a request flows through those components, and the cost of each operation. For general background on design documents, see the Design Doc Guide. For this project, follow the sections in the template.
The Lab 8 slides provide some info about the tasks in 4C and 4D, along with guiding questions that may be useful as you create your design doc.
- Overview (10%): Summarizes what you’re building, including its goals and non-goals.
- Data (15%): Describes each input file, what you extract from it, and which class parses it.
- Components (25%): Describes each class you will write: its responsibility, the data structures it stores, and the methods other classes call.
- Request Flows (35%): A sequence diagram tracing a query through your classes, plus the algorithm for each case (single word with k == 0, multiple words with k == 0, and k != 0).
- Complexity (15%): Describes the expected time and space complexity of startup and of each query case.
An Open Questions section is optional and ungraded.
We’ll grade your design document on completion and effort, not correctness. The correctness of your final design is checked by running the autograder on your code. We will grade your design document by the end of the week of the deadline.
Your design document must be readable and typed aside from your diagram. Aim for about 4 pages. Please include your diagram as a separate page upon submission. If your diagram doesn’t fit on one page, you may submit it as multiple pages. You may be deducted a format point penalty if you do not follow these instructions.
If you do not submit your design doc by the original deadline, we cannot guarantee that we’ll have it graded by the end of the week.
If you intend to work on this project during office hours, we may ask to see your design document to help understand your approach. As such, please put effort into this assignment! Grasping project requirements in the design phase will help immensely during the later implementation phases.
Write a design document for Wordnet and submit it to the Project 4B: Wordnet Design assignment.
Design Tips
Code and Data to Reference
You won’t need any new starter code to write your design doc. Everything you need is already available:
- Your Project 4A code. Wordnet reuses the same
browserpackage (NgordnetQuery,NgordnetQueryHandler, andNgordnetServer) and theNGramMapfrom 4A (a staff version will be provided). For k != 0, you’ll useNGramMap’scountHistorymethod. - The Wordnet data files. Download them from the Data spec now and open the small
ones:
synsets_size16.txt,hyponyms_size16.txt, and the EECS files (synsets_eecs.txt,hyponyms_eecs.txt, andword_history_eecs.csv). Trace a query by hand on these files before you design. You’ll need them for the Data section of your design doc. -
How the autograder creates your handler. In 4C, you’ll fill in this method in
AutograderBuddy.java, which returns yourHyponymsHandler:public static NgordnetQueryHandler getHyponymsHandler( String wordHistoryFile, String yearHistoryFile, String synsetFile, String hyponymFile)Your sequence diagram starts from this method.
We’ve included below a few questions for you to consider while brainstorming your design:
General Questions
- Poke around the
/browser,/main, and/demofolders in your Project 4A code and observe what code exists. How do the examples in the/demofolder use existing classes/methods? - How are a user’s inputs (i.e. hyponyms of “cat”, k > 0) communicated to us from the ngordnet website? How do we communicate results back to the website?
- You aren’t expected to know how the website works. However, it’s important to understand the boundaries of your implementation.
- Where do tasks overlap? Are there opportunities to reuse methods across different cases? Think about helper methods or opportunities to overload methods.
- Can you find groups of data structures and methods that serve a similar, clearly defined purpose? If so, consider moving them to a separate class. Building abstraction barriers may be helpful for managing code complexity.
- When are the data files read, and how does each object your handler needs get to it? Your sequence diagram should answer both questions.
Considering Edge Cases
- How will your implementation handle words that exist within multiple hyponyms?
- What output do we expect when a list of words are inputted? Under what circumstances is a synset a hyponym of two words? What about multiple words? How will your implementation determine the correct output?
- What output do we expect when the user provides a k > 0? Does this relate to anything we’ve already built?
Template
We have provided a template for you to use if you’d like. See the Project 4B: Wordnet Design Template, which is also linked in the assignment below. To use it, make a copy (File → Make a copy).
For the sequence diagram, we recommend the Mermaid Live Editor, which turns a few lines of text into a diagram you can export as a PNG. The template includes starter code. Any tool, including pen and paper, is fine as long as the diagram is readable. Do not use AI features to generate your diagram.
Alternatively, you can diagram your entire design. If you choose to do this, make sure you include all components in the rubric.
Submission
Once you have submitted to both assignments below, you’re done!
- Project 4B: Wordnet Checkpoint (20 points)
- Project 4B: Wordnet Design (30 points)
The score you receive on Gradescope is your final score for this assignment (assuming you followed the collaboration policy).
This spec was written by Daniel Wang and Ronnie Beggs as a new assignment in Fall 2025. The provided template was redesigned in Fall 2026 by Andrew Xu and edited by Reina Kushihashi and Marcus Koh, building on the Spring 2025 template created by Kanav Mittal and Stella Kaval and edited by Daniel Wang.