jcreek/opennetworkdiagram

1. Overall shape

Open Network Diagram is a SvelteKit-based single-page app with a small Node runtime server for persistence. The app is designed around a JSON file as the source of truth, so the architecture is split between:

• a browser UI for viewing/editing diagrams,

• a server/API layer for loading and saving network data,

• static vendored assets for icons and demo data.

2. Primary runtime modes

The repo supports two meaningful deployment modes:

• Self-hosted writable mode: the UI edits network.json through the API and persists changes to disk.

• Read-only/public mode: used for demos or Netlify-style hosting, where the UI reads static data and writes are disabled.

This mode split is important because it changes whether the server’s persistence layer is active.

3. UI layer

The user-facing application lives under src/routes and src/lib/components. The main visible pieces are:

• NetworkDiagram.svelte for rendering the topology/diagram,

• Modal.svelte for editing machines/devices,

• route entry points in +page.svelte and +layout.svelte.

The UI is built to update the diagram live as the underlying JSON changes, rather than treating the diagram as a separate model.

4. Data model and schema boundary

The canonical data shape is defined in src/lib/data/networkSchema.ts and shared validation/core logic in src/lib/shared/networkSchemaCore.mjs. This is the boundary between arbitrary JSON input and the app’s internal expectations.

The schema covers the repository’s core entities: machines, devices, VMs, software, hardware, ports, IP addresses, and roles. This is the main contract that both UI editing and persistence must respect.

5. Load/edit/save flow

The data flow is:

• load JSON from the configured data source,

• validate/normalize it against the schema,

• let the UI edit it,

• persist the updated JSON back through the API/server.

src/lib/data/loadNetworkData.ts and src/lib/data/networkEditor.ts sit on the client-side data handling path, while src/lib/server/networkPersistence.ts and src/lib/shared/networkPersistenceCore.mjs handle the write path and atomic file operations.

6. API boundary

src/routes/api/network-data/+server.ts exposes the persistence API, documented in the README as GET/PUT /api/network-data.

This endpoint is the key boundary between browser state and durable storage:

• GET serves the current diagram JSON,

• PUT accepts edits from the UI,

• responses can include writability diagnostics when the app is running read-only.

The API is what makes the app usable both locally and in Docker with a mounted data volume.

7. Diagram transformation pipeline

The raw network JSON is not rendered directly. Instead, src/lib/graph/transformNetworkData.ts and src/lib/graph/types.ts convert the persisted schema into a graph-friendly structure for display.

This transformation layer is where the app derives diagram-specific concerns such as:

• node/edge relationships,

• network vs non-network presentation,

• VM expansion behavior,

• label/connection layout details.

It is a clear separation between stored domain data and visual representation.

8. Icon system and local asset catalog

The project includes a local icon registry in src/lib/config/iconRegistry.ts and a generated manifest in src/lib/config/vendorIconManifest.ts.

Icons are vendored into static/icons/vendor and sourced from third_party/homarr-dashboard-icons, with a helper script under scripts/generate-vendor-icon-manifest.mjs.

This means the UI does not depend on an external icon service at runtime, which matters for offline/self-hosted deployments.

9. Theme and browser state

The app has a small store layer in src/lib/stores/theme.ts for theme handling. This is client-side state only and is separate from the persisted network JSON.

That split helps keep local UX concerns distinct from the authoritative infrastructure model.

10. Server/runtime packaging

server.mjs, Dockerfile, docker-compose.yml, and nginx/default.conf indicate a deployment model where the built app can be served as a containerized Node/static app behind a web server.

The server is responsible for serving the UI and backing the API in writable deployments, while the Docker/compose setup mounts a host data directory so the JSON file survives restarts.

11. Data locations and environment-specific sources

There are three important data locations:

• data/network.json.example for seeding a new writable install,

• data/network.json for default local/server persistence,

• static/data/network.json for the bundled read-only/demo dataset.

This separation supports both local editing and static hosting without changing application code.

12. Operational boundaries and CI/CD

The repo’s GitHub workflows and build targets reflect two different artifacts:

• a Docker/runtime artifact for self-hosted writable use,

• a static/Netlify artifact for read-only demo hosting.

The build variants are important because they encode the app’s operational boundary: writable persistence is only available when the runtime can access a filesystem-backed data path.

13. Architecture summary for diagramming

If you draw this system, model it as:

• a browser UI at the center,

• a JSON schema/domain layer beneath it,

• a transformation layer from domain data to graph visuals,

• a server/API persistence layer on the side for GET/PUT to a JSON file,

• vendored static icons and demo data as supporting assets.

The most important conceptual boundary is that the diagram is a projection of persisted JSON, not a separate hand-authored drawing model.