# bryllim/workout-guide architecture

> Architecture diagram of the GitHub repository bryllim/workout-guide, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bryllim/workout-guide
- Repository: https://github.com/bryllim/workout-guide

## Overview

#### Purpose and principal workflow
Workout Guide is both a framework-neutral exercise catalog and asset package, and a static website for browsing its exercise gallery and guide. The principal website workflow starts when a **gallery visitor** opens the published site and browses the gallery or an exercise detail page. Separately, an **npm package consumer** imports the library to look up or search exercises and build asset URLs. Maintainers can regenerate the catalog and artwork from a compatible exercise-source export.

#### Components

##### Catalog and package
- **Exercise lookup and search API** — `packages/workout-guide/src/index.ts`: Exposes the typed exercise collection, ID/slug lookup, normalized text search with filters, and CDN-based asset URL generation; it loads the canonical manifest.
- **Exercise and frame types** — `packages/workout-guide/src/types.ts`: Defines the catalog metadata, three-frame exercise shape, search filters, asset URL options, and attribution types.
- **Canonical catalog and artwork** — `packages/workout-guide/manifest.json`: Stores the structured exercise records and frame paths; the README documents 302 exercises and 906 SVG frames in the package assets.

##### Static website
- **Gallery, detail pages, and guide** — `apps/site/src/pages`: Contains the home, exercise listing, per-exercise detail, and guide pages; the README documents these as the static gallery and integration guide.
- **Site asset URL helper** — `apps/site/src/lib/paths.ts`: Builds base-aware URLs for locally served exercise frames and uses the package’s frame type.
- **Static site configuration** — `apps/site/astro.config.mjs`: Configures Astro’s static output, published site/base paths, trailing slashes, and sitemap integration.

##### Catalog and asset generation
- **Catalog import pipeline** — `scripts/import-catalog.mjs`: Reads definitions and pose sources from a compatible export, copies or rasterizes frame sources, creates SVGs, and writes the package manifest and license files.
- **PNG-to-SVG vectorizer** — `scripts/lib/vectorize-png.mjs`: Uses image processing and tracing libraries to vectorize transparent PNG artwork and optimize the resulting SVG.
- **Website asset synchronization** — `scripts/sync-site-assets.mjs`: Copies package artwork into the site’s public frame directory and generates social-preview artwork from featured exercises.

##### External callers
- **Gallery visitor** — `null` (external): Opens the published static website to browse exercise information and illustrations.
- **npm package consumer** — `null` (external): Imports the published package API and uses its catalog and asset URL functions.

#### Relationships
- Gallery visitor -> Gallery, detail pages, and guide: opens the published static site; evidence: `README.md`.
- npm package consumer -> Exercise lookup and search API: imports the documented package API; evidence: `README.md`.
- Exercise lookup and search API -> Canonical catalog and artwork: imports the manifest and builds its in-memory ID/slug maps from it; evidence: `packages/workout-guide/src/index.ts`.
- Exercise lookup and search API -> Exercise and frame types: imports and re-exports the package’s type definitions; evidence: `packages/workout-guide/src/index.ts`.
- Site asset URL helper -> Exercise and frame types: imports the frame type; evidence: `apps/site/src/lib/paths.ts`.
- Catalog import pipeline -> PNG-to-SVG vectorizer: calls `vectorizePng` for each generated frame; evidence: `scripts/import-catalog.mjs`.
- Catalog import pipeline -> Canonical catalog and artwork: writes the manifest and generated assets into the package; evidence: `scripts/import-catalog.mjs`.
- Website asset synchronization -> Canonical catalog and artwork: copies package assets and reads the manifest to generate featured artwork; evidence: `scripts/sync-site-assets.mjs`.
- Website asset synchronization -> Gallery, detail pages, and guide: writes frame files into the site’s public directory for local serving; evidence: `scripts/sync-site-assets.mjs`.

#### Coverage limits
The page and component source excerpts were not provided, so the detailed rendering flow, page-to-package data calls, and whether gallery frames are served locally or via package-generated URLs cannot be established. The README describes a static gallery and guide; the explicit synchronization script establishes a local asset-copy path, but not its invocation timing.

