How yuhonas/free-exercise-db works
1. This repository is primarily a static public dataset, not a traditional service. The core asset is a large collection of per-exercise JSON documents under exercises/, each paired with image assets in a matching directory structure.
2. The data model is defined centrally in schema.json. Each exercise document is expected to conform to that schema, which standardizes fields such as id, name, equipment, primaryMuscles, instructions, and images. Some fields are intentionally nullable for incomplete records.
3. The main data boundary is between the raw exercise records and the generated distribution artifacts in dist/. The key output is dist/exercises.json, which combines the individual exercise JSON files into one array for easier consumption by downstream tools and clients.
4. The root Makefile is the data/build orchestrator. From the README, it supports schema linting of all exercise files, building the combined JSON artifact, and producing newline-delimited JSON for PostgreSQL import. This means the repo supports both “static dataset” and “database ingestion” use cases from the same source data.
5. Images are treated as static companion assets rather than embedded data. The JSON records reference image paths like Exercise_Name/0.jpg, and the README explains that hosted consumers can prefix those paths with the repository’s raw GitHub URL. This keeps the dataset portable while allowing external hosting.
6. The site/ directory is a separate frontend application built with Vue 3 and Vite. It is the browsable/searchable UI for the dataset and is explicitly described as a simple frontend over the exercise data, hosted on GitHub Pages.
7. The frontend is componentized around a few clear responsibilities: SearchBar handles filtering input, PhotoGallery renders exercise imagery, and ExerciseInstructions presents the movement instructions/details. The app shell lives in site/src/App.vue, with shared styles in site/src/assets/main.css.
8. The frontend reads static content, not backend APIs. Its data flow is from bundled/static JSON and image assets into the Vue components, then into the browser UI for browsing, searching, and paginating exercises. There is no server-side application layer in the repo.
9. Tests are split by concern. Component unit tests live alongside the Vue components under site/src/components/__tests__, while Cypress end-to-end coverage lives under site/cypress/e2e and focuses on user-facing flows such as searching and paginating.
10. Build and quality automation is handled by GitHub Actions in .github/workflows/ci.yaml. The README indicates this pipeline runs linting, tests, and deployment of the site to GitHub Pages, so CI is the integration point for both dataset validation and frontend release.
11. Operationally, the repository has two deployment surfaces: the static dataset files in GitHub-reachable raw paths, and the published frontend site on GitHub Pages. Consumers can either ingest the JSON directly or use the hosted browsing UI.
12. For an architecture diagram, the most important boxes are: raw exercise records and images, schema/validation/build tooling, generated distribution artifacts, and the Vue/Vite frontend with its component layer. The key flow is source data → validation/aggregation → static distribution → browser frontend.
Main entry points: App.vue App Shell · exercises Static Content · SearchBar.spec.js Component Tests · Makefile Makefile
Components 16
Dataset
Raw exercise records, schema, and generated distribution artifacts.
- Schema · Central contract for exercise records and nullable fields.
schema.json - Exercises · Per-exercise JSON documents as the source corpus.
exercises/3_4_Sit-Up.json - Images · Companion image directories referenced by each exercise record.
exercises/3_4_Sit-Up - Dist JSON · Combined exercise array for downstream consumption.
dist/exercises.json
Frontend
Vue/Vite browsing UI over the static dataset.
- App Shell · Main frontend shell that composes browsing and display components.
site/src/App.vue - Search Bar · Handles filtering input and query interactions.
site/src/components/SearchBar.vue - Photo Gallery · Renders exercise imagery for the selected record.
site/src/components/PhotoGallery.vue - Instructions · Displays exercise details and movement steps.
site/src/components/ExerciseInstructions.vue - Shared Styles · Global styling for the Vue frontend.
site/src/assets/main.css - Static Content · Exercise JSON and image assets served directly to the browser.
site/public/exercises - Component Tests · Unit tests for Vue components.
site/src/components/__tests__/SearchBar.spec.js - E2E Tests · Browser-level coverage for searching and pagination flows.
site/cypress/e2e/searching_and_paginating.cy.js - Site Config · Frontend toolchain and bundler configuration for Vite-based static hosting.
site/vite.config.js - Package Manifest · Frontend package and script definitions for the Vue app.
site/package.json
Automation
Build, validation, and CI release orchestration.
- Makefile · Runs schema linting, dataset aggregation, and export tasks.
Makefile - CI Pipeline · Automates linting, tests, and site deployment.
.github/workflows/ci.yaml
Connections 24
- Exercises → Schema: conforms to · Each exercise JSON document is validated against the shared schema.
- Images → Exercises: referenced by · Record image paths point to companion assets in matching directories.
- Makefile → Exercises: lint/build · Orchestrates schema checks and aggregation over the source corpus.
- Makefile → Schema: validates · Uses the schema as the contract for linting the dataset.
- Makefile → Dist JSON: generates · Builds the combined exercises.json distribution artifact.
- CI Pipeline → Makefile: runs · CI executes the build and validation workflow.
- CI Pipeline → Component Tests: runs · CI executes unit tests for frontend components.
- CI Pipeline → E2E Tests: runs · CI executes browser end-to-end coverage.
- Dist JSON → Static Content: publishes · The combined dataset is exposed as static browser-consumable content.
- Images → Static Content: serves · Image assets are mirrored or hosted as static public files for the site.
- Static Content → App Shell: feeds · The frontend reads static exercise data without a backend API.
- App Shell → Search Bar: composes · App shell includes the search/filter control.
- App Shell → Photo Gallery: composes · App shell includes the image gallery.
- App Shell → Instructions: composes · App shell includes movement instructions and details.
- App Shell → Shared Styles: uses · App shell is styled by shared global CSS.
- App Shell → Site Config: built by · The Vue app is bundled and served through the Vite toolchain.
- Site Config → Package Manifest: uses · Bundler behavior is driven by the frontend package scripts and dependencies.
- Search Bar → Static Content: filters · Search operates over the static exercise collection.
- Instructions → Static Content: displays · Instruction view renders record details from static content.
- Photo Gallery → Static Content: displays · Gallery renders the static image references associated with exercises.
- Component Tests → Search Bar: covers · Component tests exercise the search component.
- Component Tests → Photo Gallery: covers · Component tests exercise the gallery component.
- Component Tests → Instructions: covers · Component tests exercise the instructions component.
- E2E Tests → App Shell: covers · E2E tests validate user-facing flows in the browser app.