DecoJS is a vanilla-JavaScript Progressive Web App with no build pipeline. The browser loads ES modules directly from source, and every `.js` file in the repo is exactly the file the browser parses. This page covers the high-level shape; per-file details live in [Module-Reference](Module-Reference.md).

## No-build ES-module philosophy

There is no bundler, no transpiler, no TypeScript compile step, no `dist/` directory. HTML files load entry modules with `<script type="module" src="...">` and the rest resolves through native `import` statements. Two consequences worth naming:

- **Imports use explicit relative paths with `.js` extensions** (e.g. `import { COMPARTMENTS } from './tissueCompartments.js'`). No bare-module resolution, no import maps, no path aliases.
- **Third-party libraries come from CDN `<script>` tags**, not npm. Chart.js, chartjs-plugin-annotation, Hammer.js, and chartjs-plugin-zoom are loaded from `cdn.jsdelivr.net` in the entry HTML; `node_modules/` exists only for Jest (used by an alternate test runner; the primary runner is dependency-free).

The rationale is educational transparency: a reader with a browser and a text editor can trace any value on screen back to the exact line of source that produced it, without sourcemaps, bundling artefacts, or a toolchain to stand up.

## Three sections, three entry families

The app is split into three user-facing sections, defined by `NAV_ITEMS` in `js/nav.js`:

| Section | Count | Entry HTML files | Primary modules |
|---|---|---|---|
| **Sandbox** | 5 simulators | `sandbox/index.html`, `sandbox/tissue-saturation.html`, `sandbox/transfilling.html`, `sandbox/cascade-filling.html`, `sandbox/gas-law.html` | `DiveSetupEditor` + `DiveProfileChart` + `MValueChart` + `GFChart` (main sandbox); specialised simulators for the rest |
| **Theory** | 4 lessons | `pressure.html`, `tissue-loading.html`, `m-values.html`, `gradient-factors.html` | Embed chart components with canned setups; `TissueSaturationSim`, `StickyTOC`, `HeroMotion` for page chrome |
| **Tests** | 7 quizzes | `quiz-physics.html`, `quiz-anatomy.html`, `quiz-accidents.html`, `quiz-safety.html`, `quiz-training.html`, `quiz-equipment.html`, `quiz-vessel.html` | Generic `quiz.js` engine + per-topic JSON in `data/quiz-*.json` |

The landing (`index.html`) and `about.html` sit outside these groups.

## Module dependency graph

All imports are static (no dynamic `import()` calls) and the graph is acyclic. The core has four shared modules used across sections; the Sandbox-only chart and editor components layer on top.

```mermaid
graph TD
    subgraph Entry["Entry HTMLs"]
        SandboxHTML[sandbox/index.html]
        TheoryHTML[theory pages<br/>pressure / tissue-loading / m-values / gradient-factors]
        QuizHTML[quiz-*.html]
    end

    subgraph Components["Components & Charts"]
        DSE[components/DiveSetupEditor.js]
        DPC[charts/DiveProfileChart.js]
        MVC[charts/MValueChart.js]
        GFC[charts/GFChart.js]
        TSS[components/TissueSaturationSim.js]
        Quiz[quiz.js]
    end

    subgraph Core["Core algorithm modules"]
        Deco[decoModel.js]
        TC[tissueCompartments.js]
        DS[diveSetup.js]
        DP[diveProfile.js]
        TE[tissueEducation.js]
    end

    subgraph Shared["App-wide shared"]
        Nav[nav.js]
        I18n[i18n.js]
        CT[charts/chartTheme.js]
        CTypes[charts/chartTypes.js]
    end

    SandboxHTML --> DSE
    SandboxHTML --> DPC
    SandboxHTML --> MVC
    SandboxHTML --> GFC
    SandboxHTML --> Nav
    SandboxHTML --> I18n

    TheoryHTML --> DPC
    TheoryHTML --> MVC
    TheoryHTML --> GFC
    TheoryHTML --> TSS
    TheoryHTML --> Nav
    TheoryHTML --> I18n

    QuizHTML --> Quiz
    QuizHTML --> Nav
    QuizHTML --> I18n

    DSE --> DS
    DSE --> CTypes
    DSE --> I18n

    DPC --> Deco
    DPC --> DS
    DPC --> TC
    DPC --> CT
    DPC --> CTypes
    DPC --> I18n

    MVC --> Deco
    MVC --> TC
    MVC --> CT
    MVC --> CTypes
    MVC --> I18n

    GFC --> Deco
    GFC --> TC
    GFC --> CT
    GFC --> I18n

    TSS --> TE
    TSS --> Deco
    TSS --> TC

    Deco --> TC
    DS --> Deco
    DS --> TC

    Nav --> I18n
```

