# kishanpujari/wallom architecture

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

- Interactive diagram: https://gitdiagram.com/kishanpujari/wallom
- Repository: https://github.com/kishanpujari/wallom

## Overview

#### Purpose and Runtime
Wallom is a Windows terminal grid-survival game implemented in PowerShell 5.1+. It runs a turn-based loop: the player moves, places mines or permanent wall bombs, collects points, and attempts to eliminate an AI enemy. ANSI terminal output provides the UI; JSON files persist game and settings state.

#### Launch and Composition
`Wallom.bat` is the Windows entry point and launches the PowerShell game. The engine is modularized as dot-sourced PowerShell scripts under `bin/`, with the central coordinator in `bin/engine.ps1`.

Key entry paths:
- `Wallom.bat`
- `bin/engine.ps1`
- `bin/splash.ps1`

#### Engine and Game Lifecycle
`bin/engine.ps1` owns high-level control flow: initialize/load a game, accept command input, advance game state, redraw the terminal, and exit or save. It composes domain modules rather than exposing a separate service or networked API.

Lifecycle boundaries:
1. Start/menu and settings selection.
2. Create or restore state.
3. Repeated player-command and enemy-update turns.
4. Persist state and return/quit.

Related UI modules:
- `bin/splash.ps1`
- `bin/ui_settings.ps1`
- `bin/ui_help.ps1`

#### Grid World and Rendering
`bin/grid.ps1` defines the playable map behavior: procedural grid setup, placement and representation of walls, player, enemy, bombs, and collectibles, plus movement/blocking constraints. It is the primary shared spatial model used by player actions, enemy movement, and bomb effects.

Terminal presentation is separated into reusable color and menu/logo views:
- `bin/grid.ps1`
- `bin/colors.ps1`
- `bin/ui_logo.ps1`

#### Enemy and Combat Systems
`bin/enemy.ps1` implements AI-driven enemy movement against the current grid state. The enemy’s turn depends on obstacle and mine placement, and it can be killed by stepping on a mine.

`bin/bomb.ps1` manages player-deployed hazards: X1 mines with configurable lifetime/radius behavior and X2 wall bombs that create durable map obstacles. This module changes grid state and supplies the combat outcome that can end a session.

Core paths:
- `bin/enemy.ps1`
- `bin/bomb.ps1`
- `bin/grid.ps1`

#### Persistence and Settings
`bin/db.ps1` is the persistence boundary for JSON game saves, including session/game ID, player and enemy positions, score, walls, bombs, and collectibles. It isolates saved-state serialization from turn logic.

`bin/config.ps1` separately manages persistent gameplay configuration, notably maximum mine count and mine lifetime; settings UI updates this configuration rather than requiring source edits.

Core paths:
- `bin/db.ps1`
- `bin/config.ps1`
- `bin/ui_settings.ps1`

#### Infrastructure and External Dependencies
The repository has no web server, database service, package runtime, or external API dependency. Required infrastructure is a Windows console with PowerShell and ANSI-capable terminal rendering. Batch is used only as the launcher; JSON files are the sole durable storage mechanism.

