# dinhducquan/neonplan3d architecture

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

- Interactive diagram: https://gitdiagram.com/dinhducquan/neonplan3d
- Repository: https://github.com/dinhducquan/neonplan3d

## Overview

NeonPlan 3D is a Home Assistant integration for drawing and maintaining a home plan, then viewing and controlling it in an interactive 3D dashboard. The main user workflow is to create floors, rooms and fixtures in the editor, save the plan and associated assets, and explore the result in the live view or dashboard card. The repository also includes device and environmental overlays, furniture packs, kiosk features, and optional Pro extensions. Several frontend subsystems are represented by their exact paths, but their internal wiring is omitted where the excerpts do not establish it.

Main entry points: [`frontend/src/model.ts`](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/model.ts) (Building model), [`frontend/src/viewer/viewer3d.ts`](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/viewer3d.ts) (3D viewer), [`frontend/src/solar.ts`](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/solar.ts) (Sunlight model), [`frontend/src/viewer/furniture.ts`](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/furniture.ts) (Furniture rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Plan creation"]
  node_editor["Plan editor<br/>[editor.ts]"]
  node_card_editor["Card editor<br/>[card-editor.ts]"]
  node_card["Dashboard card<br/>[card.ts]"]
end

subgraph group_domain["Plan and geometry"]
  node_schema["Plan schema<br/>[schema.py]"]
  node_model["Building model<br/>[model.ts]"]
  node_walls["Wall geometry<br/>[walls.ts]"]
  node_roof_sections["Roof sections<br/>[roof-sections.ts]"]
  node_solar["Sunlight model<br/>[solar.ts]"]
end

subgraph group_rendering["3D experience"]
  node_viewer["3D viewer<br/>[viewer3d.ts]"]
  node_furniture["Furniture rendering<br/>[furniture.ts]"]
  node_geo["3D geometry buffers<br/>[geo.ts]"]
end

subgraph group_integration["Home Assistant integration"]
  node_api["Frontend API<br/>[api.ts]"]
  node_building_controller["Plan sync"]
  node_ws["WebSocket handlers<br/>[websocket.py]"]
  node_storage[("Plan storage<br/>[storage.py]")]
end

subgraph group_extras["Live features"]
  node_devices["Entity mapping<br/>[devices.ts]"]
  node_parking["Parking model<br/>[parking.ts]"]
  node_weather["Weather effects<br/>[weather.ts]"]
  node_heatmap["Sensor heatmap<br/>[heatmap.ts]"]
  node_packs["Furniture packs<br/>[packs.ts]"]
  node_extensions["Extensions<br/>[extensions.ts]"]
end

node_ha_user(("Home Assistant user"))
node_ha(("Home Assistant"))

node_ha_user -->|"draws plan"| node_editor
node_ha_user -->|"configures card"| node_card_editor
node_ha_user -->|"views plan"| node_card
node_editor -->|"generates walls"| node_walls
node_building_controller -->|"loads and saves"| node_api
node_building_controller -->|"normalizes plan"| node_model
node_ws -->|"accesses stores"| node_storage
node_storage -->|"completes building"| node_schema
node_model -->|"resolves pack items"| node_packs
node_solar -->|"reads plan geometry"| node_model
node_solar -->|"uses wall geometry"| node_walls
node_solar -->|"uses roof sections"| node_roof_sections
node_furniture -->|"uses furniture data"| node_model
node_furniture -->|"resolves pack models"| node_packs
node_furniture -->|"builds buffers"| node_geo
node_viewer -->|"renders furniture"| node_furniture
node_viewer -->|"uses sunlight model"| node_solar
node_viewer -->|"uses parking model"| node_parking
node_viewer -->|"renders building"| node_model
node_ha -->|"provides entity states"| node_devices
node_ha -.->|"provides weather data"| node_weather
node_ha -.->|"provides sensor data"| node_heatmap
node_ha_user -->|"manages add-ons"| node_extensions
node_extensions -->|"checks pack updates"| node_ha

click node_editor "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/components/editor.ts"
click node_card_editor "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/card-editor.ts"
click node_card "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/card.ts"
click node_api "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/api.ts"
click node_building_controller "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/building-controller.ts"
click node_ws "https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/websocket.py"
click node_storage "https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/storage.py"
click node_schema "https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/schema.py"
click node_model "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/model.ts"
click node_walls "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/geometry/walls.ts"
click node_roof_sections "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/roof-sections.ts"
click node_solar "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/solar.ts"
click node_viewer "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/viewer3d.ts"
click node_furniture "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/furniture.ts"
click node_geo "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/geo.ts"
click node_devices "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/devices.ts"
click node_parking "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/parking.ts"
click node_weather "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/weather.ts"
click node_heatmap "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/heatmap.ts"
click node_packs "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/packs.ts"
click node_extensions "https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/components/extensions.ts"

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_editor,node_card_editor,node_card,node_ha_user toneBlue
class node_schema,node_model,node_walls,node_roof_sections,node_solar toneAmber
class node_viewer,node_furniture,node_geo toneMint
class node_api,node_building_controller,node_ws,node_storage toneRose
class node_devices,node_parking,node_weather,node_heatmap,node_packs,node_extensions,node_ha toneIndigo
```

## Components

### Plan creation

- [Plan editor](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/components/editor.ts): `frontend/src/components/editor.ts`
- [Card editor](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/card-editor.ts): `frontend/src/card-editor.ts`
- [Dashboard card](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/card.ts): `frontend/src/card.ts`

### Plan and geometry

- [Plan schema](https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/schema.py): `custom_components/neonplan3d/schema.py`
- [Building model](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/model.ts): `frontend/src/model.ts`
- [Wall geometry](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/geometry/walls.ts): `frontend/src/geometry/walls.ts`
- [Roof sections](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/roof-sections.ts): `frontend/src/roof-sections.ts`
- [Sunlight model](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/solar.ts): `frontend/src/solar.ts`

### 3D experience

- [3D viewer](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/viewer3d.ts): `frontend/src/viewer/viewer3d.ts`
- [Furniture rendering](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/furniture.ts): `frontend/src/viewer/furniture.ts`
- [3D geometry buffers](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/viewer/geo.ts): `frontend/src/viewer/geo.ts`

### Home Assistant integration

- [Frontend API](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/api.ts): `frontend/src/api.ts`
- [Plan sync](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/building-controller.ts): `frontend/src/building-controller.ts`
- [WebSocket handlers](https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/websocket.py): `custom_components/neonplan3d/websocket.py`
- [Plan storage](https://github.com/dinhducquan/neonplan3d/blob/main/custom_components/neonplan3d/storage.py): `custom_components/neonplan3d/storage.py`

### Live features

- [Entity mapping](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/devices.ts): `frontend/src/devices.ts`
- [Parking model](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/parking.ts): `frontend/src/parking.ts`
- [Weather effects](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/weather.ts): `frontend/src/weather.ts`
- [Sensor heatmap](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/heatmap.ts): `frontend/src/heatmap.ts`
- [Furniture packs](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/packs.ts): `frontend/src/packs.ts`
- [Extensions](https://github.com/dinhducquan/neonplan3d/blob/main/frontend/src/components/extensions.ts): `frontend/src/components/extensions.ts`

### Other components

- **Home Assistant user**
- **Home Assistant**

## Connections

- Home Assistant user → Plan editor: draws plan (evidence: `README.md`)
- Home Assistant user → Card editor: configures card (evidence: `README.md`)
- Home Assistant user → Dashboard card: views plan (evidence: `README.md`)
- Plan editor → Wall geometry: generates walls (evidence: `frontend/src/components/editor.ts`)
- Plan sync → Frontend API: loads and saves (evidence: `frontend/src/building-controller.ts`)
- Plan sync → Building model: normalizes plan (evidence: `frontend/src/building-controller.ts`)
- WebSocket handlers → Plan storage: accesses stores (evidence: `custom_components/neonplan3d/websocket.py`)
- Plan storage → Plan schema: completes building (evidence: `custom_components/neonplan3d/storage.py`)
- Building model → Furniture packs: resolves pack items (evidence: `frontend/src/model.ts`)
- Sunlight model → Building model: reads plan geometry (evidence: `frontend/src/solar.ts`)
- Sunlight model → Wall geometry: uses wall geometry (evidence: `frontend/src/solar.ts`)
- Sunlight model → Roof sections: uses roof sections (evidence: `frontend/src/solar.ts`)
- Furniture rendering → Building model: uses furniture data (evidence: `frontend/src/viewer/furniture.ts`)
- Furniture rendering → Furniture packs: resolves pack models (evidence: `frontend/src/viewer/furniture.ts`)
- Furniture rendering → 3D geometry buffers: builds buffers (evidence: `frontend/src/viewer/furniture.ts`)
- 3D viewer → Furniture rendering: renders furniture (evidence: `frontend/src/viewer/viewer3d.ts`)
- 3D viewer → Sunlight model: uses sunlight model (evidence: `frontend/src/viewer/viewer3d.ts`)
- 3D viewer → Parking model: uses parking model (evidence: `frontend/src/viewer/viewer3d.ts`)
- 3D viewer → Building model: renders building (evidence: `frontend/src/viewer/viewer3d.ts`)
- Home Assistant → Entity mapping: provides entity states (evidence: `README.md`)
- Home Assistant → Weather effects: provides weather data
- Home Assistant → Sensor heatmap: provides sensor data
- Home Assistant user → Extensions: manages add-ons (evidence: `README.md`)
- Extensions → Home Assistant: checks pack updates (evidence: `README.md`)
