@lernapps/app-templates 0.0.0-stage → 0.1.0

package/docs/arc42/09-decisions.arc42.md

@@ -0,0 +1,246 @@
+# Architecture Decisions
+
+<!--
+Arc42 chapter 9. Document the significant architecture decisions as Architecture Decision
+Records (ADRs). Capture any choice that was expensive, risky, or that future maintainers
+will wonder about.
+
+Avoid redundancy with section 4 (solution strategy) — refer to it for the highest-level
+choices and use this chapter for detail and rationale.
+
+For each decision, write a ## section with a prose paragraph explaining the context,
+the alternatives considered, and the rationale for the chosen option, followed by a DSL block.
+Document rejected alternatives so future readers understand what was considered.
+
+Status values:
+  proposed   — under discussion, not yet in force
+  accepted   — in force
+  deprecated — no longer recommended but not yet replaced
+  superseded — replaced by another decision
+
+When a new decision replaces an old one, set status: superseded on the old decision
+and add supersedes: <old-id> on the new decision.
+
+The `date` field should be ISO 8601 (YYYY-MM-DD).
+The `addresses` field links to quality goals and constraints this decision responds to.
+
+See https://docs.arc42.org/section-9/ for further guidance.
+
+Example:
+
+## Stateless Token Authentication
+
+The team evaluated session-based (server-side store) and token-based (stateless) authentication.
+Stateless tokens were chosen to avoid a shared session store that would introduce a single point
+of failure and complicate horizontal scaling.
+
+```arc42
+:::decision
+id: dec-auth-stateless
+title: Stateless Token Authentication
+status: accepted
+date: 2025-07-01
+addresses: qg-security, qg-performance
+:::
+```
+
+To supersede a decision, mark the old one and point to it from the new one:
+
+```arc42
+:::decision
+id: dec-auth-old
+title: Session-based Authentication
+status: superseded
+date: 2024-01-15
+:::
+```
+
+```arc42
+:::decision
+id: dec-auth-new
+title: OAuth2 Token Authentication
+status: accepted
+date: 2025-09-01
+supersedes: dec-auth-old
+:::
+```
+-->
+
+The decisions every lernapps app shares. Owner decisions are accepted with their date; decisions the runtime made
+when it was built are accepted because they are in force. Each extension adds its archetype's decisions, and an
+interactive app adds its own below these.
+
+## Generic Architecture with One Extension per Archetype
+
+Quiz, explainer and interactive app stay separate archetypes, but they share their quality goals, so they follow one
+architecture: this generic part with the frame and an abstract archetype part, and one extension per archetype in its
+template folder that adds only its own blocks and decisions and references the generic ids. An app's architecture is
+both together. Rejected: one architecture per archetype, which would repeat the frame three times; one architecture
+with every archetype's detail in it, which no app could take as its own.
+
+```arc42
+:::decision
+id: dec-generic-plus-extensions
+title: A generic architecture plus one extension per archetype
+status: accepted
+date: 2026-10-16
+addresses: qg-understandable, con-architecture-current
+:::
+```
+
+## What Archetypes Share Lives in the Shared Runtime
+
+Quiz, explainer and interactive app use some things alike, the questions first of all: the quiz asks them, the
+explainer's exercises are the same six types; the explainer and the interactive archetype read YAML content, check
+texts and formulas and check the code of Vue components alike. Such a thing lives in `runtime/shared` (the questions in
+`runtime/shared/questions`), and the archetypes build on it: no archetype imports another, and the shared runtime
+imports none. The public paths of the package (`quiz/question`, `quiz/e2e`, ...) stay as thin re-exports, so that an
+app generated from a template keeps building when a module moves. A test (`test/architecture.test.ts`) fails on an
+import against this direction and on a public path without a file or a build entry. Rejected: the explainer importing
+the quiz and the quiz the explainer's figures, which makes two archetypes one; copying the questions into each.
+
+```arc42
+:::decision
+id: dec-shared-runtime-direction
+title: Archetypes build on the shared runtime and never on each other
+status: accepted
+date: 2026-10-20
+addresses: qg-understandable, con-runtime-unchanged
+:::
+```
+
+## Vue Is Fixed for Components
+
+Where an app has components of its own (an explainer's components, an interactive app's UI), they are Vue with
+TypeScript, so that one set of component rules, their build checks on the SFC compiler's output, the lint rules and
+`vue-tsc` hold for every app, with no rules per framework; what a component draws and how stays free. Rejected: a free
+choice of framework.
+
+```arc42
+:::decision
+id: dec-vue-fixed
+title: Vue with TypeScript is fixed for an app's components
+status: accepted
+date: 2026-10-16
+addresses: con-vue-typescript, con-component-rules, qg-checkable
+:::
+```
+
+## Small Storage with a Quota
+
+All apps share the origin's 5 MiB of `localStorage`. The only storage is the tooling's `localStorage` wrapper under the
+app's prefix with a quota of 100 kB per app, and `save` refuses beyond it; the shared origin is accepted as a risk. The
+quota is decided, not built. A second storage (IndexedDB) is left out.
+
+```arc42
+:::decision
+id: dec-small-storage
+title: localStorage through the wrapper with a 100 kB quota
+status: accepted
+date: 2026-10-16
+addresses: con-state-on-device, con-storage-quota, con-frontend-only, qg-privacy, risk-shared-origin-storage, risk-storage-quota-not-built
+:::
+```
+
+## No Size Limit, the Size in the Entry
+
+The app's size is not limited by the frame; it is stated in the app's catalog entry (its fact sheet), and a page may
+show an optional loading indicator while it loads (not built). An archetype may still fix the size of its own parts,
+as the explainer does for each component. Rejected: a size budget for every app, which would keep large interactive
+apps out.
+
+```arc42
+:::decision
+id: dec-no-size-limit
+title: No size limit; the size in the entry, an optional loading indicator
+status: accepted
+date: 2026-10-16
+addresses: qg-accessibility
+:::
+```
+
+## Accessibility by Default, Limits Declared
+
+WCAG 2.1 AA and 360 px are platform rules; an app follows them by default and may deviate where its idea needs it (a
+game against the clock), saying in its entry what it does not offer; then `accessible` and `usable-at-360px`
+become warnings for it. Pages the runtime renders from the creator's data meet both in any case. Low stimulation is
+advice in a skill, not a check. Rejected: the rules as errors for every app, which would exclude real-time games.
+
+```arc42
+:::decision
+id: dec-accessibility-default
+title: Accessibility as default with declared limits
+status: accepted
+date: 2026-10-16
+addresses: con-accessibility-default, qg-accessibility, risk-accessibility-limits-not-built
+:::
+```
+
+## No Settings Now
+
+A settings dialog (time limit off, less motion, sound, pause) is not in scope now; an app that needs one later adds it
+to the frame rather than on its own.
+
+```arc42
+:::ignore H001 a scoping decision of the owner (2026-10-16): it leaves something out and serves no quality goal of its own
+:::
+:::decision
+id: dec-no-settings
+title: No settings dialog for now
+status: accepted
+date: 2026-10-16
+:::
+```
+
+## arc42 in the App, Only for Interactive Apps
+
+Every app gets the generic architecture and its archetype's extension. Only an interactive app, whose code is free,
+writes an architecture part of its own, below its extension's blocks, English and minimal; a quiz or explainer app
+writes none, because its archetype's notation (the question bank, the content schema) fixes its structure. Checked
+is only what arc42 checks itself (`arc42 diff --staged --strict` before a commit, `arc42 validate` in
+`lernapps check`); whether the code keeps to the responsibilities is not checked. Rejected: framework-specific
+conformance checks. Both checks are not wired into an app yet; `lernapps/app-templates` validates each combination of
+the generic part and one extension strictly in its pre-commit hook and in CI (`scripts/arc42.ts`).
+
+```arc42
+:::decision
+id: dec-arc42-in-app
+title: arc42 in the app; only interactive apps add their own part
+status: accepted
+date: 2026-10-16
+addresses: con-architecture-current, con-language, qg-understandable, risk-arc42-checks-not-wired
+:::
+```
+
+## The Skill as the Interface to the Creator's Assistant
+
+The guidance for the creator's assistant is a skill per archetype plus `lernapps-app` for every app: Markdown the
+assistant loads and follows, modelled as the interface `if-skills` of the skills block `bb-skills`. Advice that no check can make (how to write
+a good question, low stimulation) lives there, not in the runtime.
+
+```arc42
+:::decision
+id: dec-skill-interface
+title: Skills as the interface used by the creator's assistant
+status: accepted
+date: 2026-10-16
+addresses: qg-understandable
+:::
+```
+
+## Tutor Variant
+
+The optional tutor is a handoff to the learner's own assistant: after a click, a prompt (copied or passed to a chosen
+provider) and a static tutor page per content page give it the task on the learner's screen. Rejected: a model
+running in the browser. Built for the explainer (its extension models it); not built for the quiz and interactive
+apps.
+
+```arc42
+:::decision
+id: dec-tutor-variant
+title: Tutor as a handoff to the learner's own assistant
+status: accepted
+date: 2026-10-16
+addresses: risk-tutor-not-built, con-no-request-before-click, qg-privacy
+:::
+```