Observations:

- **`decoModel.js` and `tissueCompartments.js` are the two universal-core modules** — every chart pulls from them.
- **`diveSetup.js` depends on `decoModel.js`** (it calls `calculateNDL`, `generateDecoSchedule`, `simulateDepthTime`, etc.), so importing `diveSetup` pulls in the whole algorithm.
- **`diveProfile.js` is standalone** — parsing and validation only, no algorithm imports.
- **Nothing imports `quiz.js` except quiz pages** — the quiz subsystem is cleanly isolated from the deco algorithm.

## Rendering: Chart.js on Canvas

All three algorithm charts — `DiveProfileChart`, `MValueChart`, `GFChart` — use the same rendering stack:

- **Chart.js v3+** on **HTML5 Canvas** (not SVG). One `<canvas>` per chart instance; Chart.js owns the pixel buffer and redraws on every `chart.update()`.
- **chartjs-plugin-annotation** for M-value lines, pAnchor markers, deco stop annotations, and gas switch markers.
- **Hammer.js + chartjs-plugin-zoom** for pinch/pan/wheel interaction. Double-click resets zoom; a lock button (`js/charts/interactionLock.js`) toggles interaction on for mobile.
- **`chartTheme.js`** reads CSS custom properties from `:root` and applies them as Chart.js defaults — typography, grid colors, legend styling. Idempotent; called before every render and on theme toggle.
- **`chartTypes.js`** centralises dive-setup validation and normalisation (`validateDiveSetup`, `normalizeDiveSetup`, `mergeOptions`). No runtime types — just schema-style validation.

All CDN scripts are loaded in the entry HTML, not imported by modules, so the algorithm core remains Chart.js-free and is directly unit-testable under Node.

## i18n

Custom JSON-based loader — no i18next, no framework. Three languages ship (`locales/en.json`, `locales/cs.json`, `locales/es.json`): theory pages default to English, quizzes default to Czech (SPČR source material).

- `js/i18n.js` fetches the current locale bundle, exposes a `translate(key, params)` function, and wires a language switcher into the nav.
- On user language change it dispatches a global **`languagechange`** event.
- Every component that renders text listens for `languagechange` and re-renders — chart axis labels, legend, tooltips, DiveSetupEditor form labels, nav links, quiz question bodies.

## Event model

Components extend the native `EventTarget` and communicate via DOM-style custom events — no pub/sub library, no store, no framework state.

The canonical flow:

1. User edits a field in `DiveSetupEditor`.
2. The editor serialises its form to a `diveSetup` object and emits `change` with `detail.diveSetup` (if `emitOnInput === true`, every keystroke; otherwise on blur).
3. Each chart listens on the editor instance: `editor.addEventListener('change', e => chart.update(e.detail.diveSetup))`.
4. `update()` re-validates through `chartTypes.js`, recomputes tissue loading and ceiling via `decoModel.js`, rebuilds Chart.js datasets, and calls `chart.update()`.

The same pattern carries `languagechange` (global on `window`) and theme toggles. No component reaches into another's internals; all cross-component state moves through events or through the `diveSetup` object itself.

Per-file details live in [Module-Reference](Module-Reference.md).