Main entry points: [`bin/engine.ps1`](https://github.com/kishanpujari/wallom/blob/main/bin/engine.ps1) (Game engine), [`bin/grid.ps1`](https://github.com/kishanpujari/wallom/blob/main/bin/grid.ps1) (Grid world), [`bin/config.ps1`](https://github.com/kishanpujari/wallom/blob/main/bin/config.ps1) (Gameplay settings), [`bin/splash.ps1`](https://github.com/kishanpujari/wallom/blob/main/bin/splash.ps1) (Start menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch & UI"]
  node_launcher["Wallom launcher<br/>batch entry point<br/>[Wallom.bat]"]
  node_splash["Start menu<br/>PowerShell UI<br/>[splash.ps1]"]
  node_settings_ui["Settings UI<br/>PowerShell UI<br/>[ui_settings.ps1]"]
  node_help_ui["Help UI<br/>PowerShell UI<br/>[ui_help.ps1]"]
  node_colors["Terminal colors<br/>rendering utility<br/>[colors.ps1]"]
  node_logo["Logo view<br/>terminal view<br/>[ui_logo.ps1]"]
end

subgraph group_gameplay["Game Engine"]
  node_engine["Game engine<br/>PowerShell coordinator<br/>[engine.ps1]"]
  node_grid["Grid world<br/>spatial domain model<br/>[grid.ps1]"]
  node_enemy["Enemy AI<br/>turn system<br/>[enemy.ps1]"]
  node_bombs["Bomb system<br/>combat system<br/>[bomb.ps1]"]
end

subgraph group_storage["State &amp; Settings"]
  node_game_db[("Game save store<br/>JSON persistence<br/>[db.ps1]")]
  node_config[("Gameplay settings<br/>JSON configuration<br/>[config.ps1]")]
  node_json_files[("JSON files<br/>durable storage")]
end

node_terminal{{"Windows ANSI terminal<br/>runtime environment"}}

node_launcher -->|"launches"| node_engine
node_engine -->|"shows menu"| node_splash
node_engine -->|"opens"| node_settings_ui
node_engine -->|"opens"| node_help_ui
node_engine -->|"initializes and updates"| node_grid
node_engine -->|"runs enemy turn"| node_enemy
node_engine -->|"processes player hazards"| node_bombs
node_enemy -->|"reads and moves on"| node_grid
node_bombs -->|"changes hazards and walls"| node_grid
node_engine -->|"loads and saves session"| node_game_db
node_game_db -->|"reads and writes"| node_json_files
node_settings_ui -->|"updates"| node_config
node_engine -->|"loads settings"| node_config
node_config -->|"reads and writes"| node_json_files
node_engine -->|"reads commands and redraws"| node_terminal
node_grid -->|"uses"| node_colors
node_splash -->|"renders"| node_logo
node_engine -->|"uses ANSI output"| node_colors

click node_launcher "https://github.com/kishanpujari/wallom/blob/main/Wallom.bat"
click node_engine "https://github.com/kishanpujari/wallom/blob/main/bin/engine.ps1"
click node_splash "https://github.com/kishanpujari/wallom/blob/main/bin/splash.ps1"
click node_settings_ui "https://github.com/kishanpujari/wallom/blob/main/bin/ui_settings.ps1"
click node_help_ui "https://github.com/kishanpujari/wallom/blob/main/bin/ui_help.ps1"
click node_grid "https://github.com/kishanpujari/wallom/blob/main/bin/grid.ps1"
click node_enemy "https://github.com/kishanpujari/wallom/blob/main/bin/enemy.ps1"
click node_bombs "https://github.com/kishanpujari/wallom/blob/main/bin/bomb.ps1"
click node_colors "https://github.com/kishanpujari/wallom/blob/main/bin/colors.ps1"
click node_logo "https://github.com/kishanpujari/wallom/blob/main/bin/ui_logo.ps1"
click node_game_db "https://github.com/kishanpujari/wallom/blob/main/bin/db.ps1"
click node_config "https://github.com/kishanpujari/wallom/blob/main/bin/config.ps1"

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_launcher,node_splash,node_settings_ui,node_help_ui,node_colors,node_logo toneBlue
class node_engine,node_grid,node_enemy,node_bombs toneAmber
class node_game_db,node_config,node_json_files toneMint
class node_terminal toneNeutral
```

## Components

### Launch & UI

- [Wallom launcher](https://github.com/kishanpujari/wallom/blob/main/Wallom.bat): batch entry point · Starts the PowerShell game. · `Wallom.bat`
- [Start menu](https://github.com/kishanpujari/wallom/blob/main/bin/splash.ps1): PowerShell UI · `bin/splash.ps1`
- [Settings UI](https://github.com/kishanpujari/wallom/blob/main/bin/ui_settings.ps1): PowerShell UI · `bin/ui_settings.ps1`
- [Help UI](https://github.com/kishanpujari/wallom/blob/main/bin/ui_help.ps1): PowerShell UI · `bin/ui_help.ps1`
- [Terminal colors](https://github.com/kishanpujari/wallom/blob/main/bin/colors.ps1): rendering utility · `bin/colors.ps1`
- [Logo view](https://github.com/kishanpujari/wallom/blob/main/bin/ui_logo.ps1): terminal view · `bin/ui_logo.ps1`

### Game Engine

- [Game engine](https://github.com/kishanpujari/wallom/blob/main/bin/engine.ps1): PowerShell coordinator · Owns lifecycle, turn loop, save, and exit flow. · `bin/engine.ps1`
- [Grid world](https://github.com/kishanpujari/wallom/blob/main/bin/grid.ps1): spatial domain model · Creates and enforces the shared playable map state. · `bin/grid.ps1`
- [Enemy AI](https://github.com/kishanpujari/wallom/blob/main/bin/enemy.ps1): turn system · Moves the enemy using current grid obstacles and hazards. · `bin/enemy.ps1`
- [Bomb system](https://github.com/kishanpujari/wallom/blob/main/bin/bomb.ps1): combat system · Manages mines and permanent wall bombs. · `bin/bomb.ps1`

### State & Settings

- [Game save store](https://github.com/kishanpujari/wallom/blob/main/bin/db.ps1): JSON persistence · Serializes sessions, positions, score, walls, bombs, and collectibles. · `bin/db.ps1`
- [Gameplay settings](https://github.com/kishanpujari/wallom/blob/main/bin/config.ps1): JSON configuration · Persists mine limit and mine lifetime settings. · `bin/config.ps1`
- **JSON files**: durable storage · Sole persistent storage for saves and settings.

### Other components

- **Windows ANSI terminal**: runtime environment · Provides input and ANSI-rendered output under PowerShell 5.1+.

## Connections

- Wallom launcher → Game engine: launches
- Game engine → Start menu: shows menu
- Game engine → Settings UI: opens
- Game engine → Help UI: opens
- Game engine → Grid world: initializes and updates
- Game engine → Enemy AI: runs enemy turn
- Game engine → Bomb system: processes player hazards
- Enemy AI → Grid world: reads and moves on
- Bomb system → Grid world: changes hazards and walls
- Game engine → Game save store: loads and saves session
- Game save store → JSON files: reads and writes
- Settings UI → Gameplay settings: updates
- Game engine → Gameplay settings: loads settings
- Gameplay settings → JSON files: reads and writes
- Game engine → Windows ANSI terminal: reads commands and redraws
- Grid world → Terminal colors: uses
- Start menu → Logo view: renders
- Game engine → Terminal colors: uses ANSI output