# yuhonas/free-exercise-db architecture

> Architecture diagram of the GitHub repository yuhonas/free-exercise-db, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yuhonas/free-exercise-db
- Repository: https://github.com/yuhonas/free-exercise-db

## Overview

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: [`site/src/App.vue`](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/App.vue) (App Shell), [`site/public/exercises`](https://github.com/yuhonas/free-exercise-db/tree/main/site/public/exercises) (Static Content), [`site/src/components/__tests__/SearchBar.spec.js`](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/__tests__/SearchBar.spec.js) (Component Tests), [`Makefile`](https://github.com/yuhonas/free-exercise-db/tree/main/Makefile) (Makefile)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset"]
  node_schema["Schema<br/>[schema.json]"]
  node_exercise_records["Exercises<br/>raw dataset<br/>[3_4_Sit-Up.json]"]
  node_exercise_images["Images<br/>static assets"]
  node_dist_bundle["Dist JSON<br/>distribution artifact<br/>[exercises.json]"]
end

subgraph group_site["Frontend"]
  node_site_app["App Shell<br/>vue app<br/>[App.vue]"]
  node_search_bar["Search Bar<br/>vue component<br/>[SearchBar.vue]"]
  node_gallery["Photo Gallery<br/>vue component<br/>[PhotoGallery.vue]"]
  node_instructions["Instructions<br/>vue component"]
  node_styles["Shared Styles<br/>css<br/>[main.css]"]
  node_site_data["Static Content<br/>bundled static data"]
  node_site_tests["Component Tests<br/>vitest<br/>[SearchBar.spec.js]"]
  node_e2e_tests["E2E Tests<br/>cypress"]
  node_site_config["Site Config<br/>build config<br/>[vite.config.js]"]
  node_package_manifest["Package Manifest<br/>package config<br/>[package.json]"]
end

subgraph group_ops["Automation"]
  node_makefile["Makefile<br/>build orchestrator"]
  node_ci["CI Pipeline<br/>github actions<br/>[ci.yaml]"]
end

node_exercise_records -->|"conforms to"| node_schema
node_exercise_images -->|"referenced by"| node_exercise_records
node_makefile -->|"lint/build"| node_exercise_records
node_makefile -->|"validates"| node_schema
node_makefile -->|"generates"| node_dist_bundle
node_ci -->|"runs"| node_makefile
node_ci -->|"runs"| node_site_tests
node_ci -->|"runs"| node_e2e_tests
node_dist_bundle -->|"publishes"| node_site_data
node_exercise_images -->|"serves"| node_site_data
node_site_data -->|"feeds"| node_site_app
node_site_app -->|"composes"| node_search_bar
node_site_app -->|"composes"| node_gallery
node_site_app -->|"composes"| node_instructions
node_site_app -->|"uses"| node_styles
node_site_app -->|"built by"| node_site_config
node_site_config -->|"uses"| node_package_manifest
node_search_bar -->|"filters"| node_site_data
node_instructions -->|"displays"| node_site_data
node_gallery -->|"displays"| node_site_data
node_site_tests -->|"covers"| node_search_bar
node_site_tests -->|"covers"| node_gallery
node_site_tests -->|"covers"| node_instructions
node_e2e_tests -->|"covers"| node_site_app

click node_schema "https://github.com/yuhonas/free-exercise-db/blob/main/schema.json"
click node_exercise_records "https://github.com/yuhonas/free-exercise-db/blob/main/exercises/3_4_Sit-Up.json"
click node_exercise_images "https://github.com/yuhonas/free-exercise-db/tree/main/exercises/3_4_Sit-Up"
click node_dist_bundle "https://github.com/yuhonas/free-exercise-db/blob/main/dist/exercises.json"
click node_makefile "https://github.com/yuhonas/free-exercise-db/tree/main/Makefile"
click node_ci "https://github.com/yuhonas/free-exercise-db/blob/main/.github/workflows/ci.yaml"
click node_site_app "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/App.vue"
click node_search_bar "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/SearchBar.vue"
click node_gallery "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/PhotoGallery.vue"
click node_instructions "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/ExerciseInstructions.vue"
click node_styles "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/assets/main.css"
click node_site_data "https://github.com/yuhonas/free-exercise-db/tree/main/site/public/exercises"
click node_site_tests "https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/__tests__/SearchBar.spec.js"
click node_e2e_tests "https://github.com/yuhonas/free-exercise-db/blob/main/site/cypress/e2e/searching_and_paginating.cy.js"
click node_site_config "https://github.com/yuhonas/free-exercise-db/blob/main/site/vite.config.js"
click node_package_manifest "https://github.com/yuhonas/free-exercise-db/blob/main/site/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schema,node_exercise_records,node_exercise_images,node_dist_bundle toneBlue
class node_site_app,node_search_bar,node_gallery,node_instructions,node_styles,node_site_data,node_site_tests,node_e2e_tests,node_site_config,node_package_manifest toneAmber
class node_makefile,node_ci toneMint
```

## Components

### Dataset

Raw exercise records, schema, and generated distribution artifacts.

- [Schema](https://github.com/yuhonas/free-exercise-db/blob/main/schema.json): json schema · Central contract for exercise records and nullable fields. · `schema.json`
- [Exercises](https://github.com/yuhonas/free-exercise-db/blob/main/exercises/3_4_Sit-Up.json): raw dataset · Per-exercise JSON documents as the source corpus. · `exercises/3_4_Sit-Up.json`
- [Images](https://github.com/yuhonas/free-exercise-db/tree/main/exercises/3_4_Sit-Up): static assets · Companion image directories referenced by each exercise record. · `exercises/3_4_Sit-Up`
- [Dist JSON](https://github.com/yuhonas/free-exercise-db/blob/main/dist/exercises.json): distribution artifact · Combined exercise array for downstream consumption. · `dist/exercises.json`

### Frontend

Vue/Vite browsing UI over the static dataset.

- [App Shell](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/App.vue): vue app · Main frontend shell that composes browsing and display components. · `site/src/App.vue`
- [Search Bar](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/SearchBar.vue): vue component · Handles filtering input and query interactions. · `site/src/components/SearchBar.vue`
- [Photo Gallery](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/PhotoGallery.vue): vue component · Renders exercise imagery for the selected record. · `site/src/components/PhotoGallery.vue`
- [Instructions](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/ExerciseInstructions.vue): vue component · Displays exercise details and movement steps. · `site/src/components/ExerciseInstructions.vue`
- [Shared Styles](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/assets/main.css): css · Global styling for the Vue frontend. · `site/src/assets/main.css`
- [Static Content](https://github.com/yuhonas/free-exercise-db/tree/main/site/public/exercises): bundled static data · Exercise JSON and image assets served directly to the browser. · `site/public/exercises`
- [Component Tests](https://github.com/yuhonas/free-exercise-db/blob/main/site/src/components/__tests__/SearchBar.spec.js): vitest · Unit tests for Vue components. · `site/src/components/__tests__/SearchBar.spec.js`
- [E2E Tests](https://github.com/yuhonas/free-exercise-db/blob/main/site/cypress/e2e/searching_and_paginating.cy.js): cypress · Browser-level coverage for searching and pagination flows. · `site/cypress/e2e/searching_and_paginating.cy.js`
- [Site Config](https://github.com/yuhonas/free-exercise-db/blob/main/site/vite.config.js): build config · Frontend toolchain and bundler configuration for Vite-based static hosting. · `site/vite.config.js`
- [Package Manifest](https://github.com/yuhonas/free-exercise-db/blob/main/site/package.json): package config · Frontend package and script definitions for the Vue app. · `site/package.json`

### Automation

Build, validation, and CI release orchestration.

- [Makefile](https://github.com/yuhonas/free-exercise-db/tree/main/Makefile): build orchestrator · Runs schema linting, dataset aggregation, and export tasks. · `Makefile`
- [CI Pipeline](https://github.com/yuhonas/free-exercise-db/blob/main/.github/workflows/ci.yaml): github actions · Automates linting, tests, and site deployment. · `.github/workflows/ci.yaml`

## Connections

- 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.
