Merge pull request #10 from jcreek/dependabot/github_actions/actions/setup-node-6

build(deps): bump actions/setup-node from 4 to 6

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/docker.yml

@@ -16,7 +16,7 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3

.github/workflows/dockerhub-description.yml

@@ -0,0 +1,59 @@
+name: Docker Hub Description
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - README.md
+      - .github/workflows/dockerhub-description.yml
+
+jobs:
+  dockerhub-description:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Preflight Docker Hub repository access
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_TOKEN }}
+          DOCKERHUB_REPOSITORY: jcreek23/open-network-diagram
+        run: |
+          set -euo pipefail
+
+          if [ -z "${DOCKERHUB_USERNAME}" ] || [ -z "${DOCKERHUB_PASSWORD}" ]; then
+            echo "Missing DOCKERHUB_USERNAME or DOCKERHUB_PASSWORD secret."
+            exit 1
+          fi
+
+          LOGIN_RESPONSE="$(curl -fsS -X POST \
+            -H 'Content-Type: application/json' \
+            -d "{\"username\":\"${DOCKERHUB_USERNAME}\",\"password\":\"${DOCKERHUB_PASSWORD}\"}" \
+            https://hub.docker.com/v2/users/login/)"
+
+          TOKEN="$(printf '%s' "${LOGIN_RESPONSE}" | ruby -rjson -e 'input = STDIN.read; data = JSON.parse(input); puts data.fetch("token", "")')"
+
+          if [ -z "${TOKEN}" ]; then
+            echo "Docker Hub login succeeded but token was missing."
+            exit 1
+          fi
+
+          curl -fsS \
+            -H "Authorization: JWT ${TOKEN}" \
+            "https://hub.docker.com/v2/repositories/${DOCKERHUB_REPOSITORY}/" >/dev/null
+
+          echo "Docker Hub preflight access check passed for ${DOCKERHUB_REPOSITORY}."
+
+      - name: Update Docker Hub repository overview
+        uses: peter-evans/dockerhub-description@v5
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: jcreek23/open-network-diagram
+          readme-filepath: ./README.md
+          enable-url-completion: true

.github/workflows/release.yml

@@ -27,18 +27,18 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
           node-version: 20
 
       - name: Create Git tag + GitHub release
         id: semantic
-        uses: cycjimmy/semantic-release-action@v5.0.2
+        uses: cycjimmy/semantic-release-action@v6
         with:
           extra_plugins: |
             @semantic-release/commit-analyzer
@@ -57,13 +57,13 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
       - name: Log in to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}

README.md

@@ -1,177 +1,147 @@
-# **Open Network Diagram**
+# Open Network Diagram
 
