@lernapps/app-templates 0.0.1 → 0.1.1

package/docs/arc42/02-constraints.arc42.md

@@ -0,0 +1,228 @@
+# Architecture Constraints
+
+<!--
+Arc42 chapter 2. Document every requirement that limits your freedom of design and
+implementation decisions. Constraints must always be dealt with — though some may be
+negotiable. Architects need to know exactly where they have freedom and where they must adhere.
+
+Constraints come from three sources:
+- technical       — technology standards, infrastructure mandates, platform restrictions
+- organizational  — legal requirements, compliance rules, budget limits, governance policies
+- convention      — agreed coding standards, naming rules, documentation or versioning guidelines
+
+For each constraint, write a ## section with a prose paragraph explaining the constraint,
+its origin, and its architectural impact, followed by a DSL block.
+
+The `source` field names the origin — a legal document, client contract, governance policy,
+or internal standard. Omit it if the origin is an internal assumption.
+
+See https://docs.arc42.org/section-2/ for further guidance.
+
+Example:
+
+## Personal Data Must Remain in the EU
+
+All personally identifiable information must be stored and processed within the EU.
+This limits which cloud regions, caching layers, and third-party SaaS tools are usable.
+Origin: GDPR Art. 44, confirmed by legal review 2025-03-01.
+
+```arc42
+:::constraint
+id: con-data-residency
+title: Personal Data Must Remain in the EU
+category: organizational
+source: GDPR Art. 44 / Legal review 2025-03-01
+:::
+```
+-->
+
+## Frontend Only, Static Pages
+
+An app is static files served from its repo's GitHub Pages at `lernapps.net/<repo>/`; it has no server of its own
+and shares no code at runtime with other apps. All logic runs in the learner's browser, and the build renders every
+page ahead of time.
+
+```arc42
+:::constraint
+id: con-frontend-only
+title: Frontend only, static pages
+category: organizational
+source: ORGANIZATION.md "What every site shares" and "Apps and the app overview"; decided sketch, step 12
+:::
+```
+
+## No Request Before a Click, No Tracking
+
+No page sets a cookie, tracks, or requests anything from another server before the learner clicks; the privacy
+notice of lernapps.net states this for every app. So fonts, libraries and data are bundled, and anything that leaves
+the device (a tutor handoff, a link) waits for a click. `lernapps check` verifies it on the built app.
+
+```arc42
+:::constraint
+id: con-no-request-before-click
+title: No request before a click, no tracking
+category: organizational
+source: ORGANIZATION.md "Every page, in every repo"; lernapps check rules no-request-before-click and no-tracking
+:::
+```
+
+## TypeScript on vite-plus, Vue for Components
+
+Every app is TypeScript built with vite-plus and the shared preset of `@lernapps/tooling`. Where an app has
+components of its own (an explainer's components, an interactive app's UI), they are Vue single-file components, so
+one set of component rules, lint rules and `vue-tsc` holds for every app; the quiz has none.
+
+```arc42
+:::constraint
+id: con-vue-typescript
+title: TypeScript on vite-plus, Vue for components
+category: technical
+source: Decided sketch, step 12, section 2; owner, 2026-10-16, conversation (Vue is fixed); skill lernapps-app rule strict-typescript
+:::
+```
+
+## Component Rules
+
+The app's components and the modules they import are checked on the SFC compiler's output at build: no network
+APIs, no `eval`, `new Function`, `innerHTML` or `v-html`, imports only from Vue, the runtime, the tooling's storage,
+i18n and a11y helpers and the app's own files (an interactive app's also from the libraries in its dependencies,
+never from a URL), and browser globals only once mounted, because the build renders without a browser.
+
+```arc42
+:::constraint
+id: con-component-rules
+title: Component rules checked at build
+category: technical
+source: Decided sketch, step 12, section 2; runtime/explainer/components.ts; runtime/interactive/plugin.ts
+:::
+```
+
+## The Runtime Is Not Changed by the App
+
+The frame and the archetype's runtime come from `@lernapps/app-templates`, and the app does not change them; the app
+writes only what its archetype allows (the quiz its question bank, the explainer its content, the interactive app its
+core, UI, data, playthroughs, messages and description). Changes to the runtime reach the app as dependency updates.
+
+```arc42
+:::constraint
+id: con-runtime-unchanged
+title: The app does not change the runtime
+category: convention
+source: Decided sketch, step 12, sections 3 and 4; skill rules quiz-only-data, explainer-only-content, keep-the-preset
+:::
+```
+
+## State Only on the Device
+
+What an app remembers stays in the learner's browser, under its own key prefix, through the tooling's storage
+wrapper; there are no accounts and no server state. The learner's settings that hold for every app or for every app
+of an archetype are kept under `lernapps:settings:` and `lernapps:settings:<archetype>:`, which every app, or every
+app of that archetype, may read and write; an app's own setting wins. Storage may be blocked or full at any time, so the app must keep
+working and simply remember nothing.
+
+```arc42
+:::constraint
+id: con-state-on-device
+title: State only on the device, through the storage wrapper
+category: technical
+source: Decided sketch, step 12, section 4; @lernapps/tooling archetypes/shared/storage.ts; lint rule storage-through-wrapper
+:::
+```
+
+## Small Storage with a Quota
+
+All apps share the 5 MiB of `localStorage` of the one origin lernapps.net, so each app may keep at most 100 kB and
+`save` refuses beyond it. The quota is decided but not built yet: the wrapper has no limit today.
+
+```arc42
+:::constraint
+id: con-storage-quota
+title: Small storage with a quota of 100 kB per app
+category: technical
+source: Owner, 2026-10-16, conversation; decided sketch, step 12, section 3
+:::
+```
+
+## Accessibility: Platform Rule, App Default
+
+WCAG 2.1 AA and use at 360 px are rules for the platform's own pages; an app follows them by default and may
+deviate where its idea needs it, for example a typing game against the clock, declaring what it does not offer in its
+entry. Pages the runtime renders from the creator's data meet both in any case. Low stimulation is advice only. The
+warnings for an app with declared limits are not built yet: `accessible` and `usable-at-360px` are errors for every
+app today.
+
+```arc42
+:::constraint
+id: con-accessibility-default
+title: WCAG 2.1 AA and 360 px by default, deviations declared
+category: organizational
+source: ORGANIZATION.md "Every page, in every repo"; decided sketch, step 12, section 5; owner, 2026-10-16, conversation
+:::
+```
+
+## German for Learners, English for Infrastructure
+
+Text for learners, teachers and parents is German (further languages may be declared); shared infrastructure,
+identifiers, schemas and developer docs are English, and so is this architecture. Inside its own repo, an app's author
+decides the language of names.
+
+```arc42
+:::constraint
+id: con-language
+title: German for learner text, English for infrastructure
+category: convention
+source: ORGANIZATION.md "Language"; owner, 2026-10-16, conversation (architecture in English)
+:::
+```
+
+## Bundled Libraries with Accepted Licences
+
+A library an app uses is bundled, never loaded from a CDN, and its licence and those of its dependencies must be on
+the allowlist of the `dependency-licence` check (MIT, Apache-2.0, BSD and similar). The app's own repo is MIT;
+third-party content keeps its licence and is named next to it.
+
+```arc42
+:::ignore H006 an organisation rule that lernapps check verifies (dependency-licence); no architecture decision responds to it
+:::
+:::constraint
+id: con-bundled-licences
+title: Bundled libraries under accepted licences
+category: organizational
+source: Decided sketch, step 12, section 2; ORGANIZATION.md "License"; lernapps check rule dependency-licence
+:::
+```
+
+## Imprint and Privacy Notice
+
+Every page links to the imprint and the privacy notice of lernapps.net; the runtime renders both links in the footer
+of its pages.
+
+```arc42
+:::ignore H006 an organisation rule the runtime meets in the footer of its pages; no architecture decision responds to it
+:::
+:::constraint
+id: con-imprint-privacy
+title: Links to imprint and privacy notice
+category: organizational
+source: ORGANIZATION.md "Every page, in every repo"; decided sketch, step 12, section 3
+:::
+```
+
+## Architecture Kept Current
+
+The architecture lives in the arc42 DSL: this generic part at the root of `lernapps/app-templates` and one extension
+per archetype in its template folder. An app gets both in its `docs/arc42/`; only an interactive app, whose code is
+free, adds a part of its own; the creator's assistant updates and validates it with every change, without a
+checkpoint with the creator. `arc42 diff --staged --strict` before a commit
+and `arc42 validate` in `lernapps check` are decided but not wired into the app's hooks and check yet; the copying of
+the architecture into an app is not built yet either. In `lernapps/app-templates` itself, `scripts/arc42.ts` validates
+the generic part with each extension strictly, in the pre-commit hook and in CI.
+
+```arc42
+:::constraint
+id: con-architecture-current
+title: Architecture in docs/arc42, kept current
+category: convention
+source: Decided sketch, step 12, section 4; owner, 2026-10-16 (generic architecture plus one extension per archetype)
+:::
+```

