# aviorxt/ziwah architecture

> Architecture diagram of the GitHub repository aviorxt/ziwah, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aviorxt/ziwah
- Repository: https://github.com/aviorxt/ziwah

## Overview

1. **Overall shape**
   - This is a **static, client-side single-page storytelling site**. There is no backend, database, or API layer.
   - The architecture is centered on three runtime pieces in the browser: **HTML structure**, **CSS presentation/animation**, and **JavaScript interaction/audio state**.

2. **Entry point and document structure**
   - `index.html` is the single entry document.
   - It likely contains the **splash/loader**, the **full-screen chapter sections**, and the **overlay UI** used for story navigation, progress, and audio controls.
   - The page is designed around **vertical scroll-snap sections**, so each chapter acts as a discrete viewport-sized scene.

3. **Presentation layer**
   - `css/styles.css` is the main styling subsystem.
   - It handles the cinematic look: **glassmorphism overlays, typography, viewport-based sizing, responsive breakpoints, smooth transitions, and Ken Burns-style background motion**.
   - CSS is also responsible for the **visibility/reveal choreography** of text and panels when a chapter becomes active.

4. **Interaction and state orchestration**
   - `js/app.js` is the main UI controller.
   - It likely manages:
     - the loader “Enter Story” interaction,
     - scroll/section activation,
     - active chapter highlighting,
     - progress indicators,
     - class toggling for reveal animations,
     - and coordination between scrolling state and audio state.
   - The key browser mechanism here is **Intersection Observer**, which marks the chapter currently in view.

5. **Audio subsystem**
   - `js/audio.js` is a separate, focused subsystem for sound generation.
   - It uses the **Web Audio API** to synthesize ambient piano-like chords procedurally, without bundled audio files.
   - This module appears to create the musical atmosphere, manage **envelopes, delay/echo, and chapter-based chord progression changes**, and expose controls for starting/stopping or muting.

6. **Data flow: scroll drives scene state**
   - The main flow is: **user scrolls → Intersection Observer identifies active chapter → app.js updates active UI state → CSS transitions reveal chapter content**.
   - The same active chapter signal also feeds the audio layer so the soundtrack can shift harmony or texture according to the visible chapter.

7. **Data flow: interaction unlocks audio**
   - Because Web Audio often requires a user gesture, the **“Enter Story”** action is the gate that starts the immersive mode.
   - That click likely initializes or resumes the audio context and begins the soundtrack, while also dismissing the loader and enabling the story UI.

8. **Visual asset boundary**
   - `assets/images` holds the chapter imagery and background visuals.
   - These assets are used as atmospheric scene backdrops rather than as application data.
   - The site’s cinematic feel depends on those images plus CSS-driven scaling and panning effects.

9. **Deployment and hosting**
   - `vercel.json` defines the deployment boundary for Vercel.
   - Its role is static hosting behavior: **clean URLs and caching rules for assets**.
   - There is no server-side rendering or custom runtime on Vercel; it serves the static site as-is.

10. **Important architectural constraint**
   - The system is intentionally **self-contained in the browser**.
   - All narrative, animation, and music behavior is local to the client, so the diagram should show a **single browser app** consuming static assets and generating audio procedurally, with no external services in the execution path.

11. **Subsytem summary for diagramming**
   - **Content layer:** `index.html` and chapter markup.
   - **Style/animation layer:** `css/styles.css`.
   - **Interaction/state layer:** `js/app.js`.
   - **Audio synthesis layer:** `js/audio.js`.
   - **Media assets:** `assets/images`.
   - **Deployment config:** `vercel.json`.

12. **Suggested mental model**
   - Think of the repo as a **cinematic narrative engine**: the page scroll position is the primary input, the current chapter is the core state, CSS renders the scene, and the Web Audio synth provides adaptive ambience.