-![Docker Pulls](https://img.shields.io/docker/pulls/jcreek23/open-network-diagram)
+[![Docker Pulls](https://img.shields.io/docker/pulls/jcreek23/open-network-diagram)](https://hub.docker.com/r/jcreek23/open-network-diagram)
-![Release Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/release.yml?branch=main&label=release)
+[![Release Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/release.yml?branch=main&label=release)](https://github.com/jcreek/OpenNetworkDiagram/actions/workflows/release.yml)
-![Docker CI Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/docker.yml?label=docker%20ci)
+[![Docker CI Workflow](https://img.shields.io/github/actions/workflow/status/jcreek/OpenNetworkDiagram/docker.yml?label=docker%20ci)](https://github.com/jcreek/OpenNetworkDiagram/actions/workflows/docker.yml)
-![Latest Release](https://img.shields.io/github/v/release/jcreek/OpenNetworkDiagram?display_name=tag&sort=semver)
+[![Latest Release](https://img.shields.io/github/v/release/jcreek/OpenNetworkDiagram?display_name=tag&sort=semver)](https://github.com/jcreek/OpenNetworkDiagram/releases)
-![Netlify](https://img.shields.io/netlify/3128f05f-831b-412c-ada0-46bc3d6e61d5)
+[![Netlify](https://img.shields.io/netlify/3128f05f-831b-412c-ada0-46bc3d6e61d5)](https://opennetworkdiagram.jcreek.co.uk)
 
-**A declarative, self-hosted tool for visualising and managing home lab & network architecture diagrams.**
+**A declarative, self-hosted containerised tool for visualising and managing home lab & network architecture diagrams.**
 
----
+Open Network Diagram helps you document your infrastructure in a visual UI while keeping a real JSON source of truth you can version, back up, and reuse.
 
-## **📝 About**
+- Homelab-friendly: run it in minutes with Docker.
+- Practical: edit in the UI and autosave to `network.json`.
+- Declarative: keep your topology in Git if you wish.
 
-**Open Network Diagram** is an **open-source, self-hosted tool** for creating **interactive network and infrastructure diagrams** using a **declarative JSON format**.
+[Docker Hub](https://hub.docker.com/r/jcreek23/open-network-diagram) | [Live Demo (Read-Only)](https://opennetworkdiagram.jcreek.co.uk) | [GitHub Releases](https://github.com/jcreek/OpenNetworkDiagram/releases)
 
-✅ **Fully self-hostable via Docker**  
+![Open Network Diagram network view with ethernet labels](screenshot1.png)
-✅ **Docker-first deployment target** (Netlify optional for demo hosting)
-✅ **Interactive network visualisation**  
-✅ **Single-page modal editor with live updates**  
-✅ **Debounced autosave to JSON (self-hosted)**  
-✅ **Local vendored icon catalog (offline runtime)**  
-✅ **Lightweight Svelte**
 
-Use it to **document your home lab, office network, or cloud infrastructure** with an easy-to-use web interface.
+## Features
 
----
+- Network view with ethernet labels to make physical and logical links easy to read.
+- Non-network view for host-first inventory and service mapping.
+- Expandable VM lists per machine for quick virtualization visibility.
+- Modal editor for machines/devices with live diagram updates.
+- JSON-backed persistence with autosave in self-hosted mode.
+- Docker-first deployment with writable data volume support.
+- Optional read-only mode for public demos and safe sharing.
+- Local vendored icon catalog for offline-friendly runtime behavior.
 
-## **🚀 Quick Start (For Users)**
+## Why Home Lab Users Use It
 
-### **1️⃣ Create Your Runtime Data File**
+- Keep an always-up-to-date map of machines, VMs, and devices.
+- Edit quickly through a modal UI instead of hand-editing large diagrams.
+- Persist everything to JSON so backups and Git workflows stay simple.
+- Stay fully self-hosted with no runtime dependency on external APIs.
 
-Copy the template and edit your own network data:
+## 2-Minute Docker Quick Start
+
+This is the fastest way to run Open Network Diagram for a home lab.
+
+1. Create a local data folder and seed your first `network.json`:
 
 ```bash
-cp data/network.json.example data/network.json
+mkdir -p ond-data
+curl -fsSL https://raw.githubusercontent.com/jcreek/OpenNetworkDiagram/main/data/network.json.example -o ond-data/network.json
 ```
 
-### **2️⃣ Run Open Network Diagram via Docker**
+2. Run the published Docker image:
-
-From this repo:
 
 ```bash
-docker compose up --build
+docker run -d \
-```
+  --name open-network-diagram \
-
+  --restart unless-stopped \
-Or pull and run directly:
+  -p 8080:3000 \
-
-```bash
-docker run -d -p 8080:3000 \
   -e NETWORK_DATA_FILE=/app/data/network.json \
   -e NETWORK_BACKUP_DIR=/app/data/.backups \
-  -v "$(pwd)/data:/app/data" \
+  -v "$(pwd)/ond-data:/app/data" \
-  jcreek23/open-network-diagram
+  jcreek23/open-network-diagram:latest
 ```
 
-- **`-p 8080:3000`** → Maps the app to `http://localhost:8080`
+3. Open the app at `http://localhost:8080`.
-- **`-v .../data:/app/data`** → Uses your local writable `data/network.json`
 
-### **3️⃣ Open the Web UI**
+4. Edit your topology in the UI. Changes persist to `ond-data/network.json`.
 
-Visit **`http://localhost:8080`** to view your network diagram.
+Useful follow-up commands:
 
-### **4️⃣ Modify Your Network (Modal UI + JSON Persistence)**
+```bash
+docker logs -f open-network-diagram
+docker stop open-network-diagram
+docker rm open-network-diagram
+```
 
-- Edit machines/devices/VMs/ports directly in the modal UI.
+## What It Looks Like
-- Diagram updates immediately as you edit.
-- In self-hosted Docker/local mode, changes autosave to mounted **`data/network.json`**.
-- Netlify/demo is intentionally read-only; edits are in-memory only.
 
----
+| Network view with ethernet labels                                          | Non-network view with VMs expanded                                          | Modal editing a machine                                          |
+| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| ![Open Network Diagram network view with ethernet labels](screenshot1.png) | ![Open Network Diagram non-network view with VMs expanded](screenshot2.png) | ![Open Network Diagram modal editing a machine](screenshot3.png) |
 
-## **👩‍💻 Development Setup**
+## Docker Compose Option
 
-### **1️⃣ Clone the Repository**
+If you prefer compose:
+
+```yaml
+services:
+  open-network-diagram:
+    image: jcreek23/open-network-diagram:latest
+    ports:
+      - '8080:3000'
+    volumes:
+      - ./ond-data:/app/data
+    environment:
+      NETWORK_DATA_FILE: /app/data/network.json
+      NETWORK_BACKUP_DIR: /app/data/.backups
+    restart: unless-stopped
+```
+
+Start it with:
+
+```bash
+docker compose up -d
+```
+
+## For Developers
+
+### Local Development
 
 ```bash
 git clone https://github.com/jcreek/OpenNetworkDiagram.git
-cd open-network-diagram
+cd OpenNetworkDiagram
-```
-
-### **2️⃣ Install Dependencies**
-
-```bash
 pnpm install
-```
-
-### **3️⃣ Run in Development Mode**
-
-```bash
 pnpm run dev
 ```
 
-- Runs at `http://localhost:5173`
+App URL: `http://localhost:5173`
 
-### **4️⃣ Build Targets**
+### Build Targets
 
 ```bash
-pnpm run build          # default (Docker/static target)
+pnpm run build          # default build
-pnpm run build:docker   # explicit Docker/static target
+pnpm run build:docker   # Docker/static target
 pnpm run build:netlify  # Netlify target (read-only mode)
 pnpm run icons:manifest # regenerate local vendor icon manifest
 ```
 
----
+### Runtime and Persistence
 
-## **🛠️ Project Structure**
+- API endpoint: `GET/PUT /api/network-data`
+- Writes are enabled unless `NETWORK_READ_ONLY=true`
+- When writes are unavailable, API responses include `writableReason` for diagnostics.
+- Writes are persisted atomically to the configured data file
+- Rolling backups are kept in the backup directory (last 5)
 
-```text
+Environment variables:
-open-network-diagram/
-├── src/                    # Svelte app source
-├── src/lib/config/vendorIconManifest.ts # Generated local icon catalog
-├── static/data/network.json # Demo dataset (Netlify/demo)
-├── static/icons/vendor/     # Vendored icon assets (runtime-local)
-├── data/network.json.example # User data template (Docker)
-├── third_party/             # Third-party license/provenance notes
-├── Dockerfile              # Docker build/runtime
-├── server.mjs              # Node runtime server (static + /api/network-data)
-├── docker-compose.yml      # Local Docker run with mounted data
-├── netlify.toml            # Netlify build config
-├── .github/workflows/      # CI workflows (PR build + automated release/publish)
-└── README.md               # Documentation
-```
 
----
+- `NETWORK_READ_ONLY` (default: `false`)
+  - Set to `true` to disable writes and force read-only mode.
+- `NETWORK_DATA_FILE` (default: `data/network.json`)
+  - JSON file path to read/write.
+- `NETWORK_BACKUP_DIR` (default: `data/.backups`)
+  - Directory for backup files.
 
-## **📦 Docker Build & Deployment**
+### JSON Example
-
-### **Build the Docker Image Locally**
-
-```bash
-docker build -t open-network-diagram .
-```
-
-### **Run Locally**
-
-```bash
-docker run --rm -p 8080:3000 \
-  -e NETWORK_DATA_FILE=/app/data/network.json \
-  -e NETWORK_BACKUP_DIR=/app/data/.backups \
-  -v "$(pwd)/data:/app/data" \
-  open-network-diagram
-```
-
-### **Write API Environment Variables**
-
-- **`NETWORK_READ_ONLY`** (default: `false`)  
-  Set to `true` to disable `PUT /api/network-data` and force read-only mode.
-- **`NETWORK_DATA_FILE`** (default: `data/network.json`)  
-  JSON file path to read/write.
-- **`NETWORK_BACKUP_DIR`** (default: sibling `.backups`)  
-  Backup directory for rolling save backups (last 5 retained).
-
-### **Local Icon Catalog (No Runtime Network Dependency)**
-
-- Icons are vendored locally under **`static/icons/vendor/homarr/`**.
-- The searchable catalog is generated into **`src/lib/config/vendorIconManifest.ts`**.
-- Third-party provenance and licensing are documented in:
-  - **`third_party/homarr-dashboard-icons/SOURCE.txt`**
-  - **`third_party/homarr-dashboard-icons/LICENSE`**
-  - **`third_party/homarr-dashboard-icons/NOTICE.txt`**
-- Runtime icon search/rendering does not call external APIs.
-
-### **CI/CD (GitHub Actions + Netlify)**
-
-- GitHub Actions workflow (`.github/workflows/docker.yml`) builds Docker on PRs (validation only).
-- GitHub Actions workflow (`.github/workflows/release.yml`) runs on `main`, creates semantic version tags/releases, and publishes Docker images to **Docker Hub** (`jcreek23/open-network-diagram`).
-- Netlify uses its own CI/CD pipeline with `netlify.toml` (`pnpm run build:netlify`).
-
----
-
-## **📝 JSON Network Configuration Example**
-
-Define your network using **`network.json`**:
 
 ```json
 {
@@ -195,27 +165,37 @@ Define your network using **`network.json`**:
 }
 ```
 
----
+### Project Structure
 
-## **🤝 Contributing**
+```text
+OpenNetworkDiagram/
+├── src/                               # Svelte app source
+├── src/lib/config/vendorIconManifest.ts # Generated local icon catalog
+├── static/data/network.json           # Demo dataset (Netlify)
+├── static/icons/vendor/               # Vendored icon assets (runtime-local)
+├── data/network.json.example          # Starter data template for Docker users
+├── third_party/                       # Third-party provenance + licensing
+├── Dockerfile                         # Docker build/runtime image
+├── server.mjs                         # Node runtime server (static + API)
+├── docker-compose.yml                 # Local compose example (build from repo)
+├── netlify.toml                       # Netlify build config
+└── .github/workflows/                 # CI workflows
+```
 
-We welcome contributions! To contribute:
+### CI/CD
 
-1. **Fork the repository**.
+- `docker.yml`: validates Docker build on pull requests.
-2. **Create a feature branch** (`git checkout -b feature-name`).
+- `release.yml`: semantic release on `main` and Docker Hub publish for tagged releases.
-3. **Commit your changes** (`git commit -m "Add feature X"`).
+- Docker Hub image: [`jcreek23/open-network-diagram`](https://hub.docker.com/r/jcreek23/open-network-diagram)
-4. **Push to your fork** (`git push origin feature-name`).
-5. **Submit a Pull Request**.
 
----
+## Contributing
 
-## **📜 License**
+1. Fork the repository.
+2. Create a feature branch.
+3. Commit your changes.
+4. Push your branch.
+5. Open a pull request.
 
-[GNU GPL v3 License](LICENSE) – Free to use, modify, and distribute, except distributing closed source versions.
+## License
 
----
+[GNU GPL v3](LICENSE)
-
-## **📬 Contact**
-
-**Author:** [Joshua Creek](https://github.com/jcreek)  
-**Project Repo:** [GitHub](https://github.com/jcreek/OpenNetworkDiagram)

server.mjs

@@ -4,8 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { validateNetworkData } from './src/lib/shared/networkSchemaCore.mjs';
 import {
-	checkWritableState,
+	getWritableState,
-	isWriteEnabled,
 	readNetworkFile,
 	writeNetworkFile
 } from './src/lib/shared/networkPersistenceCore.mjs';
@@ -50,10 +49,17 @@ function badRequest(response, message, details) {
 	});
 }
 
+function resolveReadOnlyErrorMessage(reason) {
+	if (!reason) {
+		return 'Write API unavailable in current deployment.';
+	}
+	return `Write API unavailable: ${reason}`;
+}
+
 async function serveApi(request, response) {
 	if (request.method === 'GET') {
 		try {
-			const payload = await readNetworkFile();
+			const [payload, writableState] = await Promise.all([readNetworkFile(), getWritableState()]);
 			const validation = validateNetworkData(payload.data);
 			if (!validation.valid) {
 				sendJson(response, 500, {
@@ -63,11 +69,10 @@ async function serveApi(request, response) {
 				return;
 			}
 
-			const canWrite = await checkWritableState();
-
 			sendJson(response, 200, {
 				data: validation.data,
-				writable: canWrite,
+				writable: writableState.writable,
+				writableReason: writableState.reason,
 				source: payload.source,
 				updatedAt: payload.updatedAt
 			});
@@ -80,9 +85,12 @@ async function serveApi(request, response) {
 	}
 
 	if (request.method === 'PUT') {
-		if (!isWriteEnabled()) {
+		const writableStateBeforeWrite = await getWritableState();
+		if (!writableStateBeforeWrite.writable) {
 			sendJson(response, 403, {
-				error: 'Write API disabled. Unset NETWORK_READ_ONLY to enable persistence.'
+				error: resolveReadOnlyErrorMessage(writableStateBeforeWrite.reason),
+				writable: false,
+				writableReason: writableStateBeforeWrite.reason
 			});
 			return;
 		}
@@ -123,9 +131,11 @@ async function serveApi(request, response) {
 
 		try {
 			const metadata = await writeNetworkFile(validation.data);
+			const writableStateAfterWrite = await getWritableState();
 			sendJson(response, 200, {
 				data: validation.data,
-				writable: true,
+				writable: writableStateAfterWrite.writable,
+				writableReason: writableStateAfterWrite.reason,
 				source: metadata.source,
 				updatedAt: metadata.updatedAt
 			});

src/lib/components/NetworkDiagram.svelte

@@ -73,7 +73,8 @@
 	let saveState: SaveState = 'saved';
 	let dataSourceLabel = jsonPath;
 	let writable = false;
-	let readOnlyNotice = 'Read-only deployment; changes are not persisted.';
+	const defaultReadOnlyNotice = 'Read-only deployment; changes are not persisted.';
+	let readOnlyNotice = defaultReadOnlyNotice;
 
 	let showEthernetLabels = false;
 	let diagramViewMode: DiagramViewMode = 'network';
@@ -401,6 +402,13 @@
 		return 'Unexpected error';
 	}
 
+	function resolveReadOnlyNotice(reason: string | null | undefined): string {
+		if (!reason) {
+			return defaultReadOnlyNotice;
+		}
+		return `Read-only: ${reason}`;
+	}
+
 	function createGraphStyles(theme: ThemeMode): cytoscape.Stylesheet[] {
 		const nodeText = theme === 'dark' ? '#e2e8f0' : '#1e293b';
 		const textOutline = theme === 'dark' ? '#0f172a' : '#f8fafc';
@@ -976,8 +984,12 @@
 			});
 
 			if (response.status === 403) {
+				const body = (await response.json().catch(() => ({}))) as {
+					error?: string;
+					writableReason?: string | null;
+				};
 				writable = false;
-				readOnlyNotice = 'Read-only deployment; changes are not persisted.';
+				readOnlyNotice = resolveReadOnlyNotice(body.writableReason ?? body.error ?? null);
 				saveState = 'unsaved';
 				return;
 			}
@@ -998,10 +1010,14 @@
 			const body = (await response.json()) as {
 				data: NetworkData;
 				writable: boolean;
+				writableReason?: string | null;
 				source: string;
 				updatedAt: string;
 			};
 			writable = body.writable;
+			readOnlyNotice = body.writable
+				? defaultReadOnlyNotice
+				: resolveReadOnlyNotice(body.writableReason);
 			dataSourceLabel = body.source;
 			lastSavedSnapshot = JSON.stringify(body.data);
 			networkData = cloneNetworkData(body.data);
@@ -1385,6 +1401,7 @@
 			const body = (await response.json()) as {
 				data: NetworkData;
 				writable: boolean;
+				writableReason?: string | null;
 				source: string;
 				updatedAt: string;
 			};
@@ -1396,6 +1413,9 @@
 				networkData = cloneNetworkData(validation.data);
 				ensureSelectedTargetValid();
 				writable = body.writable;
+				readOnlyNotice = body.writable
+					? defaultReadOnlyNotice
+					: resolveReadOnlyNotice(body.writableReason);
 				dataSourceLabel = body.source;
 				lastSavedSnapshot = JSON.stringify(networkData);
 				saveState = 'saved';
@@ -1414,6 +1434,7 @@
 				networkData = cloneNetworkData(fallbackData);
 				ensureSelectedTargetValid();
 				writable = false;
+				readOnlyNotice = 'Read-only: API unavailable; using bundled static data.';
 				dataSourceLabel = jsonPath;
 				lastSavedSnapshot = JSON.stringify(networkData);
 				saveState = 'saved';

src/lib/server/networkPersistence.ts

@@ -1,5 +1,6 @@
 import {
 	checkWritableState as checkWritableStateCore,
+	getWritableState as getWritableStateCore,
 	isWriteEnabled as isWriteEnabledCore,
 	readNetworkFile as readNetworkFileCore,
 	writeNetworkFile as writeNetworkFileCore
@@ -12,6 +13,11 @@ export interface NetworkFileMetadata {
 	updatedAt: string;
 }
 
+export interface WritableState {
+	writable: boolean;
+	reason: string | null;
+}
+
 export function isWriteEnabled(): boolean {
 	return isWriteEnabledCore();
 }
@@ -24,6 +30,10 @@ export async function writeNetworkFile(data: NetworkData): Promise<NetworkFileMe
 	return (await writeNetworkFileCore(data)) as NetworkFileMetadata;
 }
 
+export async function getWritableState(): Promise<WritableState> {
+	return (await getWritableStateCore()) as WritableState;
+}
+
 export async function checkWritableState(): Promise<boolean> {
 	return checkWritableStateCore();
 }

src/lib/shared/networkPersistenceCore.mjs

@@ -16,6 +16,7 @@ import path from 'node:path';
  * @typedef {{ machines: unknown[]; devices: unknown[] }} NetworkData
  * @typedef {{ source: string; updatedAt: string }} NetworkFileMetadata
  * @typedef {{ data: NetworkData } & NetworkFileMetadata} NetworkFileReadResult
+ * @typedef {{ writable: boolean; reason: string | null }} WritableState
  */
 
 const NETWORK_READ_ONLY = process.env.NETWORK_READ_ONLY === 'true';
@@ -43,6 +44,38 @@ export function isWriteEnabled() {
 	return !NETWORK_READ_ONLY;
 }
 
+/**
+ * @param {unknown} error
+ * @returns {string}
+ */
+function formatFileSystemErrorCode(error) {
+	if (error && typeof error === 'object' && 'code' in error && typeof error.code === 'string') {
+		return error.code;
+	}
+	return 'UNKNOWN';
+}
+
+/**
+ * @param {string} directory
+ * @param {string} label
+ * @returns {Promise<string | null>}
+ */
+async function assertDirectoryWritable(directory, label) {
+	try {
+		await mkdir(directory, { recursive: true });
+	} catch (error) {
+		return `${label} directory "${directory}" could not be created (${formatFileSystemErrorCode(error)}).`;
+	}
+
+	try {
+		await access(directory, constants.W_OK);
+	} catch (error) {
+		return `${label} directory "${directory}" is not writable (${formatFileSystemErrorCode(error)}).`;
+	}
+
+	return null;
+}
+
 /**
  * @param {string} dataFilePath
  * @returns {Promise<string>}
@@ -151,20 +184,62 @@ export async function writeNetworkFile(data) {
 }
 
 /**
- * @returns {Promise<boolean>}
+ * @returns {Promise<WritableState>}
  */
-export async function checkWritableState() {
+export async function getWritableState() {
 	if (!isWriteEnabled()) {
-		return false;
+		return {
+			writable: false,
+			reason: 'Writes disabled by NETWORK_READ_ONLY=true.'
+		};
 	}
 
 	const source = resolveDataFilePath();
 	const directory = path.dirname(source);
+	const dataDirectoryError = await assertDirectoryWritable(directory, 'Data');
+	if (dataDirectoryError) {
+		return {
+			writable: false,
+			reason: dataDirectoryError
+		};
+	}
+
+	const backupDirectory = resolveBackupDirectory();
+	const backupDirectoryError = await assertDirectoryWritable(backupDirectory, 'Backup');
+	if (backupDirectoryError) {
+		return {
+			writable: false,
+			reason: backupDirectoryError
+		};
+	}
+
 	try {
-		await mkdir(directory, { recursive: true });
+		await access(source, constants.F_OK);
-		await access(directory, constants.W_OK);
 	} catch {
-		return false;
+		return {
+			writable: true,
+			reason: null
+		};
 	}
-	return true;
+
+	try {
+		await access(source, constants.R_OK | constants.W_OK);
+	} catch (error) {
+		return {
+			writable: false,
+			reason: `Data file "${source}" exists but is not readable and writable (${formatFileSystemErrorCode(error)}).`
+		};
+	}
+
+	return {
+		writable: true,
+		reason: null
+	};
+}
+
+/**
+ * @returns {Promise<boolean>}
+ */
+export async function checkWritableState() {
+	return (await getWritableState()).writable;
 }

src/routes/api/network-data/+server.ts

@@ -2,8 +2,7 @@ import { json } from '@sveltejs/kit';
 
 import { validateNetworkData } from '$lib/data/networkSchema';
 import {
-	checkWritableState,
+	getWritableState,
-	isWriteEnabled,
 	readNetworkFile,
 	writeNetworkFile
 } from '$lib/server/networkPersistence';
@@ -16,11 +15,18 @@ function serializeValidationErrors(errors: Array<{ path: string; message: string
 	}));
 }
 
+function resolveReadOnlyErrorMessage(reason: string | null): string {
+	if (!reason) {
+		return 'Write API unavailable in current deployment.';
+	}
+	return `Write API unavailable: ${reason}`;
+}
+
 export const GET: RequestHandler = async () => {
 	try {
-		const [{ data, source, updatedAt }, writable] = await Promise.all([
+		const [{ data, source, updatedAt }, writableState] = await Promise.all([
 			readNetworkFile(),
-			checkWritableState()
+			getWritableState()
 		]);
 		const validation = validateNetworkData(data);
 		if (!validation.valid || !validation.data) {
@@ -35,7 +41,8 @@ export const GET: RequestHandler = async () => {
 
 		return json({
 			data: validation.data,
-			writable,
+			writable: writableState.writable,
+			writableReason: writableState.reason,
 			source,
 			updatedAt
 		});
@@ -47,10 +54,13 @@ export const GET: RequestHandler = async () => {
 };
 
 export const PUT: RequestHandler = async ({ request }) => {
-	if (!isWriteEnabled()) {
+	const writableStateBeforeWrite = await getWritableState();
+	if (!writableStateBeforeWrite.writable) {
 		return json(
 			{
-				error: 'Write API disabled. Unset NETWORK_READ_ONLY to enable persistence.'
+				error: resolveReadOnlyErrorMessage(writableStateBeforeWrite.reason),
+				writable: false,
+				writableReason: writableStateBeforeWrite.reason
 			},
 			{ status: 403 }
 		);
@@ -76,10 +86,11 @@ export const PUT: RequestHandler = async ({ request }) => {
 
 	try {
 		const metadata = await writeNetworkFile(validation.data);
-		const writable = await checkWritableState();
+		const writableStateAfterWrite = await getWritableState();
 		return json({
 			data: validation.data,
-			writable,
+			writable: writableStateAfterWrite.writable,
+			writableReason: writableStateAfterWrite.reason,
 			source: metadata.source,
 			updatedAt: metadata.updatedAt
 		});

static/data/network.json

@@ -5,6 +5,47 @@
 			"ipAddress": "10.0.0.3",
 			"role": "Hypervisor",
 			"operatingSystem": "Proxmox",
+			"iconKey": "homarr:proxmox",
+			"software": {
+				"vms": [
+					{
+						"name": "OpnSense",
+						"role": "Router/Firewall/Gateway (DHCP 10.0.0.100-254)",
+						"ipAddress": "10.0.0.1"
+					},
+					{
+						"name": "TPLink Omada Controller",
+						"role": "Network Controller (:8043)",
+						"ipAddress": "10.0.0.4"
+					},
+					{
+						"name": "PiVPN (WireGuard)",
+						"role": "VPN Server",
+						"ipAddress": "10.0.0.5"
+					},
+					{
+						"name": "PiHole",
+						"role": "DNS Ad-blocker (installed, not in active use)",
+						"ipAddress": "10.0.0.6"
+					},
+					{
+						"name": "Dashy",
+						"role": "Dashboard",
+						"ipAddress": "10.0.0.12"
+					},
+					{
+						"name": "ProxRouter-Docker",
+						"role": "Docker host (Nginx reverse proxy, RustDesk, TwinGate)",
+						"ipAddress": "10.0.0.23"
+					}
+				]
+			},
+			"hardware": {
+				"cpu": "Intel N100",
+				"ram": "8GB",
+				"networkPorts": 4,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -34,45 +75,23 @@
 						"port": "wan"
 					}
 				}
-			],
-			"software": {
-				"vms": [
-					{
-						"name": "OpnSense",
-						"role": "Router/Firewall/Gateway (DHCP 10.0.0.100-254)",
-						"ipAddress": "10.0.0.1"
-					},
-					{
-						"name": "TPLink Omada Controller",
-						"role": "Network Controller (:8043)",
-						"ipAddress": "10.0.0.4"
-					},
-					{ "name": "PiVPN (WireGuard)", "role": "VPN Server", "ipAddress": "10.0.0.5" },
-					{
-						"name": "PiHole",
-						"role": "DNS Ad-blocker (installed, not in active use)",
-						"ipAddress": "10.0.0.6"
-					},
-					{ "name": "Dashy", "role": "Dashboard", "ipAddress": "10.0.0.12" },
-					{
-						"name": "ProxRouter-Docker",
-						"role": "Docker host (Nginx reverse proxy, RustDesk, TwinGate)",
-						"ipAddress": "10.0.0.23"
-					}
 			]
 		},
-			"hardware": {
-				"cpu": "Intel N100",
-				"ram": "8GB",
-				"networkPorts": 4,
-				"networkPortSpeedGbps": 1
-			}
-		},
 		{
 			"machineName": "Asustor NAS",
 			"ipAddress": "10.0.0.9",
 			"role": "NAS",
 			"operatingSystem": "Asustor ADM",
+			"iconKey": "homarr:asustor",
+			"software": {
+				"vms": []
+			},
+			"hardware": {
+				"cpu": "Realtek RTD1296 Quad Core 1.4GHz",
+				"ram": "2GB",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -82,20 +101,23 @@
 						"port": "3"
 					}
 				}
-			],
+			]
-			"software": { "vms": [] },
-			"hardware": {
-				"cpu": "Realtek RTD1296 Quad Core 1.4GHz",
-				"ram": "2GB",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1
-			}
 		},
 		{
 			"machineName": "Home Assistant Green",
 			"ipAddress": "10.0.0.13",
 			"role": "Smart Home Controller",
 			"operatingSystem": "Home Assistant OS",
+			"iconKey": "homarr:home-assistant",
+			"software": {
+				"vms": []
+			},
+			"hardware": {
+				"cpu": "Home Assistant Custom SoC",
+				"ram": "Unknown",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -105,20 +127,23 @@
 						"port": "4"
 					}
 				}
-			],
+			]
-			"software": { "vms": [] },
-			"hardware": {
-				"cpu": "Home Assistant Custom SoC",
-				"ram": "Unknown",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1
-			}
 		},
 		{
 			"machineName": "Plex Server",
 			"ipAddress": "10.0.0.11",
 			"role": "Media Server",
 			"operatingSystem": "Ubuntu Server",
+			"iconKey": "homarr:plex",
+			"software": {
+				"vms": []
+			},
+			"hardware": {
+				"cpu": "Intel N100",
+				"ram": "Unknown",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -128,20 +153,23 @@
 						"port": "5"
 					}
 				}
-			],
+			]
-			"software": { "vms": [] },
-			"hardware": {
-				"cpu": "Intel N100",
-				"ram": "Unknown",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1
-			}
 		},
 		{
 			"machineName": "Win11 N100",
 			"ipAddress": "10.0.0.8",
 			"role": "Media Downloader",
 			"operatingSystem": "Windows 11",
+			"iconKey": "homarr:windows-11",
+			"software": {
+				"vms": []
+			},
+			"hardware": {
+				"cpu": "Intel N100",
+				"ram": "Unknown",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -151,20 +179,40 @@
 						"port": "6"
 					}
 				}
-			],
+			]
-			"software": { "vms": [] },
-			"hardware": {
-				"cpu": "Intel N100",
-				"ram": "Unknown",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1
-			}
 		},
 		{
 			"machineName": "Win11 Backblaze NAS",
 			"ipAddress": "10.0.0.7",
 			"role": "Backup NAS + Hypervisor",
 			"operatingSystem": "TrueNAS Scale",
+			"iconKey": "homarr:backblaze",
+			"software": {
+				"vms": [
+					{
+						"name": "Win11NAS",
+						"role": "Backblaze Backup VM",
+						"ipAddress": "10.0.0.24"
+					},
+					{
+						"name": "MakeMKV",
+						"role": "Blu-ray Ripper",
+						"ipAddress": "10.0.0.14"
+					},
+					{
+						"name": "Handbrake",
+						"role": "Video Transcoder",
+						"ipAddress": "10.0.0.15"
+					}
+				]
+			},
+			"hardware": {
+				"cpu": "AMD Ryzen 5 4600G",
+				"ram": "16GB",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1,
+				"gpu": "EVGA GeForce GTX 1050 Ti"
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -174,37 +222,14 @@
 						"port": "7"
 					}
 				}
-			],
-			"software": {
-				"vms": [
-					{ "name": "Win11NAS", "role": "Backblaze Backup VM", "ipAddress": "10.0.0.24" },
-					{ "name": "MakeMKV", "role": "Blu-ray Ripper", "ipAddress": "10.0.0.14" },
-					{ "name": "Handbrake", "role": "Video Transcoder", "ipAddress": "10.0.0.15" }
 			]
 		},
-			"hardware": {
-				"cpu": "AMD Ryzen 5 4600G",
-				"ram": "16GB",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1,
-				"gpu": "EVGA GeForce GTX 1050 Ti"
-			}
-		},
 		{
 			"machineName": "TrueNAS Host",
 			"ipAddress": "10.0.0.10",
 			"role": "Storage + VM Host",
 			"operatingSystem": "TrueNAS Scale",
-			"ports": [
+			"iconKey": "homarr:truenas",
-				{
-					"portName": "eth0",
-					"speedGbps": 1,
-					"connectedTo": {
-						"device": "Gigabit Switch",
-						"port": "8"
-					}
-				}
-			],
 			"software": {
 				"vms": [
 					{
@@ -219,13 +244,45 @@
 				"ram": "Unknown",
 				"networkPorts": 1,
 				"networkPortSpeedGbps": 1
+			},
+			"ports": [
+				{
+					"portName": "eth0",
+					"speedGbps": 1,
+					"connectedTo": {
+						"device": "Gigabit Switch",
+						"port": "8"
 					}
+				}
+			]
 		},
 		{
 			"machineName": "AI Server",
 			"ipAddress": "10.0.0.20",
 			"role": "AI Dev/Inference",
 			"operatingSystem": "Pop!_OS",
+			"iconKey": "homarr:ollama-dark",
+			"software": {
+				"vms": [
+					{
+						"name": "Ollama",
+						"role": "LLM Inference",
+						"ipAddress": "10.0.0.21"
+					},
+					{
+						"name": "Bot Training",
+						"role": "AI Training",
+						"ipAddress": "10.0.0.22"
+					}
+				]
+			},
+			"hardware": {
+				"cpu": "AMD Ryzen 5 3600",
+				"ram": "32GB",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1,
+				"gpu": "Gigabyte GeForce GTX 1080"
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -235,26 +292,23 @@
 						"port": "9"
 					}
 				}
-			],
-			"software": {
-				"vms": [
-					{ "name": "Ollama", "role": "LLM Inference", "ipAddress": "10.0.0.21" },
-					{ "name": "Bot Training", "role": "AI Training", "ipAddress": "10.0.0.22" }
 			]
 		},
-			"hardware": {
-				"cpu": "AMD Ryzen 5 3600",
-				"ram": "32GB",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1,
-				"gpu": "Gigabyte GeForce GTX 1080"
-			}
-		},
 		{
 			"machineName": "Immich Mini PC",
 			"ipAddress": "10.0.0.30",
 			"role": "Photo Server",
 			"operatingSystem": "Linux",
+			"iconKey": "homarr:immich",
+			"software": {
+				"vms": []
+			},
+			"hardware": {
+				"cpu": "Unknown",
+				"ram": "Unknown",
+				"networkPorts": 1,
+				"networkPortSpeedGbps": 1
+			},
 			"ports": [
 				{
 					"portName": "eth0",
@@ -264,14 +318,7 @@
 						"port": "10"
 					}
 				}
-			],
+			]
-			"software": { "vms": [] },
-			"hardware": {
-				"cpu": "Unknown",
-				"ram": "Unknown",
-				"networkPorts": 1,
-				"networkPortSpeedGbps": 1
-			}
 		}
 	],
 	"devices": [
@@ -279,6 +326,7 @@
 			"name": "Gigabit Switch",
 			"ipAddress": "unknown",
 			"type": "Network Switch",
+			"iconKey": "switch",
 			"notes": "Main 24-port switch. Wireless access point uplinks through this switch.",
 			"ports": [
 				{
@@ -403,7 +451,11 @@
 				},
 				{
 					"portName": "20",
-					"speedGbps": 1
+					"speedGbps": 1,
+					"connectedTo": {
+						"device": "NanoKVM Lite",
+						"port": "port0"
+					}
 				},
 				{
 					"portName": "21",
@@ -443,6 +495,7 @@
 			"name": "HDHomeRun",
 			"ipAddress": "10.0.0.2",
 			"type": "TV Tuner",
+			"iconKey": "homarr:hdhomerun",
 			"ports": [
 				{
 					"portName": "eth0",
@@ -458,37 +511,62 @@
 			"name": "3DS",
 			"ipAddress": "10.0.0.17",
 			"type": "Handheld Console",
-			"notes": "Wi-Fi only."
+			"notes": "Wi-Fi only.",
+			"ports": []
 		},
 		{
 			"name": "2DS",
 			"ipAddress": "10.0.0.18",
 			"type": "Handheld Console",
-			"notes": "Wi-Fi only."
+			"notes": "Wi-Fi only.",
+			"ports": []
 		},
 		{
 			"name": "Nintendo Switch",
 			"ipAddress": "10.0.0.19",
 			"type": "Gaming Console",
-			"notes": "Wi-Fi only."
+			"notes": "Wi-Fi only.",
+			"ports": [
+				{
+					"portName": "port0",
+					"speedGbps": 1
+				}
+			]
 		},
 		{
 			"name": "NanoKVM Lite",
 			"ipAddress": "10.0.0.26",
 			"type": "KVM Device",
-			"notes": "Port link not yet modeled."
+			"notes": "Port link not yet modeled.",
+			"ports": [
+				{
+					"portName": "port0",
+					"speedGbps": 1,
+					"connectedTo": {
+						"device": "Gigabit Switch",
+						"port": "20"
+					}
+				}
+			]
 		},
 		{
 			"name": "UPS Pi",
 			"ipAddress": "10.0.0.27",
 			"type": "Power Monitoring Device",
-			"notes": "Port link not yet modeled."
+			"notes": "Port link not yet modeled.",
+			"ports": [
+				{
+					"portName": "port0",
+					"speedGbps": 1
+				}
+			]
 		},
 		{
 			"name": "Waveshare",
 			"ipAddress": "10.0.0.28",
 			"type": "Peripheral Device",
-			"notes": "Port link not yet modeled."
+			"notes": "Port link not yet modeled.",
+			"ports": []
 		}
 	]
 }