package/docs/arc42/03-system-context.arc42.md

@@ -0,0 +1,118 @@
+# System Scope and Context
+
+The system is one lernapps app of any archetype: the frame runtime, the tooling helpers and the archetype part,
+built into static pages. Outside it are the people who use or write the app and the few systems it meets: the host
+that serves it, the app overview that links to it and, where an archetype has the optional tutor, the learner's own
+assistant (in that archetype's extension). Each actor requires an interface of chapter 5: the pages or, for the
+creator's assistant, what the archetype lets it write, the check command and the skills.
+
+## Context diagram
+
+The creator's assistant writes the archetype's content and follows the skills; every other actor meets the built
+pages at the boundary.
+
+```arc42
+:::diagram
+id: system-context
+view: context
+notation: mermaid
+:::
+```
+
+```mermaid
+flowchart LR
+    actor-learner["Learner"]
+    actor-teacher-parent["Teachers and parents"]
+    actor-creator-assistant["Creator and their AI assistant"]
+    actor-github-pages["GitHub Pages"]
+    actor-app-overview["lernapps.net app overview"]
+    subgraph system["lernapps app"]
+        bb-render["Page rendering (the archetype's)"]
+        bb-tooling["Tooling helpers"]
+        bb-skills["Skills"]
+    end
+    actor-learner -->|"if-pages: reads and learns on the pages"| system
+    actor-teacher-parent -->|"if-pages: reads the pages"| system
+    actor-creator-assistant -->|"if-archetype-content, if-lernapps-check, if-skills: writes, checks, follows the skills"| system
+    actor-github-pages -->|"if-pages: serves the built pages"| system
+    actor-app-overview -->|"if-pages: links to the pages and deep links"| system
+```
+
+## Learner
+
+Adults and students, often in German schools, who learn in the browser, with keyboard, pointer, touch or other
+input, without an account;
+what the app remembers stays on their device.
+
+```arc42
+:::actor
+id: actor-learner
+title: Learner
+type: person
+description: Reads the pages and learns on them in the browser, without an account
+requires: if-pages
+:::
+```
+
+## Teachers and parents
+
+They read the pages and the app's entry to see what the app teaches and whether it may be used; they need the pages
+in German.
+
+```arc42
+:::actor
+id: actor-teacher-parent
+title: Teachers and parents
+type: person
+description: Read the pages to see what the app teaches and what it does not offer
+requires: if-pages
+:::
+```
+
+## Creator and their AI assistant
+
+The creator's AI assistant writes what the archetype lets it write, runs the checks and follows the skill
+`lernapps-app` and its archetype's skill (each extension names it); the creator decides and lists the app.
+
+OPEN: No interface is modelled for `vp build` and `vp dev`, which the assistant also runs; should there be one?
+
+```arc42
+:::actor
+id: actor-creator-assistant
+title: Creator and their AI assistant
+type: system
+description: Writes the archetype's content, runs lernapps check and follows the skills
+requires: if-archetype-content, if-lernapps-check, if-skills
+:::
+```
+
+## GitHub Pages
+
+The app is static files published from its repo's `gh-pages` branch to `lernapps.net/<repo>/`: the pages the build
+rendered and the bundle; there is no server of the app's own, and pull requests get a preview.
+
+```arc42
+:::actor
+id: actor-github-pages
+title: GitHub Pages
+type: system
+description: Serves the built pages and bundle of the app at lernapps.net/<repo>/
+requires: if-pages
+:::
+```
+
+## lernapps.net app overview
+
+The app connects to the platform only through its entry in the app overview, which links to the app's pages and,
+through its topics, to its deep links; `entry-links-resolve` checks that these links answer. The entry's fact sheet
+also states the app's size (not built yet).
+
+```arc42
+:::actor
+id: actor-app-overview
+title: lernapps.net app overview
+type: system
+description: Lists the app with one entry whose URL and topic links point to its pages and deep links
+requires: if-pages
+:::
+```

package/docs/arc42/04-solution-strategy.arc42.md

@@ -0,0 +1,47 @@
+# Solution Strategy
+
+Opinionated where it makes the rules checkable, free where the learning happens: a fixed frame (the runtime of
+`@lernapps/app-templates` and the tooling helpers) that the app does not change, and inside it the archetype's part.
+The quiz and the explainer are generic: the runtime ships their whole part and the creator only feeds it with data.
+An interactive app's part is free code against a few small contracts. The build, the end-to-end tests and
+`lernapps check` verify all three.
+
+```arc42
+:::solution-strategy
+id: strategy-fixed-frame-free-app
+title: Fixed, checked frame around the archetype's part
+addresses: qg-privacy, qg-checkable, qg-accessibility, qg-understandable
+:::
+```
+
+| Quality goal | Approach |
+| --- | --- |
+| `qg-privacy` | Static pages without a server; libraries, fonts and data bundled; state only through the storage wrapper on the device; component rules and lint rules forbid network APIs; `lernapps check` sees no request before a click. |
+| `qg-checkable` | What the creator writes is data under a JSON Schema or code under a contract; the build validates it and fails with one line per problem; each archetype's end-to-end tests derive their cases from it; seeds in the address make random parts replayable. |
+| `qg-accessibility` | The runtime renders the pages and brings the announcer and focus helpers; axe and 360 px are checked on the built app; an app that cannot meet them declares its limits in its entry. |
+| `qg-understandable` | One generic architecture and one extension per archetype, English and minimal; fixed folders and contracts, so an interactive app's own blocks go below its extension's. |
+
+## System decomposition
+
+Three generic roots, the shared runtime (`bb-runtime`: page trees, languages, examples check, Vue at build), the
+tooling helpers (`bb-tooling`: preset, lint rules, `lernapps check`, storage, i18n, a11y) and the skills the app
+commits (`bb-skills`); each
+archetype's extension adds its runtime (`bb-archetype-runtime`, which builds the pages, runs the build checks, starts
+the archetype's code in the browser in `bb-shell` and brings the end-to-end tests) and the parts the creator writes,
+each a root of its own, so that an interactive app can add its own blocks below them.
+
+## Technology and communication approach
+
+TypeScript on vite-plus, and Vue for an app's own components (`con-vue-typescript`), so one set of component rules
+holds. Every page is rendered at build and served statically (`con-frontend-only`); deep links and seeds live in the
+address, so the app overview can link to them. The app talks to nothing outside the browser; anything that would leave
+the device, such as the optional tutor handoff to the learner's own assistant, waits for a click
+(`con-no-request-before-click`); no model runs in the browser.
+
+## Operational approach
+
+Rules are checked by machine, not by review: the build fails on content or code that breaks the archetype's schema or
+contract; the end-to-end tests and `lernapps check` run before a push. The app's size is not limited; it is stated in
+the app's catalog entry. The runtime and tooling reach the app as dependency updates, never as edits
+(`con-runtime-unchanged`). The architecture is kept current in `docs/arc42/` (`con-architecture-current`); its
+pre-commit diff and validation are decided but not built yet.