Skip to content

prd.md

Latest commit

 

History

History
258 lines (179 loc) · 12.7 KB

prd.md

File metadata and controls

258 lines (179 loc) · 12.7 KB
Raw

APHGames Web — Product / architecture description

This document describes how aphgames-web (package name aphgames-web) is structured, what it ships at runtime, and how it connects to external repositories and services. It is aimed at engineers and coding agents onboarding onto the project.

1. Purpose and scope

The site is a static documentation and teaching hub for APHGames: learning materials (Markdown/MDX), embedded interactive examples (canvas games/demos), Reveal.js HTML slides, course pointers, a student project gallery, and ancillary pages (e.g. Czech-only curated links). There is no application server in this repo; production is static files (typically hosted behind a CDN or static host). Build-time Node scripts fetch large binary artifacts; the running site only needs those files under static/.

2. Technology stack

Area Choice
Framework Docusaurus 2.0.0-beta.17 (@docusaurus/core, @docusaurus/preset-classic)
UI React 17, MDX v1 (@mdx-js/react)
Styling Global SCSS (docusaurus-plugin-sass, src/css/global.scss) + CSS modules for pages
Search Vendored @cmfcmf/docusaurus-search-local under plugins/docusaurus-search-local (Lunr-based local search)
TypeScript Used for authoring src/ and some docs; Docusaurus does not rely on tsc for its main build (see tsconfig.json comment)
Tooling ESLint (Airbnb), fork-ts-checker-webpack-plugin in dev

Important: Locale and site URL are chosen at config load time from the CLI (--locale), not from Docusaurus’s multi-locale runtime. Each production language is effectively a separate build (see §5).

3. High-level architecture

flowchart TB
  subgraph build [Build time Node]
    DC[Docusaurus webpack build]
    DL[scripts/download_data.js]
    WEB[web.config.js]
    WEB --> DC
    WEB --> DL
    DL -->|ZIP| EX[static/examples]
    DL -->|ZIP| SL[static/slides]
    DL -->|JSON| TI[static/tiscali.json]
  end
  subgraph repos [External GitHub releases]
    ER[APHGames/examples release.zip]
    SR[APHGames/slides release.zip]
    TG[support tiscali JSON]
    ER --> DL
    SR --> DL
    TG --> DL
  end
  subgraph output [Static site output]
    HTML[HTML / JS bundles]
    HTML --- EX
    HTML --- SL
  end
  DC --> HTML
  subgraph runtime [Browser]
    DOC[Docs MDX pages]
    CAN[APHCanvas + window.APH examples bundle]
    SLV[Reveal slides as static HTML under /slides/]
    GAL[Gallery links to gallery.aphgames.io]
    DOC --> CAN
    DOC --> SLV
  end
  HTML --> runtime
