# w3ndo/jigsaw architecture

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

- Interactive diagram: https://gitdiagram.com/w3ndo/jigsaw
- Repository: https://github.com/w3ndo/jigsaw

## Overview

Jigsaw is a proof-of-concept Phoenix LiveView tiling library. Its principal workflow is for an application to create and manipulate a BSP layout, then pass that layout and matching pane slots to the LiveView component for rendering. The layout engine also supports querying and validation. The repository includes a demo dashboard, but its implementation was not sampled; its connection to the library is therefore shown as unverified. Relationships in the core workflow are supported by the README and excerpts.

Main entry points: [`apps/jigsaw/lib/bsp/layout.ex`](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/bsp/layout.ex) (Layout API), [`apps/jigsaw/lib/jigsaw_components/components.ex`](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/jigsaw_components/components.ex) (Layout component), [`apps/jigsaw/lib/bsp`](https://github.com/w3ndo/jigsaw/tree/main/apps/jigsaw/lib/bsp) (BSP tree types), [`apps/demo/lib/demo/live/home/home.ex`](https://github.com/w3ndo/jigsaw/blob/main/apps/demo/lib/demo/live/home/home.ex) (Demo dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_layout["Layout engine"]
  node_api["Layout API<br/>[layout.ex]"]
  node_tree["BSP tree types"]
  node_ids["ID generator<br/>[id.ex]"]
  node_validation["Validation errors"]
end

subgraph group_render["LiveView rendering"]
  node_components["Layout component<br/>[components.ex]"]
end

subgraph group_demo["Example dashboard"]
  node_dashboard["Demo dashboard<br/>[home.ex]"]
end

node_consumer(("Application developer"))

node_consumer -->|"manipulates layout"| node_api
node_api -->|"uses tree structs"| node_tree
node_api -->|"generates IDs"| node_ids
node_api -->|"returns errors"| node_validation
node_consumer -->|"supplies layout and slots"| node_components
node_components -->|"renders tree structs"| node_tree
node_dashboard -.->|"uses rendering API"| node_components

click node_api "https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/bsp/layout.ex"
click node_tree "https://github.com/w3ndo/jigsaw/tree/main/apps/jigsaw/lib/bsp"
click node_ids "https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/types/id.ex"
click node_validation "https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/types/validation_error.ex"
click node_components "https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/jigsaw_components/components.ex"
click node_dashboard "https://github.com/w3ndo/jigsaw/blob/main/apps/demo/lib/demo/live/home/home.ex"

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_api,node_tree,node_ids,node_validation toneBlue
class node_components toneAmber
class node_dashboard toneMint
class node_consumer toneIndigo
```

## Components

### Layout engine

- [Layout API](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/bsp/layout.ex): `apps/jigsaw/lib/bsp/layout.ex`
- [BSP tree types](https://github.com/w3ndo/jigsaw/tree/main/apps/jigsaw/lib/bsp): `apps/jigsaw/lib/bsp`
- [ID generator](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/types/id.ex): `apps/jigsaw/lib/types/id.ex`
- [Validation errors](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/types/validation_error.ex): `apps/jigsaw/lib/types/validation_error.ex`

### LiveView rendering

- [Layout component](https://github.com/w3ndo/jigsaw/blob/main/apps/jigsaw/lib/jigsaw_components/components.ex): `apps/jigsaw/lib/jigsaw_components/components.ex`

### Example dashboard

- [Demo dashboard](https://github.com/w3ndo/jigsaw/blob/main/apps/demo/lib/demo/live/home/home.ex): `apps/demo/lib/demo/live/home/home.ex`

### Other components

- **Application developer**

## Connections

- Application developer → Layout API: manipulates layout (evidence: `README.md`)
- Layout API → BSP tree types: uses tree structs (evidence: `apps/jigsaw/lib/bsp/layout.ex`)
- Layout API → ID generator: generates IDs (evidence: `apps/jigsaw/lib/bsp/layout.ex`)
- Layout API → Validation errors: returns errors (evidence: `apps/jigsaw/lib/bsp/layout.ex`)
- Application developer → Layout component: supplies layout and slots (evidence: `README.md`)
- Layout component → BSP tree types: renders tree structs (evidence: `apps/jigsaw/lib/jigsaw_components/components.ex`)
- Demo dashboard → Layout component: uses rendering API