Main entry points: [`packages/workout-guide/src/index.ts`](https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/src/index.ts) (Exercise lookup and search API), [`packages/workout-guide/manifest.json`](https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/manifest.json) (Canonical catalog and artwork), [`scripts/import-catalog.mjs`](https://github.com/bryllim/workout-guide/blob/main/scripts/import-catalog.mjs) (Catalog import pipeline), [`scripts/sync-site-assets.mjs`](https://github.com/bryllim/workout-guide/blob/main/scripts/sync-site-assets.mjs) (Website asset synchronization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Catalog and package"]
  node_exercise_api["Exercise lookup and search API<br/>Package API"]
  node_exercise_types["Exercise and frame types<br/>Type definitions"]
  node_catalog_manifest["Canonical catalog and artwork<br/>Manifest and assets"]
end

subgraph group_website["Static website"]
  node_site_pages["Gallery, detail pages, and guide<br/>Static pages"]
  node_site_asset_helper["Site asset URL helper<br/>[paths.ts]"]
end

subgraph group_generation["Catalog and asset generation"]
  node_catalog_import["Catalog import pipeline<br/>Generation script"]
  node_png_vectorizer["PNG-to-SVG vectorizer<br/>Image processing"]
  node_site_asset_sync["Website asset synchronization<br/>Generation script"]
end

node_gallery_visitor(("Gallery visitor<br/>External actor"))
node_package_consumer(("npm package consumer<br/>External actor"))

node_gallery_visitor -->|"opens"| node_site_pages
node_package_consumer -->|"imports"| node_exercise_api
node_exercise_api -->|"loads"| node_catalog_manifest
node_exercise_api -->|"imports and re-exports"| node_exercise_types
node_site_asset_helper -->|"imports"| node_exercise_types
node_catalog_import -->|"calls"| node_png_vectorizer
node_catalog_import -->|"writes"| node_catalog_manifest
node_site_asset_sync -->|"copies and reads"| node_catalog_manifest
node_site_asset_sync -->|"writes frame files"| node_site_pages

click node_exercise_api "https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/src/index.ts"
click node_exercise_types "https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/src/types.ts"
click node_catalog_manifest "https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/manifest.json"
click node_site_pages "https://github.com/bryllim/workout-guide/tree/main/apps/site/src/pages"
click node_site_asset_helper "https://github.com/bryllim/workout-guide/blob/main/apps/site/src/lib/paths.ts"
click node_catalog_import "https://github.com/bryllim/workout-guide/blob/main/scripts/import-catalog.mjs"
click node_png_vectorizer "https://github.com/bryllim/workout-guide/blob/main/scripts/lib/vectorize-png.mjs"
click node_site_asset_sync "https://github.com/bryllim/workout-guide/blob/main/scripts/sync-site-assets.mjs"

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_exercise_api,node_exercise_types,node_catalog_manifest toneBlue
class node_site_pages,node_site_asset_helper toneAmber
class node_catalog_import,node_png_vectorizer,node_site_asset_sync toneMint
class node_gallery_visitor,node_package_consumer toneIndigo
```

## Components

### Catalog and package

- [Exercise lookup and search API](https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/src/index.ts): Package API · `packages/workout-guide/src/index.ts`
- [Exercise and frame types](https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/src/types.ts): Type definitions · `packages/workout-guide/src/types.ts`
- [Canonical catalog and artwork](https://github.com/bryllim/workout-guide/blob/main/packages/workout-guide/manifest.json): Manifest and assets · `packages/workout-guide/manifest.json`

### Static website

- [Gallery, detail pages, and guide](https://github.com/bryllim/workout-guide/tree/main/apps/site/src/pages): Static pages · `apps/site/src/pages`
- [Site asset URL helper](https://github.com/bryllim/workout-guide/blob/main/apps/site/src/lib/paths.ts): URL helper · `apps/site/src/lib/paths.ts`

### Catalog and asset generation

- [Catalog import pipeline](https://github.com/bryllim/workout-guide/blob/main/scripts/import-catalog.mjs): Generation script · `scripts/import-catalog.mjs`
- [PNG-to-SVG vectorizer](https://github.com/bryllim/workout-guide/blob/main/scripts/lib/vectorize-png.mjs): Image processing · `scripts/lib/vectorize-png.mjs`
- [Website asset synchronization](https://github.com/bryllim/workout-guide/blob/main/scripts/sync-site-assets.mjs): Generation script · `scripts/sync-site-assets.mjs`

### Other components

- **Gallery visitor**: External actor
- **npm package consumer**: External actor

## Connections

- Gallery visitor → Gallery, detail pages, and guide: opens (evidence: `README.md`)
- npm package consumer → Exercise lookup and search API: imports (evidence: `README.md`)
- Exercise lookup and search API → Canonical catalog and artwork: loads (evidence: `packages/workout-guide/src/index.ts`)
- Exercise lookup and search API → Exercise and frame types: imports and re-exports (evidence: `packages/workout-guide/src/index.ts`)
- Site asset URL helper → Exercise and frame types: imports (evidence: `apps/site/src/lib/paths.ts`)
- Catalog import pipeline → PNG-to-SVG vectorizer: calls (evidence: `scripts/import-catalog.mjs`)
- Catalog import pipeline → Canonical catalog and artwork: writes (evidence: `scripts/import-catalog.mjs`)
- Website asset synchronization → Canonical catalog and artwork: copies and reads (evidence: `scripts/sync-site-assets.mjs`)
- Website asset synchronization → Gallery, detail pages, and guide: writes frame files (evidence: `scripts/sync-site-assets.mjs`)