Loading
  • Docusaurus turns docs/, blog/, src/pages/, and theme overrides into a SPA + static assets.
  • download_data pulls versioned release ZIPs for examples and slides (URLs and versions live in web.config.js), plus a filtered JSON dump for the Czech “artifacts” page.
  • Examples ship as a prebuilt JS bundle consumed in the browser (static/examples/); they are not compiled from this repo’s TypeScript sources.
  • Slides ship as static Reveal.js HTML, icons, and slides-info.json; listing UIs read that JSON and link to /slides/*.html.

4. Repository layout (essentials)

Path Role
docusaurus.config.js Main Docusaurus config; merges web.config.js into customFields; wires plugins, navbar, i18n single-locale mode, docs sidebar generator hook
web.config.js Domains, GitHub URLs, examples / slides release coordinates, gallery_url, tiscali_url
sidebars.js Single autogenerated sidebar: tutorialSidebar → docs/learning
docs/ Primary Markdown/MDX content (learning/, courses/, brand.md, …)
i18n/cs/, i18n/en/ Per-locale strings (code.json, news.json), translated doc copies under docusaurus-plugin-content-docs/current/, and locale-specific React (components/About.tsx)
src/pages/ Custom pages: home (index.tsx), gallery.tsx, Czech artifacts.tsx
src/APHCanvas.tsx Bridge from MDX to the examples bundle (window.APH[name])
src/theme/ Swizzled theme pieces (DocPaginator, NavbarItem/NavbarNavLink)
src/css/, src/components/ Shared styles and small UI helpers
src/internals/ Data modules (gallery-data.ts, resources-data.ts, Prism themes, …)
static/ Images and other static assets; examples/, slides/, tiscali.json are gitignored and produced by download_data
plugins/docusaurus-search-local/ Local search plugin copy
scripts/download_data.js Downloads and extracts external ZIPs + JSON

5. Internationalization (Czech / English)

5.1 Two sites, two builds

  • web.config.js defines urls.cs and urls.en (e.g. aphgames.cz vs aphgames.io).
  • docusaurus.config.js reads process.argv for --locale and sets:
    • i18n.defaultLocale and i18n.locales to only that locale (the other language is on another domain, not bundled as a second locale in one artifact).
  • NPM scripts mirror this: start_cs / build_cs / deploy_cs vs start_en / build_en / deploy_en.

5.2 Translations

  • Navbar labels, keywords, and many UI strings come from i18n/<locale>/code.json.
  • Home page news is loaded from i18n/<locale>/news.json.
  • The About block on the home page is loaded via react-loadable from i18n/<locale>/components/About.tsx (so copy/layout can diverge per language).

5.3 Docs per locale and “Czech-only” pages

  • Canonical English docs live under docs/.
  • Czech overrides live under i18n/cs/docusaurus-plugin-content-docs/current/ (mirrored paths).
  • Per-doc language gating: sidebarItemsGenerator in docusaurus.config.js filters out docs whose front matter includes exclude_cs or exclude_en for the active build. Examples in tree: docs/courses/aph.md and docs/learning/03-aph-requirements.md use exclude_en: true (Czech-oriented course material).

5.4 Czech-only UI

  • Navbar injects Artifacts and a YouTube icon link only when currentLocale === 'cs' (docusaurus.config.js).
  • src/pages/artifacts.tsx is a Czech-facing page backed by static/tiscali.json.

6. Content model (docs)

  • Sidebar: sidebars.js autogenerates from folder docs/learning only. Other doc routes (e.g. docs/courses/, docs/brand.md) are reached via explicit links/nav, not the main tutorial sidebar.
  • MDX: Docs can import React/TSX modules (e.g. @site/docs/learning/lectures.tsx, @site/src/APHCanvas.tsx).
  • Intro + slides index: docs/learning/01-intro.md embeds <Lectures /> from docs/learning/lectures.tsx, which reads static/slides/slides-info.json and groups slides for the current locale, excluding course-tagged rows (!sl.course).
  • Course slides: docs/courses/aph.md embeds docs/courses/aph_lectures.tsx, filtering slides-info.json for locale match and course === 'APH', with optional locked tiles (locked === 'true' string from JSON).

7. External project: engine examples (GitHub APHGames/examples)

7.1 What this repo contains

  • Not the TypeScript sources. At build/dev time, npm run download_data downloads release.zip from the configured GitHub releases asset and extracts it to static/examples/ (ignored by git).

7.2 How the site loads them

  • src/APHCanvas.tsx runs only in the browser (typeof window !== 'undefined').
  • On first use it sets window.BASE_URL = '../../../../examples' and window.parcelRequire = null, then require('@site/static/examples/examples') to load the bundle.
  • It instantiates new window.APH[name](config), calls .init(canvasDomElement), and .destroy() on unmount.
  • MDX pages pass a string name matching an exported example class (e.g. <APHCanvas name={'Tetris'} />).

7.3 Relation to COLF.io / Pixi

  • The examples bundle is built from the examples repository; those demos are described in copy as using COLF.io (minigame layer on PixiJS). This site documents and embeds them; it does not list colf.io as an npm dependency.

7.4 Updating examples

  • Bump examples_version in web.config.js to match a published APHGames/examples release, then rerun npm run download_data.

8. External project: slides (GitHub APHGames/slides, Reveal.js)

8.1 What this repo contains

  • ZIP extracted to static/slides/: HTML decks (e.g. tutorial_….html), slides-info.json, icons/, assets. Path is gitignored.

8.2 How the site surfaces them

  • Direct static URLs: /slides/<file_name>.html with query variants ?print-pdf and ?presentation (Reveal.js conventions).
  • Discovery UI: lectures.tsx (general) and aph_lectures.tsx (APH course) render cards from slides-info.json (group, name, file_name, locale, category, course, locked, …).

8.3 User documentation

  • docs/learning/misc/slides.md documents Reveal keyboard shortcuts and expectations.

8.4 Updating slides

  • Bump slides_version in web.config.js, run npm run download_data.

9. Gallery (/gallery)

  • Implemented in src/pages/gallery.tsx with data from src/internals/gallery-data.ts.
  • Game tiles link to gallery_url from web.config.js (e.g. https://gallery.aphgames.io) with paths like {galleryUrl}/{item.id}/; screenshots are expected at {galleryUrl}/{item.id}/screenshot.jpg.
  • The gallery is not stored in this repo; this project only links out.

10. Search plugin (local fork)

  • Configured in docusaurus.config.js as a file path plugin: plugins/docusaurus-search-local.
  • Indexes docs, blog, and pages; Lunr language is set to ["en", "ru"] where Russian is used as a stand-in tokenizer config for Czech (comment in config: cs not supported out of the box).
  • style: undefined avoids injecting default plugin CSS (custom styling expected elsewhere).

11. Theme and UX customizations

  • DocPaginator: swizzled to render null — prev/next doc footer navigation is disabled site-wide.
  • NavbarNavLink: small customization around Link / active class behavior.
  • Color mode: default dark, switch disabled (comment: avoiding maintaining two diagram themes).
  • Prism: custom light/dark themes under src/internals/prism-aph-*.js.

12. Build, run, deploy

12.1 Typical developer flow

  1. npm install
  2. npm run download_data — downloads examples ZIP, slides ZIP, and tiscali.json (Node 18+ built-in http/https).
  3. npm run start_en or npm run start_cs — Docusaurus dev server.

12.2 Production build

  • npm run build_en / npm run build_cs — outputs under build/ (gitignored).

12.3 Deploy

  • docusaurus deploy scripts exist per locale; hosting is static (see README: aphgames.io / aphgames.cz).

12.4 Lint

  • npm run lint targets src, i18n, docs.

13. Configuration reference (web.config.js)

Field Purpose
urls.cs / urls.en Canonical site origins per language build
owner, org Branding / copyright
github, youtube External links (navbar)
examples_url, examples_version GitHub repo + release tag for examples ZIP
slides_url, slides_version GitHub repo + release tag for slides ZIP
gallery_url Base URL for hosted student games
tiscali_url JSON for artifacts page

All of the above are spread into Docusaurus siteConfig.customFields for use in React (useDocusaurusContext).

14. Risks and upgrade notes (for maintainers)

  • Docusaurus beta.17 is dated; upgrading will touch webpack, MDX, i18n, and the swizzled theme APIs.
  • APHCanvas depends on globals and a Parcel-style examples bundle; changing the examples build output may require edits to BASE_URL, require path, or constructor names.
  • download_data uses SSL_VERIFYPEER: false — acceptable only in a trusted controlled environment; revisit for CI security policy.
  • Course / intro links in navbar point to /docs/learning/intro; the on-disk intro file is docs/learning/01-intro.md — confirm URL aliases or fix links when changing doc slugs.

15. Glossary

Term Meaning here
Examples Prebuilt JS bundle from APHGames/examples, embedded via APHCanvas
Slides Reveal.js HTML decks from APHGames/slides, served as static files
COLF.io External engine/library used by examples and gallery Pixi titles (documented, not vendored as source in this repo)
customFields web.config.js merged into Docusaurus config for runtime access

Document generated to reflect the repository as of the project state when authored. When in doubt, treat docusaurus.config.js, web.config.js, and scripts/download_data.js as the source of truth for wiring and versions.