How stan-smith/fossflow works
FossFLOW is a monorepo with three main runtime surfaces and one documentation surface:
1. A reusable diagramming engine/library in packages/fossflow-lib
2. A browser app/PWA in packages/fossflow-app
3. An optional backend service used mainly for Docker/server-side storage in packages/fossflow-backend
4. A separate docs site under packages/fossflow-lib/docs
1) Core product architecture: browser-based diagram editor
The main application is an isometric diagram editor that runs in the browser. The editor is not a thin UI on top of a backend; most of the interactive behavior, rendering, and state management live in the shared library package.
packages/fossflow-lib: the editor engine
This package is the architectural center of the repo. It provides:
• The top-level Isoflow component and the library entry points
• Rendering and scene composition
• Interaction handling for editing diagrams
• State stores and reducers
• Schema definitions and validation for diagrams
• Reusable UI controls and dialogs
• Hooks and utility functions that encapsulate editor behavior
Main internal subsystems in the library
Rendering / scene graph
The components/SceneLayers, Renderer, SceneLayer, Svg, Grid, IsoTileArea, UiOverlay, and related components form the visual pipeline.
This layer is responsible for:
• Drawing the isometric workspace
• Rendering nodes, connectors, rectangles, and text boxes
• Drawing overlays such as controls, tooltips, cursors, and menus
• Export-oriented rendering support, including SVG/image generation
The diagram elements are broken into distinct visual and logical categories:
• Nodes
• Connectors
• Rectangles
• Text boxes
• Labels
That separation matters because each item type has its own controls, transforms, and reducer logic.
Interaction system
The interaction folder is the user input engine. It contains interaction modes such as:
• Cursor
• Pan
• Drag items
• Place icon
• Connector creation
• Lasso / freehand lasso
• Rectangle drawing and transforming
• Text box placement/editing
The interaction manager and pan handlers route pointer and keyboard events into the active mode. This is the layer that translates user gestures into state updates in the stores/reducers.
State management
The stores folder contains the application state model, including:
• Model state
• Scene state
• UI state
• Locale state
• Reducers for model items, connectors, rectangles, text boxes, and views
The store boundary is important: diagram state is normalized into model/scene/UI concerns, and the reducers are responsible for updating those structures in response to interactions. This is also where undo/history support is integrated via hooks like useHistory.
Schemas and validation
The schemas folder defines the canonical data structures for:
• Colors
• Icons
• Connectors
• Rectangles
• Text boxes
• Models and views
• Validation
This is the repo’s contract for import/export and persistence. It is the main boundary between “live editor state” and serialized diagram data.
Hooks and utilities
The hooks and utils folders provide reusable editor logic:
• Geometry, coordinates, and size calculations
• Tile occupancy/pathfinding helpers
• Connector label positioning
• View/model item accessors
• Resize, window, and scene helpers
• Icon filtering and icon category logic
• Iso-projection helpers
These are not just convenience helpers; they encode the domain logic that keeps rendering, hit testing, and placement consistent.
UI chrome and editor controls
The library also contains most of the editor UI:
• Main menu
• Tool menu
• Zoom controls
• Settings dialogs
• Help dialog
• Export image dialog
• Context menus
• Item controls for each object type
• Color selector, icon picker, hotkey settings, pan/zoom settings, connector settings
This means the library is not only “rendering primitives”; it is effectively the entire editor shell and interaction surface.
2) App package: the product wrapper around the library
packages/fossflow-app is the browser-facing app that wraps the library and turns it into a PWA.
Responsibilities of the app package
• Bootstraps the React application
• Hosts the main editor page
• Manages diagram persistence in the browser
• Handles app-specific storage concerns
• Provides internationalized UI resources
• Registers the service worker for offline/PWA support
• Supplies app-level styling and minimal integration code
App-specific pieces
Key files suggest these responsibilities:
• App.tsx, EditorPage.tsx: top-level application composition
• StorageManager.tsx: persistence orchestration
• usePersistedDiagram.ts: restore/save behavior for the current diagram
• services/storageService.ts: persistence backend abstraction used by the app
• services/iconPackManager.ts: management of icon pack data
• diagramUtils.ts: app-level helpers around diagram state
• serviceWorkerRegistration.ts: offline support
• i18n.ts and public/i18n: runtime translation resources
App data flow
At runtime, the browser app typically follows this flow:
1. App loads
2. It initializes locale, icon packs, and persisted diagram state
3. It renders the library’s editor component
4. User edits the diagram in the library
5. App persists the serialized diagram using browser storage or server storage depending on deployment
6. Service worker enables offline/PWA behavior
The app is therefore a thin but important boundary between the reusable editor engine and product-specific persistence/PWA behavior.
3) Persistence and serialization boundary
There are two distinct persistence paths implied by the repo:
Browser-side persistence
The README describes:
• Quick save to browser session
• Auto-save to session storage every few seconds
• Export/import as JSON
That suggests the default local flow is:
• Editor state is serialized to a diagram model format
• The app saves it locally in the browser
• The user can export/import the same model format manually
Server-side persistence in Docker
The Docker-oriented setup introduces a backend service and volume-mounted storage under ./diagrams or /data/diagrams.
This is an optional runtime boundary:
• The browser app still hosts the editor
• The backend provides diagram file storage
• Basic auth can be enabled through environment variables
• Nginx is used in the containerized deployment path to serve/proxy the app
For an architecture diagram, this is best represented as an optional server-side storage subsystem rather than a required API backend for editing.
4) Deployment architecture
Local/browser-first mode
The standard development/runtime model is:
• React/TypeScript app in the browser
• Editor engine as a library package
• No required external SaaS dependencies
Docker/production mode
The repo includes:
• Dockerfile
• compose.yml and compose.dev.yml
• nginx.conf
• docker-entrypoint.sh
• packages/fossflow-backend/server.js
This implies a containerized deployment with:
• Static frontend assets served through Nginx
• A Node-based backend process for server storage and optional authentication
• Persistent volume storage for diagrams
The deployment boundary is therefore split between:
• Frontend static/PWA assets
• A lightweight Node backend for storage concerns
• Nginx as the edge/static serving layer in the container image
5) Documentation and examples as separate surfaces
The repo also contains two non-product surfaces:
Docs site
packages/fossflow-lib/docs is a Next.js-based documentation site for the library. This is separate from the editor runtime and is used to document APIs, quickstart, installation, and contributing.
Examples and fixtures
packages/fossflow-lib/src/examples and src/fixtures provide sample editors, readonly mode, debug tools, and initial data. These are reference compositions for embedding the library in different modes.
These are useful to treat as “integration examples” in the architecture rather than production subsystems.
6) Testing and quality gates
The repo has two main test layers:
Unit/component tests
Most of the library’s behavior is covered by Jest tests under packages/fossflow-lib/src/**/__tests__.
These tests validate:
• Schemas and reducers
• Hooks
• Rendering utilities
• UI components
End-to-end tests
e2e-tests uses Python/Selenium-style tests and Docker orchestration to drive the app in a real browser.
These tests focus on:
• Basic load
• Base path routing
• Import/export behavior
• Undo/redo
• Node placement
• Store debug behavior
For architecture purposes, the E2E suite is important because it validates the full stack:
browser UI, editor engine, persistence flows, and container deployment behavior.
7) Key architectural boundaries to draw
If you are diagramming the system, the most important boundaries are:
• Browser app boundary vs. reusable editor library
• Live editor state vs. serialized diagram schema
• Interaction handling vs. rendering
• App-level persistence vs. editor engine logic
• Browser-only mode vs. Docker/server-storage mode
• Production runtime vs. docs/examples/testing tooling
8) Technology choices that materially affect the architecture
• React + TypeScript: main UI/runtime model
• PWA/service worker: offline-capable client app
• Monorepo package structure: shared editor engine and app wrapper are developed together
• NPM-published library: the engine is intended for reuse/embedding
• Docker + Nginx: container deployment and static serving edge
• Node backend: optional storage/auth service
• Python/Selenium-based E2E tests: real-browser validation of the integrated system
In short, FossFLOW is best understood as a browser-native diagramming engine packaged as a reusable React library, with a thin app shell for PWA behavior and persistence, plus an optional containerized backend for server-side storage.
Main entry points: Isoflow.tsx Isoflow · App.tsx App shell · stores Stores · interaction Interactions
Components 18
Editor library
Reusable browser-based diagramming engine and its internal subsystems.
- Isoflow · Top-level editor component and main public entry point for the shared engine.
packages/fossflow-lib/src/Isoflow.tsx - Scene render · Composes the isometric workspace, SVG scene, grid, layers, and overlays.
packages/fossflow-lib/src/components/SceneLayers - Interactions · Pointer and keyboard modes for pan, drag, lasso, connector, shapes, and text.
packages/fossflow-lib/src/interaction - Stores · Normalized model, scene, UI, and locale state with reducers and history support.
packages/fossflow-lib/src/stores - Schemas · Canonical model definitions and validation for import, export, and persistence.
packages/fossflow-lib/src/schemas - Hooks & utils · Shared geometry, placement, projection, history, and lookup helpers used by editor behavior.
packages/fossflow-lib/src/hooks - Editor chrome · Menus, dialogs, controls, and overlays for editing, settings, help, export, and item tools.
packages/fossflow-lib/src/components
Browser app
PWA shell that wraps the library and handles persistence and app UX.
- App shell · Top-level React application composition and editor page bootstrap.
packages/fossflow-app/src/App.tsx - Persisted diagram · Browser persistence orchestration for loading, saving, and restoring diagrams.
packages/fossflow-app/src/usePersistedDiagram.ts - App services · Storage abstraction, icon pack management, i18n, and service worker registration.
packages/fossflow-app/src/services/storageService.ts - App pages · Editor page, diagram manager, storage manager, and app-local UI wiring.
packages/fossflow-app/src/EditorPage.tsx
Backend & deploy
Optional server storage service and container edge/runtime pieces.
- Storage service · Optional backend process used for Docker/server-side diagram storage and auth.
packages/fossflow-backend/server.js - Nginx edge · Container-side static serving and proxy layer for production deployment.
nginx.conf - Docker stack · Compose and entrypoint setup for containerized frontend and optional backend runtime.
Dockerfile
Docs & examples
Documentation and reference compositions for the library.
Quality gates
Automated validation across library, app, and deployment flows.
Connections 27
- Isoflow → Scene render: renders · The editor component composes the visual workspace.
- Isoflow → Interactions: handles input · Editor gestures are routed through interaction modes.
- Isoflow → Stores: reads/writes state · Interactive editing updates normalized editor stores.
- Isoflow → Schemas: serializes · Live state is validated and exported through schema contracts.
- Isoflow → Hooks & utils: uses logic · Shared domain helpers support geometry, projection, and lookup.
- Isoflow → Editor chrome: shows ui · Menus, dialogs, and controls are mounted around the canvas.
- Scene render → Stores: consumes scene · Render layers read scene and model state from stores.
- Scene render → Hooks & utils: geometry · Rendering and hit testing rely on shared utility calculations.
- Interactions → Stores: dispatches · Pointer and keyboard modes mutate model, scene, and UI state.
- Interactions → Hooks & utils: calculates · Modes use geometry and occupancy helpers for placement.
- Stores → Schemas: conforms to · Reducers maintain structures compatible with serialized models.
- Hooks & utils → Schemas: interprets · Helpers operate on the same model and item shapes as the schema layer.
- Editor chrome → Stores: controls · UI chrome edits settings, selections, and item properties via stores.
- Examples → Isoflow: embeds · Reference compositions mount the shared editor engine in different modes.
- Docs site → Examples: documents · Docs describe installation, API usage, and example configurations.
- App shell → Isoflow: wraps · The browser app embeds the reusable library editor.
- App shell → Persisted diagram: persists · App shell coordinates browser save and restore behavior.
- App shell → App services: initializes · Locale, icon pack, storage, and service worker setup happen at app start.
- App pages → App shell: composes · App pages and managers build the browser-facing runtime.
- Persisted diagram → Storage service: optional sync · Persisted diagrams can be backed by the server storage service.
- App services → Storage service: server path · Storage abstraction can target the optional backend deployment.
- Docker stack → Storage service: runs · Container stack includes the Node storage service.
- Docker stack → Nginx edge: serves through · Production image uses Nginx as the edge/static layer.
- E2E tests → App shell: validates · End-to-end tests exercise the browser app and editor flows.
- E2E tests → Docker stack: validates · E2E coverage also checks containerized deployment behavior.
- Lib tests → Schemas: covers · Library tests validate the schema and reducer boundary.
- Lib tests → Interactions: covers · Tests exercise hooks, utilities, and interaction behavior.