+
+## 1. End User Code
+
+The End User Code is written in JavaScript with added syntax sugar. The [eval package](https://github.com/tidalcycles/strudel/tree/main/packages/eval#strudelcycleseval) evaluates the user code
+after a transpilation step, which resolves the syntax sugar. If you don't want the syntax sugar, you can omit the eval package and call the native javascript `eval` instead.
+
+### 🍭 Syntax Sugar
+
+JavaScript Transpilation = converting valid JavaScript to valid JavaScript:
+
+```js
+"c3 [e3 g3]".fast(2)
+```
+
+becomes
+
+```js
+mini('c3 [e3 g3]')
+ .withMiniLocation([1, 0, 0], [1, 11, 11]) // source location
+ .fast(2);
+```
+
+- double quoted strings and backtick strings are turned into `mini` calls (single quoted strings are left as is)
+- The source location is added by chaining `withMiniLocation`, which enables the real time highlighting later
+- (psuedo) variable names that look like notes (like `c4`, `bb2` or `fs3`) are turned into strings
+- support for top level await
+- operator overloading could be implemented in the future
+
+This is how it works:
+
+
+
+- The user code is parsed with a [shift parser](https://github.com/shapesecurity/shift-parser-js), generating an AST
+- The AST is transformed to resolve the syntax sugar
+- The AST is used to generate code again (shift-codegen)
+
+Shift will most likely be replaced with acorn in the future, see https://github.com/tidalcycles/strudel/issues/174
+
+### Mini Notation
+
+Another important part of the user code is the mini notation, which allows to express rhythms in a short manner.
+
+- the mini notation is [implemented as a PEG grammar](https://github.com/tidalcycles/strudel/blob/main/packages/mini/krill.pegjs), living in the [mini package](https://github.com/tidalcycles/strudel/tree/main/packages/mini)
+- it is based on [krill](https://github.com/Mdashdotdashn/krill) by Mdashdotdashn
+- the peg grammar is used to generate a parser with [peggyjs](https://peggyjs.org/)
+- the generated parser takes a mini notation string and outputs an AST
+- the AST can then be used to construct a pattern using the regular Strudel API
+
+Here's an example AST:
+
+```json
+{
+ "type_": "pattern",
+ "arguments_": { "alignment": "h" },
+ "source_": [
+ {
+ "type_": "element", "source_": "c3",
+ "location_": { "start": { "offset": 1, "line": 1, "column": 2 }, "end": { "offset": 4, "line": 1, "column": 5 } }
+ },
+ {
+ "type_": "element",
+ "location_": { "start": { "offset": 4, "line": 1, "column": 5 }, "end": { "offset": 11, "line": 1, "column": 12 } }
+ "source_": {
+ "type_": "pattern", "arguments_": { "alignment": "h" },
+ "source_": [
+ {
+ "type_": "element", "source_": "e3",
+ "location_": { "start": { "offset": 5, "line": 1, "column": 6 }, "end": { "offset": 8, "line": 1, "column": 9 } }
+ },
+ {
+ "type_": "element", "source_": "g3",
+ "location_": { "start": { "offset": 8, "line": 1, "column": 9 }, "end": { "offset": 10, "line": 1, "column": 11 } }
+ }
+ ]
+ },
+ }
+ ]
+}
+```
+
+which translates to `seq(c3, seq(e3, g3))`
+
+## 2. Querying & Scheduling
+
+When the user code has been evaluated, we hopefully get a Pattern instance, which we can use to query events from.
+These events can then be used to trigger side effects in the real world. On that note, Events are mostly called Hap(s) in the codebase, because JS already has a built in `Event` class.
+
+### Querying
+
+> Querying = Asking a Pattern for Events within a certain time span
+
+```js
+seq('c3', ['e3', 'g3']) // <--- Pattern
+ .queryArc(0, 2) // query events within 0 and 2 cycles
+ .map((hap) => hap.showWhole()); // make readable
+```
+
+yields
+
+```js
+[
+ '0/1 -> 1/2: c3', // cycle 0
+ '1/2 -> 3/4: e3',
+ '3/4 -> 1/1: g3',
+ '1/1 -> 3/2: c3', // cycle 1
+ '3/2 -> 7/4: e3',
+ '7/4 -> 2/1: g3',
+];
+```
+
+### 🗓️ Scheduling
+
+The scheduler will query events repeatedly, creating a possibly endless loop of time slices.
+Here is a simplified example of how it works
+
+```js
+let step = 0.5; // query interval in seconds
+let tick = 0; // how many intervals have passed
+let pattern = seq('c3', ['e3', 'g3']); // pattern from user
+setInterval(() => {
+ const events = pattern.queryArc(tick * step, ++tick * step);
+ events.forEach((event) => {
+ console.log(event.showWhole());
+ const o = getAudioContext().createOscillator();
+ o.frequency.value = getFreq(event.value);
+ o.start(event.whole.begin);
+ o.stop(event.whole.begin + event.duration);
+ o.connect(getAudioContext().destination);
+ });
+}, step * 1000); // query each "step" seconds
+```
+
+## 3. Sound Output
+
+The third and last step is to use the scheduled events to make sound.
+Patterns are wrapped with param functions to compose different properties of the sound.
+
+```js
+note("[c2(3,8) [
+
+
+
+- Patterns represent just values in time!
+- Suitable for any time based output (music, visuals, movement, .. ?)
+
+### Supported Outputs
+
+At the time of writing this doc, the following outputs are supported:
+
+- Web Audio API `.out()` see [/webaudio](https://github.com/tidalcycles/strudel/tree/main/packages/webaudio)
+- MIDI `.midi()` see [/midi](https://github.com/tidalcycles/strudel/tree/main/packages/midi)
+- OSC `.osc()` see [/osc](https://github.com/tidalcycles/strudel/tree/main/packages/osc)
+- Serial `.serial()` see [/serial](https://github.com/tidalcycles/strudel/tree/main/packages/serial)
+- Tone.js `.tone()` (deprecated?) [/tone](https://github.com/tidalcycles/strudel/tree/main/packages/tone)
+- WebDirt `.webdirt()` (deprecated?) [/webdirt](https://github.com/tidalcycles/strudel/tree/main/packages/webdirt)
+- Speech `.speak()` (experimental) part of [/core](https://github.com/tidalcycles/strudel/tree/main/packages/core)
+
+These could change, so make sure to check the [packages folder](https://github.com/tidalcycles/strudel/tree/main/packages).
diff --git a/docs/technical-manual/shiftflow.png b/docs/technical-manual/shiftflow.png
new file mode 100644
index 000000000..8d91658dc
Binary files /dev/null and b/docs/technical-manual/shiftflow.png differ
diff --git a/docs/technical-manual/strudelflow.png b/docs/technical-manual/strudelflow.png
new file mode 100644
index 000000000..72cdf494b
Binary files /dev/null and b/docs/technical-manual/strudelflow.png differ
diff --git a/docs/technical-manual/waa-nodes.png b/docs/technical-manual/waa-nodes.png
new file mode 100644
index 000000000..cece1aa91
Binary files /dev/null and b/docs/technical-manual/waa-nodes.png differ