# lewdry/zorkweb architecture

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

- Interactive diagram: https://gitdiagram.com/lewdry/zorkweb
- Repository: https://github.com/lewdry/zorkweb

## Overview

1. **Overall shape**
   - This is a mostly client-side SvelteKit application that serves classic Zork games in the browser.
   - The core architecture is: **SvelteKit routing/UI shell on top of a browser-based Z-machine interpreter**, with all game ROMs shipped as static assets.

2. **Primary runtime boundary**
   - There is no visible backend domain logic in the repository tree.
   - The important execution boundary is **browser vs. static hosting**: the app ships HTML/CSS/JS plus the Zork ROM files, and the game runs entirely in the user’s browser.

3. **Routing structure**
   - `src/routes/+layout.svelte` and `src/routes/+layout.js` define the global app layout and shared behavior across pages.
   - `src/routes/+page.svelte` is the entry/home page.
   - `src/routes/[game]/+page.js` and `src/routes/[game]/+page.svelte` implement a dynamic route for selecting and playing a specific game, likely mapping URLs like `/zork1`, `/zork2`, `/zork3`.

4. **Game selection and page-level data flow**
   - The `[game]` route is the key navigation boundary: it receives the game identifier from the URL, resolves which ROM to load, and renders the player UI for that game.
   - This is the point where app navigation becomes game runtime setup.

5. **Game execution subsystem**
   - `src/lib/jszm.js` is the likely interpreter/runtime layer for the Z-machine.
   - It is the core engine that consumes a Zork ROM and produces the interactive text adventure behavior in the browser.
   - This subsystem is distinct from the UI: it handles game state, command processing, and output generation.

6. **Player UI subsystem**
   - `src/lib/components/ZPlayer.svelte` is the central interactive component.
   - It likely bridges user input, interpreter output, and auxiliary modes such as voice interaction.
   - This component is the main integration point between the Svelte app and the interpreter runtime.

7. **Shared navigation and app chrome**
   - `src/lib/components/Navbar.svelte` provides persistent navigation across the app.
   - It is part of the app shell rather than the game engine, and likely lets users move between games or pages.

8. **Static game assets**
   - The ROMs live in `static/roms/zork1.z3`, `zork2.z3`, and `zork3.z3`.
   - Because they are in `static`, they are served directly by the host and fetched by the browser at runtime.
   - This is the main content/data source for the interpreter; there is no evidence of ROM fetching from an API.

9. **Supporting assets and presentation**
   - `src/app.css`, Tailwind config, and DaisyUI styling shape the visual presentation.
   - Styling is an app-wide concern, but it does not affect the game logic architecture except by defining the shell around the player.

10. **Voice mode capability**
    - The README calls out speech-to-text and text-to-speech support.
    - That functionality is likely encapsulated in the player layer rather than a separate backend service, meaning the browser uses local Web APIs for voice input/output while still relying on the same interpreter pipeline.

11. **Build and framework boundary**
    - The app is built with **SvelteKit** and bundled via **Vite**.
    - `svelte.config.js`, `vite.config.js`, and `tailwind.config.js` define the framework and asset pipeline, but they do not introduce additional runtime subsystems.

12. **Deployment model**
    - `.github/workflows/deploy.yml` indicates automated deployment via GitHub Actions.
    - Given the static ROMs and browser-only runtime, the deployment is likely a static site deployment rather than a server application.

13. **Important diagram boundaries**
    - A useful architecture diagram should show:
      - **User browser**
      - **SvelteKit app shell / routes**
      - **ZPlayer UI**
      - **JSZM interpreter**
      - **Static ROM assets**
      - Optional **browser speech APIs** for voice mode
    - The key data flow is: **route selection → ROM fetch from `/static/roms` → interpreter execution in browser → text/UI updates back to the player**.

14. **What is not present**
    - No database, auth service, API layer, or server-side game engine is evident in the repository structure.
    - That absence is architecturally important: the application is designed as a self-contained, front-end-hosted interactive fiction player.