Main entry points: [`index.html`](https://github.com/aviorxt/ziwah/blob/main/index.html) (Story Shell), [`vercel.json`](https://github.com/aviorxt/ziwah/blob/main/vercel.json) (Vercel Config), [`js/app.js`](https://github.com/aviorxt/ziwah/blob/main/js/app.js) (UI Controller), [`css/styles.css`](https://github.com/aviorxt/ziwah/blob/main/css/styles.css) (Scene Styling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser App"]
  node_index_html["Story Shell<br/>document<br/>[index.html]"]
  node_styles_css["Scene Styling<br/>css<br/>[styles.css]"]
  node_app_js["UI Controller<br/>browser script<br/>[app.js]"]
  node_audio_js["Audio Synth<br/>web audio<br/>[audio.js]"]
  node_browser_runtime(("Browser Runtime<br/>client runtime"))
end

subgraph group_media["Media"]
  node_image_assets[("Images<br/>static media")]
end

subgraph group_deploy["Deployment"]
  node_vercel_cfg["Vercel Config<br/>hosting config<br/>[vercel.json]"]
end

node_browser_runtime -->|"loads"| node_index_html
node_index_html -->|"includes"| node_styles_css
node_index_html -->|"includes"| node_app_js
node_index_html -->|"includes"| node_audio_js
node_index_html -->|"references"| node_image_assets
node_app_js -->|"toggles state"| node_styles_css
node_app_js -->|"controls"| node_audio_js
node_app_js -->|"observes scroll"| node_index_html
node_audio_js -->|"runs in"| node_browser_runtime
node_styles_css -->|"frames"| node_image_assets
node_vercel_cfg -->|"serves"| node_index_html
node_vercel_cfg -->|"serves"| node_styles_css
node_vercel_cfg -->|"serves"| node_app_js
node_vercel_cfg -->|"serves"| node_audio_js
node_vercel_cfg -->|"serves"| node_image_assets

click node_index_html "https://github.com/aviorxt/ziwah/blob/main/index.html"
click node_styles_css "https://github.com/aviorxt/ziwah/blob/main/css/styles.css"
click node_app_js "https://github.com/aviorxt/ziwah/blob/main/js/app.js"
click node_audio_js "https://github.com/aviorxt/ziwah/blob/main/js/audio.js"
click node_image_assets "https://github.com/aviorxt/ziwah/tree/main/assets/images"
click node_vercel_cfg "https://github.com/aviorxt/ziwah/blob/main/vercel.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index_html,node_styles_css,node_app_js,node_audio_js,node_browser_runtime toneBlue
class node_image_assets toneAmber
class node_vercel_cfg toneMint
```

## Components

### Browser App

Client-side storytelling experience running entirely in the browser.

- [Story Shell](https://github.com/aviorxt/ziwah/blob/main/index.html): document · Single-page entry document containing the loader, chapters, and overlay UI. · `index.html`
- [Scene Styling](https://github.com/aviorxt/ziwah/blob/main/css/styles.css): css · Main presentation layer for cinematic layout, motion, responsive behavior, and reveal transitions. · `css/styles.css`
- [UI Controller](https://github.com/aviorxt/ziwah/blob/main/js/app.js): browser script · Coordinates loader flow, scroll-driven active chapter state, progress, and reveal choreography. · `js/app.js`
- [Audio Synth](https://github.com/aviorxt/ziwah/blob/main/js/audio.js): web audio · Procedural ambient soundtrack and chapter-aware audio state built with the Web Audio API. · `js/audio.js`
- **Browser Runtime**: client runtime · The self-contained execution environment where scroll, animation, and audio state live.

### Media

Atmospheric visual assets used as chapter backdrops.

- [Images](https://github.com/aviorxt/ziwah/tree/main/assets/images): static media · Chapter imagery and background visuals used to create the cinematic atmosphere. · `assets/images`

### Deployment

Static hosting configuration for Vercel.

- [Vercel Config](https://github.com/aviorxt/ziwah/blob/main/vercel.json): hosting config · Static deployment rules for clean URLs and asset handling on Vercel. · `vercel.json`

## Connections

- Browser Runtime → Story Shell: loads · The browser renders the single-page story document.
- Story Shell → Scene Styling: includes · The document pulls in the main styling and animation layer.
- Story Shell → UI Controller: includes · The document bootstraps the interaction controller.
- Story Shell → Audio Synth: includes · The document loads the audio subsystem used for ambience.
- Story Shell → Images: references · Chapters and scenes use static imagery from the asset folder.
- UI Controller → Scene Styling: toggles state · Interaction code drives active/reveal classes that CSS animates.
- UI Controller → Audio Synth: controls · Active chapter and user gestures are forwarded to the audio layer.
- UI Controller → Story Shell: observes scroll · Intersection-based chapter activation comes from the page structure.
- Audio Synth → Browser Runtime: runs in · Web Audio synthesis executes locally in the browser.
- Scene Styling → Images: frames · CSS scales, positions, and animates the background imagery.
- Vercel Config → Story Shell: serves · Deployment serves the static entry document.
- Vercel Config → Scene Styling: serves · Hosting exposes the stylesheet as a static asset.
- Vercel Config → UI Controller: serves · Hosting exposes the interaction script as a static asset.
- Vercel Config → Audio Synth: serves · Hosting exposes the audio script as a static asset.
- Vercel Config → Images: serves · Hosting exposes the image assets as static files.