# astrum-forge/bvx-kit architecture

> Architecture diagram of the GitHub repository astrum-forge/bvx-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/astrum-forge/bvx-kit
- Repository: https://github.com/astrum-forge/bvx-kit

## Overview

##### Project Type and Purpose
- This is an open-source, renderer-agnostic TypeScript library (npm package) called **BitVoxel Engine**.
- Its purpose is to provide a highly optimized voxel data management and rendering abstraction (separating meta-data from rendering state) for large, dynamic, destructible worlds.

##### File Structure Analysis
- Top level: CI/CD workflows (.github/workflows), packaging config (.gitignore, LICENSE, README.md), whitepaper, graphics assets.
- Core package: `bvx-kit/`
- `package.json`, `tsconfig.json`, `.npmignore` → build and publish configuration
- `src/index.ts` → public API exports
- `src/lib/` → main modules:
– `containers/` (bit-array, hash-grid)
– `engine/` (chunks, geometry, layer, raycaster, world-index, voxel-world)
– `geometry/` (generic BVX geometry abstractions + lookup tables)
– `math/` (various key generators: linear, Morton, etc.)
– `util/` (bit operations)
- `tests/` → unit tests for every module
- CI workflows: Jest testing, npm publish, tagging.

##### README Insights
- Emphasis on:
- **Meta-Data Abstraction** & **BitVoxel Layer** (1-bit state + n-bit meta data)
- **Geometry LUT** for precomputed mesh data (vertices, normals, indices)
- Generic interface allowing any renderer to hook into the engine

##### Key Components
a. Public API Layer
– Exposed classes/functions (MortonKey, VoxelChunk, VoxelWorld, etc.)
b. Core Modules
– Containers: BitArray, HashGrid
– Engine: Chunk classes, VoxelWorld, indexing, layer abstraction
– Geometry: BVX geometry API + LUT modules
– Math: Key generators (MortonKey, LinearKey)
– Util: Bit-ops helper functions
c. External Integrations
– Renderer (Three.js, WebGL, custom)
– Consumer application code (Game or Simulation)
d. Build & CI Pipeline
– TypeScript compile → Jest tests → npm publish
– GitHub Actions workflows

##### Relationships & Data Flow
1. Consumer code calls the **Public API** → constructs `VoxelWorld` & `VoxelChunk` via `MortonKey`.
2. `VoxelWorld` uses **HashGrid** container to store chunk references.
3. `VoxelChunk` internally uses **BitArray** + meta-data arrays to track voxel states.
4. On mesh generation requests, **Engine** modules (layer + raycaster) consult **Geometry LUT** and **Math** modules to build face geometry.
5. Resulting mesh data (vertices, normals, indices) is passed to external **Renderer**.

##### Architectural Patterns & Principles
- Layered modular architecture: clear separation between data containers, engine logic, geometry generation, and utilities.
- Dependency inversion: engine logic depends only on generic interfaces, so any renderer can plug in.
- Single Responsibility: each sub-folder/module has one clear concern.
- Fully unit-tested core to ensure reliability.

##### Detailed Component Breakdown (suggested grouping
- Public API Layer
[Index.ts exports: MortonKey, VoxelChunk, VoxelWorld, etc.]
- Data Containers
[BitArray] → bit-level state storage
[HashGrid] → spatial indexing of chunks
- Engine Core
[voxel-chunk.ts]
[layer/bvx-layer.ts]
[raycaster/voxel-raycaster.ts + voxel-ray.ts]
[world-index.ts + voxel-world.ts]
- Geometry Subsystem
[bvx-geometry.ts]
[lut: bvx-vertices.ts, bvx-indices.ts, bvx-normals.ts, bvx-uv.ts, flipped indices]
- Math Subsystem
[key.ts, linear-key.ts, morton-key.ts]
- Utilities
[bit-ops.ts]
- CI/CD (GitHub Actions)
[jest.yml, publish.yml, tag.yml]

