# hf1nacl/volumepackcaculator architecture

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

- Interactive diagram: https://gitdiagram.com/hf1nacl/volumepackcaculator
- Repository: https://github.com/hf1nacl/volumepackcaculator

## Overview

1. **Repository type and delivery model**
   - This is a small **client-side JavaScript application** built with **Vite** and deployed as a static site.
   - The runtime is the browser; there is no backend, database, or API layer in the repository.
   - The `docs/` folder contains the built static output, suggesting GitHub Pages or a similar static hosting target.

2. **Entry points and page structure**
   - The app has a top-level `index.html` plus HTML fragments under `src/html/` for the main screens:
     - `containers.html`
     - `containers-custom.html`
     - `error.html`
   - `src/main.js` and `src/js/index.js` are the bootstrap points that wire the HTML, styles, and behavior together.
   - The architecture is page-driven rather than component-framework-driven.

3. **Core domain: volume and packing**
   - The repository’s main business logic is about **calculating container volume** and determining **how many boxes fit inside** a container.
   - The README explicitly describes the goal as measuring volumetric efficiency and estimating packing capacity.
   - This domain is implemented through calculation modules in `src/js/calcs/` and packing-specific logic in `src/js/containers/`.

4. **Calculation layer**
   - `src/js/calcs/math-calcs.js` likely contains the pure math helpers for volume, dimensions, and related numeric operations.
   - `src/js/calcs/window-calcs.js` appears to support calculations tied to viewport/window sizing, likely used to adapt layout or render scale.
   - These modules are the clearest “logic boundary” in the repo: they should be largely free of DOM concerns and reused by multiple screens.

5. **Packing and container orchestration**
   - The `src/js/containers/` folder contains the application’s main packing workflow:
     - `box-packing.js`
     - `containers-boxes.js`
     - `custom-boxes.js`
     - `settings.js`
   - This layer coordinates user selections, box definitions, packing constraints, and the output shown to the user.
   - It sits between the pure math helpers and the rendering/UI layer.

6. **Standard vs custom container flows**
   - The presence of both `containers.html` and `containers-custom.html` indicates two main user paths:
     - a standard container flow with predefined container/box sets
     - a custom-box flow with user-defined dimensions
   - The README’s limitation notes for custom boxes are important architecture constraints:
     - maximum 25 boxes
     - no rotation
     - heuristic packing that may not find all valid packings
   - That means the custom-box path is intentionally constrained and computationally lighter than a fully optimal packing engine.

7. **Visualization layer**
   - `src/js/containers/draw-isometric-view.js` is the rendering subsystem for the 3D/isometric visualization.
   - The README notes the use of the external **`@elchininet/isometric`** package, which likely powers this visual representation.
   - This layer is separate from the packing logic: calculations determine what fits, and the isometric renderer displays the result.

8. **UI behavior and app state**
   - `src/js/darkMode.js` is a focused UI concern for theme switching.
   - `src/js/containers/settings.js` suggests user-configurable packing or display parameters.
   - These modules indicate that app state is managed in small, feature-specific scripts rather than a centralized state store.

9. **Styling and assets**
   - `src/style.css` holds the application styling, with Bootstrap mentioned in the README as part of the UI stack.
   - `src/assets/` contains local assets used by the app.
   - The `docs/assets/` build artifacts show the final bundled JS/CSS generated by Vite.

10. **Build and packaging**
   - `vite.config.js` defines the build setup.
   - `package.json` and `package-lock.json` indicate a standard npm-managed build pipeline.
   - The architecture is optimized for static bundling: source in `src/`, compiled output in `docs/`, and no server-side runtime.

11. **Operational boundaries**
   - External dependency usage is narrow and purposeful: the isometric visualization package is the main nontrivial library called out in the README.
   - Bootstrap is used for layout/UI, but the core application behavior remains custom JS.
   - This keeps the app self-contained and easy to host, but also means complex packing behavior is implemented in-browser.

12. **How data moves through the app**
   - User input enters through the HTML screens.
   - Container/box dimensions and settings are passed into the calculation modules.
   - Packing results are produced by the packing logic.
   - The visualization layer converts those results into an isometric display.
   - Any responsive or theme-related behavior is handled alongside this flow by window/dark-mode helpers.

