# kailashsr38/ascii-magic-art architecture

> Architecture diagram of the GitHub repository kailashsr38/ascii-magic-art, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kailashsr38/ascii-magic-art
- Repository: https://github.com/kailashsr38/ascii-magic-art

## Overview

ASCII Magic Art is a library of animated ASCII pieces, usable from a terminal, a web page, or JavaScript. The main workflow selects a piece, produces timed text-and-colour frames, optionally restyles them, then plays or renders them. The README documents browser playback and canvas-based image, GIF, and video export; sampled code also shows the CLI using piece modules and runtime styling. The many individual pieces are represented by the catalog and representative implementation nodes. Some browser and export relationships are documented rather than fully visible in the excerpts.

Main entry points: [`bin/cli.js`](https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js) (Terminal CLI), [`runtime/player.js`](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/player.js) (Web player), [`pieces`](https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces) (Piece catalog), [`runtime/canvas.js`](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/canvas.js) (Canvas renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["Terminal CLI<br/>[cli.js]"]
  node_web["Web element<br/>[ascii.js]"]
  node_js_api["JavaScript API"]
  node_prompt["Piece prompts<br/>[cli.js]"]
end

subgraph group_catalog["Art catalog"]
  node_catalog["Piece catalog"]
  node_scene_pieces["Scene pieces"]
  node_image_pieces["Photo scenes<br/>[ocean-sunset.js]"]
end

subgraph group_render["Frame and render runtime"]
  node_player["Web player<br/>[player.js]"]
  node_glyphs["Look restyling<br/>[glyphs.js]"]
  node_canvas["Canvas renderer<br/>[canvas.js]"]
  node_terminal_output["Terminal playback<br/>[cli.js]"]
end

subgraph group_toolkit["Drawing toolkit"]
  node_image_motion["Image animation<br/>[image.js]"]
  node_scene_tools["Scene drawing<br/>[scene.js]"]
  node_grid_tools["Grid toolkit<br/>[kit.js]"]
end

node_user(("User"))

node_user -->|"runs command"| node_cli
node_user -->|"embeds element"| node_web
node_user -->|"imports piece"| node_js_api
node_cli -->|"loads pieces"| node_catalog
node_cli -->|"restyles frames"| node_glyphs
node_cli -->|"plays frames"| node_terminal_output
node_cli -->|"copies prompt"| node_prompt
node_prompt -->|"copies to clipboard"| node_user
node_web -->|"starts playback"| node_player
node_player -->|"loads piece"| node_catalog
node_player -->|"restyles frames"| node_glyphs
node_player -->|"paints frames"| node_canvas
node_js_api -->|"selects piece"| node_catalog
node_catalog -->|"draws with"| node_grid_tools
node_scene_pieces -->|"draws with"| node_grid_tools
node_image_pieces -->|"animates image"| node_image_motion
node_scene_tools -->|"uses utilities"| node_grid_tools
node_image_pieces -.->|"exports frames"| node_canvas
node_js_api -.->|"exports media"| node_canvas

click node_cli "https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js"
click node_web "https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/ascii.js"
click node_js_api "https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces"
click node_prompt "https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js"
click node_catalog "https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces"
click node_scene_pieces "https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces"
click node_image_pieces "https://github.com/kailashsr38/ascii-magic-art/blob/main/pieces/ocean-sunset.js"
click node_image_motion "https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/image.js"
click node_scene_tools "https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/scene.js"
click node_grid_tools "https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/kit.js"
click node_player "https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/player.js"
click node_glyphs "https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/glyphs.js"
click node_canvas "https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/canvas.js"
click node_terminal_output "https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js"

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_cli,node_web,node_js_api,node_prompt,node_user toneBlue
class node_catalog,node_scene_pieces,node_image_pieces toneAmber
class node_player,node_glyphs,node_canvas,node_terminal_output toneMint
class node_image_motion,node_scene_tools,node_grid_tools toneRose
```

## Components

### User entry points

- [Terminal CLI](https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js): `bin/cli.js`
- [Web element](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/ascii.js): `runtime/ascii.js`
- [JavaScript API](https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces): `pieces`
- [Piece prompts](https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js): `bin/cli.js`

### Art catalog

- [Piece catalog](https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces): `pieces`
- [Scene pieces](https://github.com/kailashsr38/ascii-magic-art/tree/main/pieces): `pieces`
- [Photo scenes](https://github.com/kailashsr38/ascii-magic-art/blob/main/pieces/ocean-sunset.js): `pieces/ocean-sunset.js`

### Frame and render runtime

- [Web player](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/player.js): `runtime/player.js`
- [Look restyling](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/glyphs.js): `runtime/glyphs.js`
- [Canvas renderer](https://github.com/kailashsr38/ascii-magic-art/blob/main/runtime/canvas.js): `runtime/canvas.js`
- [Terminal playback](https://github.com/kailashsr38/ascii-magic-art/blob/main/bin/cli.js): `bin/cli.js`

### Drawing toolkit

- [Image animation](https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/image.js): `lib/image.js`
- [Scene drawing](https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/scene.js): `lib/scene.js`
- [Grid toolkit](https://github.com/kailashsr38/ascii-magic-art/blob/main/lib/kit.js): `lib/kit.js`

### Other components

- **User**

## Connections

- User → Terminal CLI: runs command (evidence: `README.md`)
- User → Web element: embeds element (evidence: `README.md`)
- User → JavaScript API: imports piece (evidence: `README.md`)
- Terminal CLI → Piece catalog: loads pieces (evidence: `bin/cli.js`)
- Terminal CLI → Look restyling: restyles frames (evidence: `bin/cli.js`)
- Terminal CLI → Terminal playback: plays frames (evidence: `README.md`)
- Terminal CLI → Piece prompts: copies prompt (evidence: `README.md`)
- Piece prompts → User: copies to clipboard (evidence: `README.md`)
- Web element → Web player: starts playback (evidence: `README.md`)
- Web player → Piece catalog: loads piece (evidence: `runtime/player.js`)
- Web player → Look restyling: restyles frames (evidence: `runtime/player.js`)
- Web player → Canvas renderer: paints frames (evidence: `runtime/player.js`)
- JavaScript API → Piece catalog: selects piece (evidence: `README.md`)
- Piece catalog → Grid toolkit: draws with (evidence: `pieces/ci-pipeline.js`)
- Scene pieces → Grid toolkit: draws with (evidence: `pieces/chai-stall-dawn.js`)
- Photo scenes → Image animation: animates image (evidence: `pieces/ocean-sunset.js`)
- Scene drawing → Grid toolkit: uses utilities (evidence: `lib/scene.js`)
- Photo scenes → Canvas renderer: exports frames (evidence: `README.md`)
- JavaScript API → Canvas renderer: exports media (evidence: `README.md`)
