aviorxt/ziwah

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.