package/docs/arc42/10-quality-requirements.arc42.md

@@ -0,0 +1,155 @@
+# Quality Requirements
+
+The four quality goals every lernapps app shares, in the order of chapter 1, each made testable by scenarios. The
+set and the priorities are the owner's (2026-10-16). Each extension adds its archetype's scenarios; the quiz and the
+explainer add readability without JavaScript as a goal of their own. Scenarios marked "not built yet" describe a
+decided check that does not exist today.
+
+## 10.1 Quality Goals
+
+## Privacy
+
+The app sends nothing anywhere and requests nothing from another server before a click; what it remembers stays on the
+learner's device. The privacy notice of lernapps.net promises this for every app.
+
+```arc42
+:::quality-goal
+id: qg-privacy
+title: Privacy
+priority: high
+:::
+```
+
+## Checkable
+
+The rules an app keeps are verified by machine, at build and in the browser, so that an assistant can change content
+or code and still learn at once when it breaks the frame.
+
+```arc42
+:::quality-goal
+id: qg-checkable
+title: Checkable by machine
+priority: high
+:::
+```
+
+## Accessibility
+
+A default with declared limits: the pages meet WCAG 2.1 AA and work at 360 px, and an app that cannot declares its
+limits in its entry.
+
+```arc42
+:::quality-goal
+id: qg-accessibility
+title: Accessibility by default
+priority: medium
+:::
+```
+
+## Understandable
+
+A reviewer or the creator's agent understands an app's structure from its architecture, the generic part plus its
+archetype's extension, written in English and minimal and kept current with the code.
+
+```arc42
+:::quality-goal
+id: qg-understandable
+title: Understandable from its architecture
+priority: medium
+:::
+```
+
+## 10.2 Quality Scenarios
+
+## No request before a click
+
+`lernapps check` visits every page of the built app, blocks and records requests to other hosts while it loads.
+
+```arc42
+:::quality-scenario
+id: qs-no-request-before-click
+title: No request to another host before a click
+quality: qg-privacy
+stimulus: lernapps check loads every page of the built app without clicking
+response: Requests to other hosts are recorded; each one is an error of no-request-before-click
+metric: 0 requests to another origin on every page before a click
+:::
+```
+
+## State stays on the device
+
+An app's code that uses the browser's storage directly, sets a cookie or calls a network API is reported by the lint
+rules on commit and by the component rules at build.
+
+```arc42
+:::quality-scenario
+id: qs-state-on-device
+title: Remembered state stays on the device
+quality: qg-privacy
+stimulus: A component stores progress with localStorage directly or sends it with fetch
+response: storage-through-wrapper or vue-component-no-network reports it; the build's component rules fail on the network call
+metric: 0 findings; all storage goes through createStorage under the prefix lernapps:<app>:
+:::
+```
+
+## Broken content fails the build
+
+What the creator wrote is validated against the archetype's schema or contract before any page is written.
+
+```arc42
+:::quality-scenario
+id: qs-build-fails-per-line
+title: A broken question bank, content or description fails the build
+quality: qg-checkable
+stimulus: The creator's assistant writes data that breaks the archetype's schema or a rule the schema cannot say
+response: The build fails with one line per problem naming the file, the place and what to change
+metric: 0 pages written from invalid data; every problem named in one line
+:::
+```
+
+## No WCAG violation found by axe
+
+`lernapps check` runs axe-core for WCAG 2.1 A and AA on each page it visits. For an app whose entry declares its limits
+the finding should become a warning; that is not built yet, so it is an error for every app today.
+
+```arc42
+:::quality-scenario
+id: qs-axe-clean
+title: axe finds no WCAG 2.1 A or AA violation
+quality: qg-accessibility
+stimulus: lernapps check visits the pages of the built app
+response: Each axe violation is reported as an error of accessible, naming the page and element
+metric: 0 axe violations of WCAG 2.1 A or AA on every page
+:::
+```
+
+## Usable at 360 px
+
+`lernapps check` measures each page in a 360 px wide window.
+
+```arc42
+:::quality-scenario
+id: qs-usable-at-360px
+title: No page wider than 360 px
+quality: qg-accessibility
+stimulus: lernapps check opens every page of the built app in a 360 px wide window
+response: A wider page is an error of usable-at-360px, naming the elements that are too wide
+metric: Page width at most 360 px on every page
+:::
+```
+
+## Code no block claims
+
+Not built yet (decided sketch, step 12, section 4): before a commit, `arc42 diff --staged --strict` compares the staged
+code with the architecture; it matters for interactive apps, whose code is free.
+
+```arc42
+:::quality-scenario
+id: qs-architecture-current
+title: New code without a building block fails the commit
+quality: qg-understandable
+stimulus: An assistant stages new code under src/ that no building block claims, or a block changed without its prose
+response: arc42 diff --staged --strict fails the commit and names the unclaimed path or the block
+metric: 0 unclaimed paths under src/ at every commit, in about 0.2 s
+:::
+```