Main entry points: [`src/js/index.js`](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/index.js) (index.js), [`src/js/containers/box-packing.js`](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/box-packing.js) (Box packing), [`src/main.js`](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/main.js) (main.js), [`src/js/containers/draw-isometric-view.js`](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/draw-isometric-view.js) (Isometric view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Browser app"]
  node_n_index_html["index.html<br/>entry page<br/>[index.html]"]
  node_n_main_js["main.js<br/>bootstrap<br/>[main.js]"]
  node_n_index_js["index.js<br/>app init<br/>[index.js]"]
  node_n_html_containers["Containers<br/>screen template<br/>[containers.html]"]
  node_n_html_custom["Custom boxes<br/>screen template"]
  node_n_html_error["Error page<br/>screen template<br/>[error.html]"]
  node_n_dark_mode["Dark mode<br/>ui toggle<br/>[darkMode.js]"]
end

subgraph group_grp_domain["Packing domain"]
  node_n_math_calcs["Math calcs<br/>pure calculations<br/>[math-calcs.js]"]
  node_n_window_calcs["Window calcs<br/>layout calculations<br/>[window-calcs.js]"]
  node_n_box_packing["Box packing<br/>packing engine<br/>[box-packing.js]"]
  node_n_containers_boxes["Containers/boxes<br/>standard packing"]
  node_n_custom_boxes["Custom boxes<br/>custom packing<br/>[custom-boxes.js]"]
  node_n_draw_iso["Isometric view<br/>renderer"]
  node_n_settings["Settings<br/>ui state<br/>[settings.js]"]
end

subgraph group_grp_assets["Styles and assets"]
  node_n_style["style.css<br/>global styles<br/>[style.css]"]
  node_n_assets["Assets"]
end

subgraph group_grp_build["Build and output"]
  node_n_vite["Vite config<br/>build config<br/>[vite.config.js]"]
  node_n_docs["docs build<br/>static output"]
end

node_n_index_html -->|"loads"| node_n_main_js
node_n_main_js -->|"initializes"| node_n_index_js
node_n_index_js -->|"mounts"| node_n_html_containers
node_n_index_js -->|"mounts"| node_n_html_custom
node_n_index_js -->|"routes"| node_n_html_error
node_n_index_js -->|"toggles"| node_n_dark_mode
node_n_index_js -->|"applies"| node_n_style
node_n_containers_boxes -->|"uses"| node_n_math_calcs
node_n_custom_boxes -->|"uses"| node_n_math_calcs
node_n_box_packing -->|"computes"| node_n_math_calcs
node_n_box_packing -->|"reads"| node_n_settings
node_n_containers_boxes -->|"orchestrates"| node_n_box_packing
node_n_custom_boxes -->|"orchestrates"| node_n_box_packing
node_n_box_packing -->|"renders"| node_n_draw_iso
node_n_draw_iso -->|"uses"| node_n_assets
node_n_window_calcs -->|"supports"| node_n_draw_iso
node_n_main_js -->|"built by"| node_n_vite
node_n_vite -->|"outputs"| node_n_docs
node_n_style -->|"bundled into"| node_n_docs

click node_n_index_html "https://github.com/hf1nacl/volumepackcaculator/blob/main/index.html"
click node_n_main_js "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/main.js"
click node_n_index_js "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/index.js"
click node_n_html_containers "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/containers.html"
click node_n_html_custom "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/containers-custom.html"
click node_n_html_error "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/error.html"
click node_n_math_calcs "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/calcs/math-calcs.js"
click node_n_window_calcs "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/calcs/window-calcs.js"
click node_n_box_packing "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/box-packing.js"
click node_n_containers_boxes "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/containers-boxes.js"
click node_n_custom_boxes "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/custom-boxes.js"
click node_n_draw_iso "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/draw-isometric-view.js"
click node_n_settings "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/settings.js"
click node_n_dark_mode "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/darkMode.js"
click node_n_style "https://github.com/hf1nacl/volumepackcaculator/blob/main/src/style.css"
click node_n_assets "https://github.com/hf1nacl/volumepackcaculator/tree/main/src/assets"
click node_n_vite "https://github.com/hf1nacl/volumepackcaculator/blob/main/vite.config.js"
click node_n_docs "https://github.com/hf1nacl/volumepackcaculator/tree/main/docs"

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_n_index_html,node_n_main_js,node_n_index_js,node_n_html_containers,node_n_html_custom,node_n_html_error,node_n_dark_mode toneBlue
class node_n_math_calcs,node_n_window_calcs,node_n_box_packing,node_n_containers_boxes,node_n_custom_boxes,node_n_draw_iso,node_n_settings toneAmber
class node_n_style,node_n_assets toneMint
class node_n_vite,node_n_docs toneRose
```

## Components

### Browser app

Client-side runtime and page entrypoints

- [index.html](https://github.com/hf1nacl/volumepackcaculator/blob/main/index.html): entry page · Top-level HTML entry for the static app · `index.html`
- [main.js](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/main.js): bootstrap · Primary browser bootstrap that wires the app together · `src/main.js`
- [index.js](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/index.js): app init · Central app initialization and page-level wiring · `src/js/index.js`
- [Containers](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/containers.html): screen template · Main container packing screen markup · `src/html/containers.html`
- [Custom boxes](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/containers-custom.html): screen template · Custom container and box screen markup · `src/html/containers-custom.html`
- [Error page](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/html/error.html): screen template · Fallback or error-screen markup · `src/html/error.html`
- [Dark mode](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/darkMode.js): ui toggle · Theme switching behavior for the interface · `src/js/darkMode.js`

### Packing domain

Calculation, packing, and visualization logic

- [Math calcs](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/calcs/math-calcs.js): pure calculations · Volume, dimensions, and other numeric helpers · `src/js/calcs/math-calcs.js`
- [Window calcs](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/calcs/window-calcs.js): layout calculations · Viewport and sizing calculations for responsive behavior · `src/js/calcs/window-calcs.js`
- [Box packing](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/box-packing.js): packing engine · Core packing workflow that determines fit and arrangement · `src/js/containers/box-packing.js`
- [Containers/boxes](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/containers-boxes.js): standard packing · Standard container and box set orchestration · `src/js/containers/containers-boxes.js`
- [Custom boxes](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/custom-boxes.js): custom packing · User-defined box flow with constrained heuristic packing · `src/js/containers/custom-boxes.js`
- [Isometric view](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/draw-isometric-view.js): renderer · Isometric 3D-style visualization of packing results · `src/js/containers/draw-isometric-view.js`
- [Settings](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/js/containers/settings.js): ui state · Packing and display settings used by container flows · `src/js/containers/settings.js`

### Styles and assets

Shared styling and static assets

- [style.css](https://github.com/hf1nacl/volumepackcaculator/blob/main/src/style.css): global styles · Application-wide styling and layout rules · `src/style.css`
- [Assets](https://github.com/hf1nacl/volumepackcaculator/tree/main/src/assets): static assets · Local images and other bundled assets · `src/assets`

### Build and output

Vite configuration and generated static site

- [Vite config](https://github.com/hf1nacl/volumepackcaculator/blob/main/vite.config.js): build config · Build and dev server configuration · `vite.config.js`
- [docs build](https://github.com/hf1nacl/volumepackcaculator/tree/main/docs): static output · Generated static site output for hosting · `docs`

## Connections

- index.html → main.js: loads · HTML entry loads the browser bootstrap
- main.js → index.js: initializes · Bootstrap hands off to app initialization
- index.js → Containers: mounts · Wires the standard packing screen
- index.js → Custom boxes: mounts · Wires the custom packing screen
- index.js → Error page: routes · Uses error markup for fallback states
- index.js → Dark mode: toggles · Connects theme behavior to the app
- index.js → style.css: applies · Pairs page behavior with shared styling
- Containers/boxes → Math calcs: uses · Standard flow depends on numeric volume helpers
- Custom boxes → Math calcs: uses · Custom packing uses shared math helpers
- Box packing → Math calcs: computes · Core packing logic builds on volume and dimension math
- Box packing → Settings: reads · Packing behavior is parameterized by settings
- Containers/boxes → Box packing: orchestrates · Standard container flow invokes the packing engine
- Custom boxes → Box packing: orchestrates · Custom box flow invokes constrained packing
- Box packing → Isometric view: renders · Packing results are visualized in isometric form
- Isometric view → Assets: uses · Visualization can draw from bundled static assets
- Window calcs → Isometric view: supports · Responsive sizing helps the renderer fit the viewport
- main.js → Vite config: built by · Source entry is bundled through Vite
- Vite config → docs build: outputs · Build artifacts are emitted to the static docs site
- style.css → docs build: bundled into · Styles are compiled into the generated static site