##### Detail
- Every module grouping.
- How geometry LUT and math keys feed into engine.
- Do not over-complicate: group small helpers (util, math) but label them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Public API Layer
    subgraph "Public API Layer"
        API["Index.ts\nExports: MortonKey, VoxelChunk, VoxelWorld"]:::api
    end

    %% Data Containers
    subgraph "Data Containers"
        BA["BitArray"]:::containers
        HG["HashGrid"]:::containers
    end

    %% Engine Core
    subgraph "Engine Core"
        subgraph "Chunks"
            C0["voxel-chunk.ts"]:::engine
            C1["voxel-chunk-0.ts"]:::engine
            C2["voxel-chunk-8.ts"]:::engine
            C3["voxel-chunk-16.ts"]:::engine
            C4["voxel-chunk-32.ts"]:::engine
        end
        VI["voxel-index.ts"]:::engine
        WI["world-index.ts"]:::engine
        VW["voxel-world.ts"]:::engine
        BVXL["bvx-layer.ts"]:::engine
        subgraph "Raycasting"
            VR["voxel-ray.ts"]:::engine
            VRC["voxel-raycaster.ts"]:::engine
        end
        subgraph "Face Geometry Helpers"
            VFG["voxel-face-geometry.ts"]:::engine
            VG["voxel-geometry.ts"]:::engine
        end
    end

    %% Geometry Subsystem
    subgraph "Geometry Subsystem"
        BG["bvx-geometry.ts"]:::geometry
        subgraph "Lookup Tables"
            LI["bvx-indices.ts"]:::geometry
            LIF["bvx-indices-flipped.ts"]:::geometry
            LN["bvx-normals.ts"]:::geometry
            LU["bvx-uv.ts"]:::geometry
            LV["bvx-vertices.ts"]:::geometry
        end
    end

    %% Math Subsystem
    subgraph "Math Subsystem"
        MK["morton-key.ts"]:::math
        LK["linear-key.ts"]:::math
        K["key.ts"]:::math
    end

    %% Utilities
    subgraph "Utilities"
        BO["bit-ops.ts"]:::util
    end

    %% External Integrations
    subgraph "External Systems"
        CON["Consumer App"]:::external
        REN["Renderer"]:::external
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        Code["TypeScript Compile"]:::ci
        Test["Jest Tests"]:::ci
        Publish["npm Publish"]:::ci
    end

    %% Connections
    CON -->|"calls Public API"| API
    API -->|"uses"| VW
    API -->|"uses"| C0
    API -->|"uses"| MK
    VW -->|"stores chunks in"| HG
    C0 -->|"tracks state with"| BA
    VW -->|"indexes voxels via"| VI
    VW -->|"manages world via"| WI
    VW -->|"applies layer"| BVXL
    BVXL -->|"queries geometry"| VFG
    VFG -->|"computes geometry"| VG
    VG -->|"uses LUT"| LI
    VG -->|"uses LUT"| LIF
    VG -->|"uses LUT"| LN
    VG -->|"uses LUT"| LU
    VG -->|"uses LUT"| LV
    VFG -->|"requests keys from"| MK
    VFG -->|"requests keys from"| LK
    VFG -->|"requests keys from"| K
    VG -->|"outputs mesh"| REN
    Code -->|"runs"| Test
    Test -->|"on success"| Publish

    %% Click Events
    click API "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/index.ts"
    click BA "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/containers/bit-array.ts"
    click HG "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/containers/hash-grid.ts"
    click C0 "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/chunks/voxel-chunk.ts"
    click C1 "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/chunks/voxel-chunk-0.ts"
    click C2 "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/chunks/voxel-chunk-8.ts"
    click C3 "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/chunks/voxel-chunk-16.ts"
    click C4 "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/chunks/voxel-chunk-32.ts"
    click VI "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/voxel-index.ts"
    click WI "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/world-index.ts"
    click VW "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/voxel-world.ts"
    click BVXL "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/layer/bvx-layer.ts"
    click VR "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/raycaster/voxel-ray.ts"
    click VRC "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/raycaster/voxel-raycaster.ts"
    click VFG "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/geometry/voxel-face-geometry.ts"
    click VG "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/engine/geometry/voxel-geometry.ts"
    click BG "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/bvx-geometry.ts"
    click LI "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/lut/bvx-indices.ts"
    click LIF "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/lut/bvx-indices-flipped.ts"
    click LN "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/lut/bvx-normals.ts"
    click LU "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/lut/bvx-uv.ts"
    click LV "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/geometry/lut/bvx-vertices.ts"
    click MK "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/math/morton-key.ts"
    click LK "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/math/linear-key.ts"
    click K "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/math/key.ts"
    click BO "https://github.com/astrum-forge/bvx-kit/blob/main/bvx-kit/src/lib/util/bit-ops.ts"
    click Test "https://github.com/astrum-forge/bvx-kit/blob/main/.github/workflows/jest.yml"
    click Publish "https://github.com/astrum-forge/bvx-kit/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef api fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
    classDef containers fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20
    classDef engine fill:#FFF9C4,stroke:#F57F17,color:#F57F17
    classDef geometry fill:#E1BEE7,stroke:#6A1B9A,color:#6A1B9A
    classDef math fill:#F8BBD0,stroke:#880E4F,color:#880E4F
    classDef util fill:#CFD8DC,stroke:#37474F,color:#37474F
    classDef external fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef ci fill:#B3E5FC,stroke:#01579B,color:#01579B
```