package/docs/arc42/11-risks.arc42.md

@@ -0,0 +1,113 @@
+# Risks and Technical Debt
+
+<!--
+Arc42 chapter 11. Document known risks and areas of technical debt ordered by priority.
+Risk management is about making technical risks visible to the people who need to act on them.
+
+A risk is a known threat whose severity has not yet been fully mitigated.
+Technical debt is a shortcut taken consciously or accidentally whose cost will have to be
+paid later. Both belong here.
+
+For each risk or debt item, write a ## section with a prose paragraph describing the risk,
+its cause, its potential impact, and the current situation, followed by a DSL block.
+
+The `mitigation` field describes the planned or accepted response. Even "accepted without
+action until X" is a valid mitigation — it shows the team made a conscious choice.
+
+Order entries by priority — highest risk first.
+
+See https://docs.arc42.org/section-11/ for further guidance.
+
+Example:
+
+## No Automated Performance Regression Tests
+
+The performance quality goal has no automated gate in CI. Performance regressions can be
+introduced without detection until a production incident occurs.
+
+```arc42
+:::risk
+id: risk-no-perf-tests
+title: No Automated Performance Regression Tests
+severity: high
+mitigation: Add k6 load test suite as a nightly CI job with a p95 threshold gate.
+:::
+```
+-->
+
+Risks and debt of the frame every lernapps app shares, highest first. Each extension adds its archetype's, and an
+interactive app its own.
+
+## Declared Accessibility Limits Not Built
+
+An app may declare its limits in its entry and then get warnings instead of errors from `accessible` and
+`usable-at-360px`; neither the entry field nor the warnings exist yet, so an app that deviates (a game against the
+clock) fails `lernapps check` today.
+
+```arc42
+:::risk
+id: risk-accessibility-limits-not-built
+title: Declared accessibility limits not built
+severity: medium
+mitigation: Planned in the sketch (tooling step 2, lernapps/apps step 3); until then an app keeps both rules or cannot be listed.
+:::
+```
+
+## Storage Quota Not Built
+
+The quota of 100 kB per app is decided, but the storage wrapper has no limit: `save` succeeds until the browser
+refuses, so one app can fill the origin's shared 5 MiB.
+
+```arc42
+:::risk
+id: risk-storage-quota-not-built
+title: Storage quota of 100 kB not built
+severity: medium
+mitigation: Build the quota into the tooling's storage wrapper, so that save refuses beyond 100 kB per app; until then apps keep only small values (the quiz's last result, the explainer's chosen way to the tutor).
+:::
+```
+
+## Shared Origin Storage
+
+Every app on lernapps.net shares one origin and so one `localStorage`. A learner who clears the site's data, or a
+browser that evicts it, loses what every app remembered, and an app that picks another app's storage name reads and
+overwrites its values.
+
+```arc42
+:::risk
+id: risk-shared-origin-storage
+title: Storage shared by every app of the origin
+severity: medium
+mitigation: Accepted (owner): apps keep only small data that may be lost, under their own prefix, and keep working with nothing remembered; the quota limits what one app takes.
+:::
+```
+
+## Tutor Not Built for Quiz and Interactive Apps
+
+The tutor is decided as a handoff to the learner's own assistant (`dec-tutor-variant`), but it is built only for the
+explainer, so a quiz or an interactive app has no tutor yet.
+
+```arc42
+:::risk
+id: risk-tutor-not-built
+title: Tutor handoff not built for quiz and interactive apps
+severity: medium
+mitigation: Build the handoff with the exercise contract and task numbers from the explainer's parts; until then apps add no tutor of their own.
+:::
+```
+
+## arc42 Checks Not Wired
+
+The architecture is meant to be kept current by `arc42 diff --staged --strict` before a commit and `arc42 validate` in
+`lernapps check`; neither is wired into an app yet, so architecture and code can drift unnoticed. In
+`lernapps/app-templates` the generic part and its extensions are validated in the pre-commit hook and in CI.
+
+```arc42
+:::risk
+id: risk-arc42-checks-not-wired
+title: arc42 checks not wired into the app
+severity: medium
+mitigation: Planned in the sketch (tooling step 2); until then the review reads the architecture against the code.
+:::
+```
+