Main entry points: [`src/routes/[game]/+page.js`](https://github.com/lewdry/zorkweb/blob/main/src/routes/[game]/+page.js) (Game loader), [`src/lib/components/ZPlayer.svelte`](https://github.com/lewdry/zorkweb/blob/main/src/lib/components/ZPlayer.svelte) (ZPlayer), [`src/routes/+layout.svelte`](https://github.com/lewdry/zorkweb/blob/main/src/routes/+layout.svelte) (App shell), [`static/roms`](https://github.com/lewdry/zorkweb/tree/main/static/roms) (Zork ROMs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser runtime"]
  node_user(("Player<br/>user"))
  node_browser_host["Browser host<br/>runtime boundary"]
  node_speech_apis{{"Speech APIs<br/>web APIs"}}
end

subgraph group_app["SvelteKit app"]
  node_layout_js["Layout data<br/>route module<br/>[+layout.js]"]
  node_layout_svelte["App shell<br/>layout component<br/>[+layout.svelte]"]
  node_home_page["Home page<br/>route page<br/>[+page.svelte]"]
  node_game_route_js["Game loader<br/>dynamic route module<br/>[+page.js]"]
  node_game_page["Game page<br/>route page<br/>[+page.svelte]"]
  node_navbar["Navbar<br/>ui component<br/>[Navbar.svelte]"]
  node_zplayer["ZPlayer<br/>interactive component<br/>[ZPlayer.svelte]"]
  node_jszm["JSZM<br/>z-machine interpreter<br/>[jszm.js]"]
  node_lib_index["Lib entry<br/>module entry<br/>[index.js]"]
  node_app_css["App styles<br/>[app.css]"]
end

subgraph group_content["Static content"]
  node_roms[("Zork ROMs<br/>static assets")]
  node_zork1["Zork I<br/>game ROM<br/>[zork1.z3]"]
  node_zork2["Zork II<br/>game ROM<br/>[zork2.z3]"]
  node_zork3["Zork III<br/>game ROM<br/>[zork3.z3]"]
end

node_deploy_workflow["Deploy workflow<br/>ci workflow<br/>[deploy.yml]"]

node_user -->|"plays"| node_browser_host
node_browser_host -->|"loads app"| node_layout_svelte
node_layout_svelte -->|"shared behavior"| node_layout_js
node_layout_svelte -->|"renders"| node_navbar
node_layout_svelte -->|"hosts"| node_home_page
node_home_page -->|"navigates to"| node_game_route_js
node_game_route_js -->|"provides data"| node_game_page
node_game_page -->|"mounts"| node_zplayer
node_zplayer -->|"drives"| node_jszm
node_zplayer -.->|"uses voice"| node_speech_apis
node_jszm -->|"loads ROMs"| node_roms
node_roms -->|"contains"| node_zork1
node_roms -->|"contains"| node_zork2
node_roms -->|"contains"| node_zork3
node_zplayer -->|"styled by"| node_app_css
node_browser_host -.->|"deployed by"| node_deploy_workflow
node_browser_host -->|"executes"| node_jszm
node_game_route_js -->|"selects"| node_zork1
node_game_route_js -->|"selects"| node_zork2
node_game_route_js -->|"selects"| node_zork3
node_lib_index -->|"re-exports"| node_zplayer
node_lib_index -->|"re-exports"| node_jszm

click node_layout_js "https://github.com/lewdry/zorkweb/blob/main/src/routes/+layout.js"
click node_layout_svelte "https://github.com/lewdry/zorkweb/blob/main/src/routes/+layout.svelte"
click node_home_page "https://github.com/lewdry/zorkweb/blob/main/src/routes/+page.svelte"
click node_game_route_js "https://github.com/lewdry/zorkweb/blob/main/src/routes/[game]/+page.js"
click node_game_page "https://github.com/lewdry/zorkweb/blob/main/src/routes/[game]/+page.svelte"
click node_navbar "https://github.com/lewdry/zorkweb/blob/main/src/lib/components/Navbar.svelte"
click node_zplayer "https://github.com/lewdry/zorkweb/blob/main/src/lib/components/ZPlayer.svelte"
click node_jszm "https://github.com/lewdry/zorkweb/blob/main/src/lib/jszm.js"
click node_lib_index "https://github.com/lewdry/zorkweb/blob/main/src/lib/index.js"
click node_app_css "https://github.com/lewdry/zorkweb/blob/main/src/app.css"
click node_roms "https://github.com/lewdry/zorkweb/tree/main/static/roms"
click node_zork1 "https://github.com/lewdry/zorkweb/blob/main/static/roms/zork1.z3"
click node_zork2 "https://github.com/lewdry/zorkweb/blob/main/static/roms/zork2.z3"
click node_zork3 "https://github.com/lewdry/zorkweb/blob/main/static/roms/zork3.z3"
click node_deploy_workflow "https://github.com/lewdry/zorkweb/blob/main/.github/workflows/deploy.yml"

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_user,node_browser_host,node_speech_apis toneBlue
class node_layout_js,node_layout_svelte,node_home_page,node_game_route_js,node_game_page,node_navbar,node_zplayer,node_jszm,node_lib_index,node_app_css toneAmber
class node_roms,node_zork1,node_zork2,node_zork3 toneMint
class node_deploy_workflow toneNeutral
```

## Components

### Browser runtime

Client-side execution boundary in the user’s browser.

- **Player**: user · Person interacting with the text adventure in the browser.
- **Browser host**: runtime boundary · Executes the app and interprets game logic entirely client-side.
- **Speech APIs**: web APIs · Browser speech-to-text and text-to-speech capabilities used for voice mode.

### SvelteKit app

Routing, shell, and interactive game UI.

- [Layout data](https://github.com/lewdry/zorkweb/blob/main/src/routes/+layout.js): route module · Shared route-level setup and page behavior. · `src/routes/+layout.js`
- [App shell](https://github.com/lewdry/zorkweb/blob/main/src/routes/+layout.svelte): layout component · Global SvelteKit shell around the pages. · `src/routes/+layout.svelte`
- [Home page](https://github.com/lewdry/zorkweb/blob/main/src/routes/+page.svelte): route page · Entry page for the application. · `src/routes/+page.svelte`
- [Game loader](https://github.com/lewdry/zorkweb/blob/main/src/routes/[game]/+page.js): dynamic route module · Resolves the selected game from the URL and prepares page data. · `src/routes/[game]/+page.js`
- [Game page](https://github.com/lewdry/zorkweb/blob/main/src/routes/[game]/+page.svelte): route page · Dynamic route that renders the selected game. · `src/routes/[game]/+page.svelte`
- [Navbar](https://github.com/lewdry/zorkweb/blob/main/src/lib/components/Navbar.svelte): ui component · Persistent navigation shared across the app. · `src/lib/components/Navbar.svelte`
- [ZPlayer](https://github.com/lewdry/zorkweb/blob/main/src/lib/components/ZPlayer.svelte): interactive component · Main game UI that connects input, output, and voice features. · `src/lib/components/ZPlayer.svelte`
- [JSZM](https://github.com/lewdry/zorkweb/blob/main/src/lib/jszm.js): z-machine interpreter · Browser-based Z-machine runtime that executes Zork ROMs. · `src/lib/jszm.js`
- [Lib entry](https://github.com/lewdry/zorkweb/blob/main/src/lib/index.js): module entry · Shared library export surface. · `src/lib/index.js`
- [App styles](https://github.com/lewdry/zorkweb/blob/main/src/app.css): styles · Global presentation and layout styling. · `src/app.css`

### Static content

ROM assets and host-served files used at runtime.

- [Zork ROMs](https://github.com/lewdry/zorkweb/tree/main/static/roms): static assets · Static game files served directly by the host. · `static/roms`
- [Zork I](https://github.com/lewdry/zorkweb/blob/main/static/roms/zork1.z3): game ROM · Static ROM for the first game. · `static/roms/zork1.z3`
- [Zork II](https://github.com/lewdry/zorkweb/blob/main/static/roms/zork2.z3): game ROM · Static ROM for the second game. · `static/roms/zork2.z3`
- [Zork III](https://github.com/lewdry/zorkweb/blob/main/static/roms/zork3.z3): game ROM · Static ROM for the third game. · `static/roms/zork3.z3`

### Other components

- [Deploy workflow](https://github.com/lewdry/zorkweb/blob/main/.github/workflows/deploy.yml): ci workflow · GitHub Actions deployment for the static app. · `.github/workflows/deploy.yml`

## Connections

- Player → Browser host: plays · The player uses the app in the browser.
- Browser host → App shell: loads app · The browser loads the SvelteKit shell.
- App shell → Layout data: shared behavior · The shell uses route-level shared setup.
- App shell → Navbar: renders · Persistent navigation is part of the app chrome.
- App shell → Home page: hosts · The shell wraps the entry page.
- Home page → Game loader: navigates to · Users choose a game route from the entry page.
- Game loader → Game page: provides data · The dynamic route prepares the selected game page.
- Game page → ZPlayer: mounts · The game page renders the interactive player.
- ZPlayer → JSZM: drives · The UI sends commands and receives game output from the interpreter.
- ZPlayer → Speech APIs: uses voice · Voice mode is implemented through browser speech capabilities.
- JSZM → Zork ROMs: loads ROMs · The interpreter consumes static game files.
- Zork ROMs → Zork I: contains · Static asset for Zork I.
- Zork ROMs → Zork II: contains · Static asset for Zork II.
- Zork ROMs → Zork III: contains · Static asset for Zork III.
- ZPlayer → App styles: styled by · The player and shell are presented through global styles.
- Browser host → Deploy workflow: deployed by · The static client is built and deployed via GitHub Actions.
- Browser host → JSZM: executes · Interpreter logic runs entirely client-side.
- Game loader → Zork I: selects · The route resolves the requested game asset.
- Game loader → Zork II: selects · The route resolves the requested game asset.
- Game loader → Zork III: selects · The route resolves the requested game asset.
- Lib entry → ZPlayer: re-exports · Shared library surface exposes the main component.
- Lib entry → JSZM: re-exports · Shared library surface exposes the interpreter module.
