Repository navigation
Deliverables
- Andrew Cambridge
- Anna Egbert
- Brayden Walker
- Connor Harvey
- Ethan Rushforth
- Justin Palmer
By the end of this project, we aim to have all of these features.
Note
Emphasized items are non-negotiable and cannot be dropped or postponed to a future update without crippling the release version.
-
Flashcards — create and use digital flashcards
- Save (and load) flashcard decks
- Edit existing decks
- "definition" flashcards — expect the answer to be an exact match
- "concept" flashcards — user-graded, answer may not be an exact match but should identify key points
- "function" flashcards — define a set of variables and the function that produces the answers, then randomize values each time
- restrict answer & variables to "neat" values (must be integers, max/min values, etc)
- display variables within a word problem (or set of word problems) provided when building
- Study mode — present a random flashcard's question, take user input, score response
- Test/Quiz mode — multiple choice/matching/fill-in-the-blank questions based on a flashcard deck
- Define allowed question types per card and randomize from that list
Features in this section are to be implemented only after the release project is complete. This section represents features to be added in ANY future version, not necessarily the next.
Important
Any new features (or extensions of features) not already required by the previous section must fall into this category.
- Flashcards
- Update "concept" flashcard grading
- addition of an (optional) AI model that can determine whether a free-response answer is conceptually identical
- AI grading can be overridden by the user
- addition of an (optional) AI model that can determine whether a free-response answer is conceptually identical
- Histogram showing learning progress over time for a given deck
- possibly as detailed as by card
- reuse data to target frequently missed
- "sequential" flashcards — place a series of events/steps in order
- "flowchart" flashcards cards — similar to sequential, but for non-linear processes
- "checkbox" flashcards — have multiple correct answers
- can be free-response
- apply either exact or approximate answer-checking (or AI checker, if implemented)
- Custom flashcard API — allow advanced users to create their own flashcard types, so long as they create the right interface
- provide some kind of package?
- Cloud storage for decks
- Update "concept" flashcard grading
- Games
- Convert to a mobile app
- Required feature logic completed
- Simple UI (could be CLI)
- Function flashcards (partial)
- Test/Quiz mode (partial)
- More developed UI (definitely not CLI, but not necessarily pretty either)
- Bug-free (as far as we can tell)
- All planned features complete
- UI ready for non-technical users
Note that the required features have shifted slightly from deliverable 3. This is intentional; these planned features were more realistic.
if the images fail to embed, the image can be also found here, though the critical path may not be highlighted (critical tasks are bolded in the PERT calculation table). If images load but look strange, try using the open image in new tab option via the right-click menu.
| Contents |
|---|
| 1. Purpose and scope |
| 2. Goals and Quality Requirements |
| 3. Architecture Overview |
| 4. Subsystems in detail |
| 5. Data Design |
| 6. Deployment, support, and cost |
| 7. Hard problems and risks |
Quizlet BB is a customizable flashcard website that, other than a remote database, runs entirely on the client. Its main distinction is that users can create custom flashcards (using TypeScript/JavaScript) that follow the project’s interface, then have the app render and display them.
Planned features include deck creation, editing, saving, and loading; flashcard and quiz modes; custom flashcards; and cloud saving for logged-in users. Users can also export decks to a file and import them later. A function flashcard will be provided as an example custom flashcard and as a test of how custom-card system functions for card developers.
This document describes the system’s major parts, how they connect, the main design choices, and the technical risks to address early.
The project must address all of the quality areas in the assignment. The most relevant constraints are that the project has the financial backing of a handful of college students (leading to a total budget of $0), it must be built entirely in less than a single semester, and that the app will be running in a browser.
| Quality | Design goal |
|---|---|
| Reliability | Avoid losing deck data. Validate decks and custom-card inputs, handle storage failures clearly, and support file export and re-import. Extensive testing will be performed on each system to ensure proper handling of edge cases. |
| Performance | Keep common deck and study interactions responsive and snappy. Custom cards should not be able to block the page indefinitely. |
| Functionality | Support deck creation, editing, flashcard mode (answer is simply displayed on request), quiz mode (user input is scored against flashcard answer), support for user-built flashcards, cloud saving for logged-in users, and file export/import. |
| Competitiveness | Stand out through user-written custom flashcards and flexible grading, rather than only through standard study modes. |
| Compatibility | Work as a website in all major browsers (Firefox, Chromium/Chrome, and Safari/Webkit) |
| Lifespan | Exported files provide a way for users to keep their work. The project is only planned to be live for this December's final exam season; keep the card interface and deck format maintainable just in case. |
| Deployment | Deploy the web app through Vercel and use Supabase for authentication and cloud storage. |
| Support | Treat support and maintenance as limited to the class and hobby project. Post-semester support is not guaranteed, but is possible assuming financial feasibility. Project will remain public for self-hosting. |
| Cost | Use free hosting and service tiers where possible; design should function within the limits of those tiers. |
The current repository organization is:
flowchart TD
A["App"] --> B["Components"]
A --> C["Hooks"]
B --> C
B --> D["Service"]
C --> D
D --> E["Storage"]
Edges between folders represent permitted dependencies. An additional Shared folder is accessible by all layers.
Our system architecture is approximately the following:
| System | Description |
|---|---|
| Storage | Consists of a localStorage implementation as well as a remote database provided by Supabase. Supabase was chosen to enable us to forgo having a backend, and simply make direct calls to the database from the client (safely) |
| Authentication | Also via supabase, to enable their RLS features (critical for security) |
| Deck Management | Drives the exporting, loading, creating, and editing processes for flashcard decks |
| Quiz Mode | Poses questions to be answered by the user from a deck (retrieved from Deck Management/memory) |
| Flashcard Mode | Similar to Quiz Mode, except it simulates a standard paper flashcard instead of an interactive quiz |
| Custom Flashcard | Each custom flashcard is an independent system that interacts with interfaces exposed by Deck Management, Quiz Mode, and Flashcard Mode. The system is heavily sandboxed for security purposes |
The interaction between these systems is shown here:
flowchart BT
subgraph Storage
Local[(localStorage)]
Cloud@{ shape: cloud, label: "Cloud Storage via Supabase"}
end
subgraph Sandbox
CF[[Custom Flashcard]]
end
A["Authentication (via Supabase)"] --> Cloud
DM["Deck Management"] --> Storage
Sandbox --> DM
Sandbox --> FM["Flashcard Mode"]
FM --> DM
Sandbox --> QM["Quiz Mode"]
QM --> DM
This system manages storing flashcard decks and custom code. Since the Deck Management system will deal with converting flashcards into a storeable file format, both localStorage and cloud storage can simply store these files (likely as text) and retrieve them upon request.
Supabase provides a pre-built authorization system that can be easily integrated into an app. The SupabaseClient class provided by the @supabase/supabase-js package exposes auth functions in addition to standard query functions, and manages almost every aspect of authorization. The way to interface with this object is well-documented, and implementation should follow Supabase documentation.
This is the most critical system of the app, as it produces and manages the Deck and Flashcard objects used everywhere else. Most engineering here will be data design (see section 5). However, it will also need to modify that data and convert it into saveable formats (csv or json are likely candidates). Decks should be able to add or remove flashcards, and all possible options for individual flashcard configurations should be visible and make their function obvious. In regards to exporting and importing files, a distinction should be made between whether a user is exporting a deck to share (which would need to remove personal history) or to save for personal use. Lastly, all data formats need to be validated and errors should be clearly presented to the user while also remaining recoverable.
This system is by far the simplest. It merely needs to loop through each flashcard, rendering one side, then flipping (rendering the other side) on the user's request. If time permits, we may add a way for the user to mark a card for restudying, and allow them to redo this subset of the deck once each card has been viewed.
This system is another loop similar to Flashcard mode, but graded. There will be several grading scales flashcards can use: binary (right/wrong), stars (out of 5) and percentage(rounded to the nearest 1%). These may be implemented as a single value with different display modes, or could use wholly distinct values under the hood; the particulars are beyond the scope of this document. There will also be two modes of grading: user-driven (the user scores their own answer—useful for large blocks of text) or automatic (with an option for the user to override with their own score). Scores will be tracked with each card, and the data displayed to the user at the end of the session. Further use of this scoring data is possible, but will be "bonus" functionality to be added if time permits.
Custom flashcards will exist as their own system, provided they implement the right interfaces. They will need to implement a "save" function that converts their data into a text string, and also a "load" function that can extract this data and construct a flashcard object. This flashcard object will need to provide methods for editing/creating cards (including UI), though we will provide prebuilt methods and components for the most common formats (LaTeX, Markdown, raw text, etc.). Flashcards will need to implement similar methods for rendering in the Flashcard and Quiz modes, as well as validation for the Quiz Mode (though again, we will provide common methods that can be called/copied in).
This system has the most unknown unknowns, so much of the implementation will require a degree of research or trial and error. Hence, this system gets the bulk of our available development time (at least 1.5 demos will be spent here).
We will be implementing a "Function" flashcard to refine the interface. Function flashcards aim to provide randomly generated values to populate word problems (provided with the card, not AI generated) as well as a function to determine the answer of said word problem. This requires building some form of algebraic calculator, as well as a way to generate inputs in such a way that the output is reasonable for any arbitrary formula (as in, not 10 decimal places. It is undetermined whether we will have enough time to give the user full control over both input AND output bounds, but the important part is testing our interface, so it doesn't particularly matter).
We will also need to modify the file import/export design made for the Deck Manager so that we can provide a .zip file of interfaces, and receive a .zip of a completed flashcard.
Most importantly, ustom-card code is untrusted and must run in an isolated sandbox. It should receive only the card data needed for the current operation and communicate with the app through a narrow, validated interface. It must not have access to deck storage, authentication state, or the Supabase client. Row Level Security protects database operations and will prevent data breaches, but it is not a substitute for isolating custom code.
A deck contains the information needed to identify and display its cards. Cards need to distinguish their content from the implementation that renders and grades them. For a custom card, that likely means storing card data separately from the custom-card implementation or type it uses.
Our current model has the following objects:
- Deck: identifier, title, array of contained cards, custom card type implementations, and ownership or storage information.
- Card: identifier, card type, prompt or card data, answer history, and any grading configuration.
- Custom Card: identifier, custom type, answer history, and data string (to be parsed by the custom implementation)
It is vital that all interfaces remain as stable as possible in order to prevent custom cards from becoming obsolete across versions.
The website will use Next.js and deploy on Vercel. Supabase is the planned authentication and cloud storage provider. The project will rely on free service tiers and is not intended to have long-term hosting or support commitments.
The team should document how to configure deployment and required Supabase settings so another team member can reproduce the release. The design should also make the export/import path usable if hosted access ends, so that interested users can continue to use their flashcards (by cloning our repository).
- Sandboxing user-written cards. Custom code must be isolated from user data and app credentials while still being able to render and grade a card. This is the largest architectural risk and should be tested before building many card types.
- Defining a durable custom-card interface. The interface must support rendering, input, grading, and multiple grading scales. Changes to it may break existing custom cards, so its contract and versioning need early attention.
- Saving and transferring decks. localStorage, Supabase, and exported files must represent decks consistently. Import should validate files and report unsupported or invalid content without silently losing work.
- Maintaining consistent grading behavior. The app must support self-grading for concept cards and grading implemented by custom cards while giving users understandable results.
- Testing the function-card example. Because it is intended as an extensive test of the custom-card system, it should exercise configuration, randomized values, prompt display, answer generation, and grading.