package/docs/arc42/12-glossary.arc42.md

@@ -0,0 +1,162 @@
+# Glossary
+
+<!--
+Arc42 chapter 12. Define the domain and technical terms used in the architecture documentation.
+A shared glossary reduces misunderstanding by ensuring all stakeholders use the same language.
+If you work in multi-language teams, it also serves as a translation reference.
+
+For each term, write a ## section with a prose paragraph providing context, etymology, or
+extended explanation where useful, followed by a DSL block with a concise definition.
+
+Keep the `definition` field to one or two sentences that unambiguously identify the concept.
+Extended explanation belongs in the prose above the block.
+
+If a short form is important, include it in the prose; the typed glossary block has no
+`abbreviation` field.
+
+Note synonyms the team has agreed NOT to use, and why, in the prose paragraph.
+
+See https://docs.arc42.org/section-12/ for further guidance.
+
+Example:
+
+## Bounded Context
+
+A bounded context is a logical boundary within which a domain model is consistent and
+unambiguous. Inside a bounded context, terms have precise, agreed meanings. The same word
+may mean something different in another bounded context.
+
+```arc42
+:::glossary-term
+id: term-bounded-context
+title: Bounded Context
+definition: A logical boundary within which a domain model, its language, and its rules are internally consistent. Defined in Domain-Driven Design (Evans, 2003).
+:::
+```
+-->
+
+Terms with a meaning specific to lernapps apps of every archetype. Learner-facing text is German; these terms are the
+English names used in code, schemas and this architecture. Each extension adds its archetype's terms.
+
+## Archetype
+
+One of the kinds of app the generator can make, each a template folder of `lernapps/app-templates` with its runtime:
+`quiz`, `explainer`, `interactive`.
+
+```arc42
+:::glossary-term
+id: term-archetype
+title: Archetype
+definition: A kind of lernapps app (quiz, explainer, interactive) with its template and its runtime, which fixes what the creator writes.
+:::
+```
+
+## Extension
+
+Lives in the template folder's `docs/arc42/`; it references the generic ids and defines none of them again.
+
+```arc42
+:::glossary-term
+id: term-extension
+title: Extension
+definition: The part of the architecture one archetype adds to the generic architecture, its blocks placed below the generic ones.
+:::
+```
+
+## Runtime
+
+The runtime of `@lernapps/app-templates`; together with the tooling helpers it forms the frame an app does not change.
+
+```arc42
+:::glossary-term
+id: term-runtime
+title: Runtime
+definition: The shared code of every app of an archetype that builds its pages, checks it at build time and runs it in the browser; the app never edits it.
+:::
+```
+
+## Shell
+
+Started by the archetype's start function in `src/main.ts`: `startQuiz`, `startExplainer` or `startInteractive`.
+
+```arc42
+:::glossary-term
+id: term-shell
+title: Shell
+definition: The runtime's code in the browser that turns the static pages into the live app.
+:::
+```
+
+## Creator
+
+The person who makes and lists an app on lernapps.net, usually working through an AI assistant.
+
+```arc42
+:::glossary-term
+id: term-creator
+title: Creator
+definition: The person who builds an app and lists it in the app overview.
+:::
+```
+
+## Start Page
+
+`index.html` of each language. Not to be confused with the home page of lernapps.net.
+
+```arc42
+:::glossary-term
+id: term-start-page
+title: Start page
+definition: The page at the app's address, rendered at build from what the creator wrote, from which every other page of the app is reached.
+:::
+```
+
+## Seed
+
+Taken from the address where the archetype uses one, else drawn at random.
+
+```arc42
+:::glossary-term
+id: term-seed
+title: Seed
+definition: A positive integer from which the app draws everything random, so that the same address gives the same order, task or states.
+:::
+```
+
+## Entry
+
+The only way an app connects to the platform: its entry links to it. Its topics may point to the app's deep links, an
+app that deviates from the accessibility default says so there, and its fact sheet states the app's size (not built
+yet).
+
+```arc42
+:::glossary-term
+id: term-entry
+title: Entry
+definition: The one YAML file per app in lernapps/apps entries/, checked against the entry schema, that lists the app in the app overview.
+:::
+```
+
+## Catalog
+
+Shown at lernapps.net/apps/; the owner decides whether an app is listed.
+
+```arc42
+:::glossary-term
+id: term-catalog
+title: Catalog
+definition: The apps the app overview of lernapps.net provides, one entry per app.
+:::
+```
+
+## Tutor
+
+Optional; built for the explainer only; no model runs in the browser (see `dec-tutor-variant`).
+
+```arc42
+:::glossary-term
+id: term-tutor
+title: Tutor
+definition: The learner's own AI assistant, to which the app hands the current task after a click, through a prompt and static tutor pages.
+:::
+```