> For the complete documentation index, see [llms.txt](https://marcylabschool.gitbook.io/swe/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://marcylabschool.gitbook.io/swe/mod-4-interactive-data-driven-ui/8-interactive-data-driven-project.md).
# Project: Interactive & Data-Driven User Interfaces
**Table of Contents:**
* [Overview](#overview)
* [Deliverables](#deliverables)
* [Stretch Features: localStorage + AI](#stretch-features-localstorage--ai)
* [Milestones](#milestones)
* [Setup Steps](#setup-steps)
* [GitHub Organization & Scrum Board](#github-organization--scrum-board)
* [Vite Project + Project Repo](#vite-project--project-repo)
* [Product Spec Sheet](#product-spec-sheet)
* [Deployment with gh-pages](#deployment-with-gh-pages)
* [Git Workflow for Paired Projects](#git-workflow-for-paired-projects)
* [The Golden Rule](#the-golden-rule)
* [Branch Strategy](#branch-strategy)
* [The Workflow (Repeat for Every Ticket)](#the-workflow-repeat-for-every-ticket)
* [Dividing the Work into Tickets](#dividing-the-work-into-tickets)
* [Handling Merge Conflicts](#handling-merge-conflicts)
* [Daily Routine](#daily-routine)
* [Common Mistakes to Avoid](#common-mistakes-to-avoid)
* [Project Grading](#project-grading)
* [Fetching Requirements (8 points)](#fetching-requirements-8-points)
* [User Interface: Structure and Accessibility (12 points)](#user-interface-structure-and-accessibility-12-points)
* [General (9 points)](#general-9-points)
* [Form Requirements (9 points)](#form-requirements-9-points)
* [Tips for Success](#tips-for-success)
* [Choosing an Easy API to Work With](#choosing-an-easy-api-to-work-with)
* [Focus on demonstrating your learning, not building something unique.](#focus-on-demonstrating-your-learning-not-building-something-unique)
* [Make Decisions Quickly](#make-decisions-quickly)
* [Plan and Delegate!!](#plan-and-delegate)
* [Meet on your own time](#meet-on-your-own-time)
* [Test your API!](#test-your-api)
## Overview
It's time for your first paired project week! For this project, you and a partner will build an application that interacts with a third-party API. You will fetch data, render the fetched data to the DOM, and then fetch some more data! In the end, you will have a deployed interactive application that connects with a web API.
The main technical goal of your app is to **send two fetches** and render the fetched data:
1. First, fetch a collection of resources (GET a set of users, a set of pictures, a set of authors) and render all of those resources.
2. Fetch more details about a single one of those resources (GET details about a single user, a single picture, a single author, etc…) when the user interacts with the page.
By building this project, you will demonstrate the following technical skills:
* Structuring HTML with semantic elements
* CSS layout with Flexbox and Grid
* Media Query Responsiveness
* JavaScript form handling
* Modular Code with ES Modules
* Event handling and event delegation
Additionally, you will:
* Develop teamwork skills including communication, problem-solving, compromise, and task management
* Strengthen your Git workflow fundamentals, managing branches, navigating merge conflicts, and maintaining a repository
* Practice Agile methodologies by managing a scrum board and by performing daily stand-up and stand-down
* Deploy a project
* Practice your technical communication through a presentation
### Deliverables
Unlike your solo projects where the project itself was the main deliverable, for a portfolio-level project, you will be required to do a bit more. The deliverables below will help keep you and your partner organized and will help keep your Engineering Manager (your instructor) informed on your progress. In the end, all of these deliverables will serve as valuable artifacts that document your work.
**Deliverable Resources**
* [Project Spec Sheet Template](https://docs.google.com/document/d/1gSM_RWRAP_EJGQ7pp58Pti6PXKQJ_YWx3uvC4iRQ1EI/edit)
* [How to Create a Scrum Board](/swe/projects/2-how-to-create-scrumboard.md)!
* [Template Scrum Board](https://github.com/users/benspector-mls/projects/7/views/1)
* [Presentation Template](https://docs.google.com/presentation/d/1NvzL4yUaVSNFlmNtG3shNdK4j0oW3Ll2zbq8gK2vrzQ/edit?usp=sharing) — make sure to hit all of the talking points in the template but feel free to modify the design!
Expand each below to see details and examples.
A Deployed Project
* Your project must meet all of the grading requirements listed below.
* Each project is deployed on GitHub using an Organization
* Examples:
* [Art Viewer (Art Institute of Chicago API)](https://art-viewer-mike-example.github.io/art-viewer-day-4/)
* [Forecast It Already (Open Meteo Weather API)](https://forecast-it-already.github.io/Forecast-It-Already/)
* [We Cooked (TheMealDB)](https://we-cooked.github.io/cooked/)
* [Pokedex (PokeAPI)](https://phoenix-pokedex.github.io/Phoenix-Pokedex/)
* [Buldak (Jikan Anime/Manga API)](https://bul-dak.github.io/anime-web/)
A Project Spec Sheet
* A project spec sheet is a document that provides key details about the project including the API being used, the intended features/user stories, and wireframes.
* Examples:
* [Art Viewer Product Spec Sheet](https://docs.google.com/document/d/1ekNpWx_LKCFGPQ74qijXTMRJJoq4sHJIB1mv9Mg8HHk/edit)
A GitHub Organization and Scrum Board
* A GitHub Organization is a shared account on GitHub where you and your teammates can collaborate on repositories. Having a GitHub organization will make deployment straight forward.
* [We Cooked Organization](https://github.com/we-cooked)
* A scrum board is a tool for creating and assigning tasks ("tickets") within a project. Typically, a scrum board will organize tasks into these columns: *Backlog* (tasks waiting to be assigned), *In Progress* (assigned tasks that are being worked on), *In Review* (tasks to be reviewed), and *Done* (completed tasks).
* Examples:
* [We Cooked Completed Scrum Board](https://github.com/orgs/we-cooked/projects/1/views/1)\*
* [Sample "In Progress" Example](https://github.com/users/benspector-mls/projects/3/views/1?layout=board)
* [Starting Template To Copy](https://github.com/users/benspector-mls/projects/7/views/1)
A Professional README
Your `README.md` should be polished enough that a new engineer can understand and run your project without asking questions.
Example: [We Cooked Repository README](https://github.com/we-cooked/cooked)
At minimum, include:
* Project title and one-paragraph summary
* Live deployed link
* Team members
* API used (name + endpoints)
* Features section
* List your 2 MVP features
* List your stretch feature(s)
* Setup instructions
* `npm install`
* `npm run dev`
* Tech stack (`HTML`, `CSS`, `JavaScript`, `Vite`, etc.)
* Screenshots or GIFs
* Known limitations or future improvements
Use the same professional writing standards we expect in all artifacts:
* Clear section headers
* Correct spelling/grammar
* Consistent formatting
* No placeholder text
AI Usage Document (Required)
Generative AI tools are a required part of this project workflow, but you must be able to explain every line of code you submit.
Make a copy of this [AI Usage Document](https://docs.google.com/document/d/1xxhC0GWMqWOzoeY7_aCX8ERWY6avB4RrS5LAqla8CSI/copy) and track your usage.
For each meaningful AI interaction, you are required to document:
1. What you asked for (your prompt)
2. What you received (the AI response)
3. What you changed and why
4. How the final code works (in your own words)
Add a link to your AI Usage Document in your `README.md`, for example:
```md
This project provided us an opportunity to build with AI assistance. Check out our [AI Usage Document](PASTE_LINK_HERE) to see how we used AI on this project.
```
A Presentation + Walkthrough Demo Video
* The presentation is your "elevator pitch" to tell your audience about the project, how you built it, and what you learned through the process.
* Examples:
* [We Cooked Presentation](https://docs.google.com/presentation/d/1fm1dWFZofhChPFYlG4CcbOKGoE5ziJWtFNuzhKytm7k/edit?slide=id.g327ab0f0e7e_0_559#slide=id.g327ab0f0e7e_0_559) — This example does an excellent job with their demo recording, walking the audience through the features of the application.
* [Pickle Productions Presentation](https://docs.google.com/presentation/d/1Jbn9q0Pc8iUsJGCY93X3RoSkMVg0zSzHz7xFzVUuON4/edit) — This example does an excellent job at explaining their technical challenge and teamwork learnings.
### Stretch Features: localStorage + AI
Use AI to help you learn and implement `localStorage` for a real user-facing feature in your app.
Your localStorage stretch feature should:
* Store user preferences or user-generated state in the browser
* Persist after page refresh
* Be loaded on page start and reflected in the UI
* Include a clear way for users to update the stored value
Feature ideas:
* Save the most recently selected item and re-render it on reload
* Save filter/search form values so they persist on refresh
* Save a favorites list of fetched items
* Save a theme preference (light/dark) or display settings
Suggested AI workflow:
1. Ask AI: "How does `localStorage` work in JavaScript, and when should I use it?"
2. Ask AI: "Help me implement `` with `localStorage` in a Vite app."
3. Ask AI to review your implementation for edge cases:
* Missing keys
* Invalid JSON
* Clearing stale data
4. Refactor the code to match your project structure and naming conventions.
5. Document the full interaction in your AI Usage Document.
Quality bar for this stretch:
* `localStorage` reads/writes are wrapped in helper functions
* JSON parsing/stringifying is handled safely
* UI still works when `localStorage` is empty
* The feature is demonstrated in your walkthrough video
### Milestones
As you work on this project, don't set your sights on the fully completed project from the jump. Give yourself smaller goals that you can reach each day and focus on one goal at a time. As long as your goals build on each other, you will eventually reach your final destination.
For this Art Viewer project, you can see the progress made on each day.
* [https://art-viewer-mike-example.github.io/art-viewer-day-1](https://art-viewer-mike-example.github.io/art-viewer-day-1/) (just the app is deployed. It doesn't do anything yet)
* [https://art-viewer-mike-example.github.io/art-viewer-day-2](https://art-viewer-mike-example.github.io/art-viewer-day-2/) (we can fetch and then render a list of pictures)
* (we can click on a picture to fetch more details about that one picture)
*Note: no need to create a new repo for each day - this is just done this way for demonstration purposes.*
Eventually, you will need to develop the skill of planning out your objectives. However, for this project we've laid out some daily milestones that you can strive for with bare minimum requirements, ideal progress, and stretch goals. Remember: a feature isn't "done" until it's been reviewed and merged to `main` via a PR.
{% tabs %}
{% tab title="Day 1" %}
* **Bare Minimum:**
* [ ] Product Spec Sheet is complete with API endpoints, user stories, and a wireframe that shows thoughtful idea about what data is displayed.
* [ ] Scrum board is populated with tickets (use the ticket breakdown above as a starting point). Partners have assigned themselves tickets.
* **Ideal:**
* [ ] GitHub Organization and Repo is created.
* [ ] Vite project skeleton is set up pushed — both partners do this together on `main`. This is the one time you push directly to `main`.
* **Stretch:**
* [ ] Partners each create their first feature branch and start working.
* Note: If you have not submitted your proposal and are undecided about your API by this deadline, you will be assigned an API and product spec sheet by your Engineering Manager.
{% endtab %}
{% tab title="Day 2" %}
* **Bare Minimum:**
* [ ] All Day 1 goals are completed.
* [ ] Each partner has opened and merged at least one PR (e.g., Partner A: fetch function, Partner B: form HTML).
* **Ideal:**
* [ ] Fetch functions for both endpoints are written, tested in the console, and merged to `main`.
* [ ] HTML structure is complete.
* **Stretch:**
* [ ] Render functions are written and merged. Fetched data appears on the page.
{% endtab %}
{% tab title="Day 3" %}
* **Bare Minimum:**
* [ ] All Day 1–2 goals are completed.
* [ ] Both fetches render data to the page (merged to `main`).
* **Ideal:**
* [ ] Event handling is wired up — clicking an item fetches and displays details, or submitting the form triggers a fetch. These are merged via PRs.
* **Stretch:**
* [ ] Layout (flexbox / grid) and basic responsive styling is added.
{% endtab %}
{% tab title="Day 4" %}
* **Bare minimum:**
* [ ] All Day 1–3 goals are completed.
* [ ] Responsive layout is merged.
* [ ] All open branches are merged or closed — `main` represents your working app.
* **Ideal:**
* [ ] Project is deployed (build the Vite project and push to `main`).
* [ ] Presentation slides are created and posted on Canvas.
* [ ] Begin implementing localStorage stretch feature (on a new branch!).
* **Stretch:**
* [ ] localStorage feature is merged.
{% endtab %}
{% tab title="Day 5" %}
* **Bare minimum:**
* [ ] All Day 1–4 goals are completed.
* [ ] The localStorage stretch feature is merged. No open branches remain.
* **Ideal:**
* [ ] Presentation slides are complete with a recorded demo video.
* [ ] GitHub Repo README is polished with screenshots, live link, and AI Usage Doc link.
* **Stretch:**
* [ ] Additional stretch features.
{% endtab %}
{% endtabs %}
## Setup Steps
### GitHub Organization & Scrum Board
First, we will create the GitHub organization and Scrum Board that will enable you and your partner to collaborate on the project.
1. Create a new GitHub organization for your team. Only one person needs to do this. They will provide their email for verification and then invite their partner as a collaborator.
2. Copy the [Scrum Board template](https://github.com/users/benspector-mls/projects/7/views/1).
1. Make your organization the Owner
2. Make sure to check the box that says "Draft issues will be copied if selected".
3. Remove "\[COPY]" from the project name.
3. Then, you can get started assigning tickets! We recommend completing the **Project Setup** and **Assign Tasks** tickets as a team before assigning individual tickets. When a ticket is assigned, move it to the "In progress" column.
### Vite Project + Project Repo
Next, we will create the Vite Project that will serve as the starting point for your project.
1. Both partners should open VS Code and `cd` into the directory where they plan on working.
2. One person in your group should run `npm create vite@latest` to create the project starter code
* Remove any unnecessary code provided by Vite, but keep the `index.html`, `styles.css`, and `main.js` files.
* Create additional module files such as `src/dom-helpers.js` and `src/fetch-helpers.js`.
3. Make a new repository owned by your GitHub organization.
* It should have NOTHING in it.
* The name should be `mod-4-project` (you can change it later).
* Make sure it is **public**.
4. It will then provide instructions to turn your existing Vite project into a repo and push to your newly created repo. It will tell you to run these commands:
```bash
git init
git add -A
git commit -m "init"
git branch -M main
# update the url below (after "origin") with your own blank repo from step 1
git remote add origin git@github.com:{organization-name}/{repo-name}.git
git push -u origin main
```
### Product Spec Sheet
Before you begin coding, you must align as a team on your project vision by making a Product Spec Sheet.
1. Make a copy of the [Template](https://docs.google.com/document/d/1gSM_RWRAP_EJGQ7pp58Pti6PXKQJ_YWx3uvC4iRQ1EI/edit)
2. Update your Share settings to "Anyone with the link > Commenter"
3. Post your team's Product Spec Sheet on Canvas.
Here is an example of the [Art Viewer Product Spec Sheet](https://docs.google.com/document/d/1ekNpWx_LKCFGPQ74qijXTMRJJoq4sHJIB1mv9Mg8HHk/)
Completing this is your first deliverable!
### Deployment with gh-pages
As you write your code, your project is considered "in development". When we are ready to share the project with the world, we will **deploy** it. The main differences between a project in development and a deployed project are **file storage**, **access**, and **uptime**.
In development you use a development server (like Vite) that runs on `localhost`:
* *File Storage*: The files are stored on your computer.
* *Access*: Only you can see it. If you send the link `http://localhost:5173` to a friend, it won't work for them.
* *Uptime*: When your computer turns off, the server stops running as well.
**Deployment** is the act of moving your finished work to a publicly accessible server which is just a computer whose resources you can access over a network. We'll be deploying our code onto GitHub's servers:
* *File Storage*: The files are stored on one of GitHub's servers.
* *Access*: Anyone with the URL can see the project and access the files.
* *Uptime*: GitHub keeps the servers running. Even if you turn your computer off, your website stays online because its living on their hardware, not yours.
{% hint style="info" %}
A deployment server often refers to both the *computer hardware* that is "hosting" our files and the *server-side application* running on it is programmed to wait for incoming requests and sends those files to the user requesting them ("the client").
GitHub Pages is known as a **static web server** which means that it just stores our HTML, CSS, and JS files and serves them directly to the user. Every user will get the exact same website and user experience.
In the upcoming Backend unit, you will learn how to create your own **dynamic server-side applications**, enabling you customize what the client receives based on who they are, what resources they've requested, etc. In other words, you will be able to create your own APIs.
{% endhint %}
To deploy your project with GitHub pages, follow these steps:
**Step 1: Create and Update `vite.config.js`**
Create a file called `vite.config.js` at the root of your repository and add the code below. If you've changed the name of your repository from `mod-4-project` to something else, make sure to update this file.
```js
import { defineConfig } from 'vite'
// https://vitejs.dev/config/
export default defineConfig({
base: "/mod-4-project/"
})
```
**Step 2: Install gh-pages**
Install the `gh-pages` package as a dev dependency. It makes it incredibly easy to deploy.
```sh
npm install gh-pages --save-dev
```
**Step 3: Add predeploy and deploy scripts to package.json**
Add the following `"predeploy"` and `"deploy"` scripts to your `package.json` file:
```json
"scripts": {
// other scripts...
"predeploy" : "npm run build",
"deploy" : "gh-pages -d dist"
}
```
**Step 4: Add the homepage to package.json**
GitHub pages will serve your website at `https://{github-organization}.github.io/{repo-name}/`.
Add the complete website URL by adding a `"homepage"` to your package.json. Make sure to update the organization name (keep `.github.io`) and the repo name
```json
{
"name": "mod-4-project",
"private": true,
"version": "0.0.0",
"type": "module",
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview",
"predeploy": "npm run build",
"deploy": "gh-pages -d dist"
},
"devDependencies": {
"gh-pages": "^6.3.0",
"vite": "^7.3.1"
},
"homepage": "https://marcy-example-organization.github.io/mod-4-project/"
}
```
**Step 5: Run Deploy**
Now, deploy your project! Run the command:
```sh
npm run deploy
```
And you’re done!
**Step 6: GitHub Configuration**
Lastly, Go to your GitHub repository and navigate to Settings -> Pages (left sidebar). Select source as “Deploy from branch” and branch as “gh-pages”.
Wait for a few minutes and soon, your site will be live!
## Git Workflow for Paired Projects
This is likely your first time collaborating on code with another person using Git. The workflow below is intentionally simple. Follow it closely and you'll avoid most of the headaches that come from working in the same codebase.
### The Golden Rule
**Never push directly to `main`.** All work happens on branches. Code gets into `main` through Pull Requests (PRs) that your partner reviews.
### Branch Strategy
Use **feature branches** — short-lived branches where each branch corresponds to one ticket on your scrum board.
Branch naming convention: `feature/short-description`
Examples:
* `feature/fetch-all-items`
* `feature/render-item-list`
* `feature/single-item-section`
* `feature/form-html`
* `feature/responsive-layout`
### The Workflow (Repeat for Every Ticket)
```
1. Pull the latest main
git checkout main
git pull origin main
2. Create a new branch for your ticket
git checkout -b feature/your-ticket-name
3. Do your work, committing as you go
git add .
git commit -m "Add fetch function for all artworks"
4. Push your branch to GitHub
git push origin feature/your-ticket-name
5. Open a Pull Request on GitHub
- Base: main ← Compare: feature/your-ticket-name
- Assign your partner as a reviewer
6. Your partner reviews the PR
- Look it over, leave comments or approve
- The reviewer merges the PR on GitHub
7. Both partners pull the updated main
git checkout main
git pull origin main
```
Then start the next ticket from step 1.
### Dividing the Work into Tickets
The key to working in parallel is to **split work by feature, not by file**. Each ticket should be a vertical slice — the HTML, CSS, JS, and fetch logic needed for one piece of functionality.
Here is a suggested way to break the project into tickets. The ticket numbers suggest a rough order, but tickets at the same level can be worked on in parallel by different partners.
**Setup (do together, Day 1) — this is the one time you push directly to `main`**
1. **Project Setup** — Create GitHub Organization, repo, and clone locally. Set up Vite project with initial file structure (`index.html`, `styles.css`, `app.js`)
2. **Assign Tickets** — Assign tickets in the backlog to each team member.
**Partner A: Fetch & Render All Items:**
3. **Collection section HTML & CSS** — Create a `` for displaying the collection of data with a `h2` and a `ul` to be filled using JavaScript
4. **Fetch all items** — Write a fetch function that GETs the collection endpoint and logs the data. Include `async/await`, `try/catch`, `response.ok` check.
5. **Render item list** — Write a function that takes the fetched array and renders `` elements inside the `` in the collection ``. Use `createElement`
6. **Responsive grid layout** — Style the item list using CSS Flexbox or Grid. Add a media query so items stack on mobile and sit side-by-side on desktop.
**Partner B: Fetch & Render One Item:**
7. **Single item section HTML + CSS** — Create the `` for displaying a single fetched item with its `` and placeholder content.
8. **Fetch single item** — Write a fetch function that GETs the "single item" endpoint and logs the data. Include `async/await`, `try/catch`, `response.ok` check.
9. **Fetch on Click** — Add an event listener (using event delegation on the ``) that fetches details for one item and renders them in the single-item section.
**Either partner (after earlier tickets merge):**
10. **Build the form HTML** — Create the `