# stan-smith/fossflow architecture

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

- Interactive diagram: https://gitdiagram.com/stan-smith/fossflow
- Repository: https://github.com/stan-smith/fossflow

## Overview

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: [`packages/fossflow-lib/src/Isoflow.tsx`](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-lib/src/Isoflow.tsx) (Isoflow), [`packages/fossflow-app/src/App.tsx`](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-app/src/App.tsx) (App shell), [`packages/fossflow-lib/src/stores`](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/stores) (Stores), [`packages/fossflow-lib/src/interaction`](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/interaction) (Interactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Editor library"
  node_isoflow["Isoflow<br/>library entry<br/>[Isoflow.tsx]"]
  node_scene["Scene render<br/>render pipeline"]
  node_interaction["Interactions<br/>input engine"]
  node_stores[("Stores<br/>state model")]
  node_schemas["Schemas<br/>data contract"]
  node_hooks_utils["Hooks & utils<br/>domain logic"]
  node_chrome["Editor chrome<br/>ui shell"]
end

subgraph "Browser app"
  node_app_boot["App shell<br/>browser app<br/>[App.tsx]"]
  node_app_store["Persisted diagram<br/>app state"]
  node_app_services["App services<br/>pwa services<br/>[storageService.ts]"]
  node_app_files["App pages<br/>app runtime<br/>[EditorPage.tsx]"]
end

subgraph "Backend & deploy"
  node_backend["Storage service<br/>node backend<br/>[server.js]"]
  node_nginx["Nginx edge<br/>container edge<br/>[nginx.conf]"]
  node_docker["Docker stack<br/>deployment"]
end

subgraph "Docs & examples"
  node_examples["Examples<br/>reference modes"]
  node_docs["Docs site<br/>next docs"]
end

subgraph "Quality gates"
  node_e2e["E2E tests<br/>browser tests"]
  node_lib_tests["Lib tests<br/>unit tests"]
end

node_isoflow -->|"renders"| node_scene
node_isoflow -->|"handles input"| node_interaction
node_isoflow -->|"reads/writes state"| node_stores
node_isoflow -->|"serializes"| node_schemas
node_isoflow -->|"uses logic"| node_hooks_utils
node_isoflow -->|"shows ui"| node_chrome
node_scene -->|"consumes scene"| node_stores
node_scene -->|"geometry"| node_hooks_utils
node_interaction -->|"dispatches"| node_stores
node_interaction -->|"calculates"| node_hooks_utils
node_stores -->|"conforms to"| node_schemas
node_hooks_utils -->|"interprets"| node_schemas
node_chrome -->|"controls"| node_stores
node_examples -->|"embeds"| node_isoflow
node_docs -.->|"documents"| node_examples
node_app_boot -->|"wraps"| node_isoflow
node_app_boot -->|"persists"| node_app_store
node_app_boot -->|"initializes"| node_app_services
node_app_files -->|"composes"| node_app_boot
node_app_store -.->|"optional sync"| node_backend
node_app_services -.->|"server path"| node_backend
node_docker -->|"runs"| node_backend
node_docker -->|"serves through"| node_nginx
node_e2e -->|"validates"| node_app_boot
node_e2e -->|"validates"| node_docker
node_lib_tests -->|"covers"| node_schemas
node_lib_tests -->|"covers"| node_interaction

click node_isoflow "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-lib/src/Isoflow.tsx"
click node_scene "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/components/SceneLayers"
click node_interaction "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/interaction"
click node_stores "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/stores"
click node_schemas "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/schemas"
click node_hooks_utils "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/hooks"
click node_chrome "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/components"
click node_examples "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src/examples"
click node_docs "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/docs"
click node_app_boot "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-app/src/App.tsx"
click node_app_store "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-app/src/usePersistedDiagram.ts"
click node_app_services "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-app/src/services/storageService.ts"
click node_backend "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-backend/server.js"
click node_nginx "https://github.com/stan-smith/fossflow/blob/master/nginx.conf"
click node_docker "https://github.com/stan-smith/fossflow/tree/master/Dockerfile"
click node_e2e "https://github.com/stan-smith/fossflow/tree/master/e2e-tests/tests"
click node_lib_tests "https://github.com/stan-smith/fossflow/tree/master/packages/fossflow-lib/src"
click node_app_files "https://github.com/stan-smith/fossflow/blob/master/packages/fossflow-app/src/EditorPage.tsx"

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_isoflow,node_scene,node_interaction,node_stores,node_schemas,node_hooks_utils,node_chrome toneBlue
class node_app_boot,node_app_store,node_app_services,node_app_files toneAmber
class node_backend,node_nginx,node_docker toneMint
class node_examples,node_docs toneRose
class node_e2e,node_lib_tests toneIndigo
```

## Components

### Editor library

Reusable browser-based diagramming engine and its internal subsystems.

- [Isoflow](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-lib/src/Isoflow.tsx): library entry · Top-level editor component and main public entry point for the shared engine. · `packages/fossflow-lib/src/Isoflow.tsx`
- [Scene render](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/components/SceneLayers): render pipeline · Composes the isometric workspace, SVG scene, grid, layers, and overlays. · `packages/fossflow-lib/src/components/SceneLayers`
- [Interactions](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/interaction): input engine · Pointer and keyboard modes for pan, drag, lasso, connector, shapes, and text. · `packages/fossflow-lib/src/interaction`
- [Stores](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/stores): state model · Normalized model, scene, UI, and locale state with reducers and history support. · `packages/fossflow-lib/src/stores`
- [Schemas](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/schemas): data contract · Canonical model definitions and validation for import, export, and persistence. · `packages/fossflow-lib/src/schemas`
- [Hooks & utils](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/hooks): domain logic · Shared geometry, placement, projection, history, and lookup helpers used by editor behavior. · `packages/fossflow-lib/src/hooks`
- [Editor chrome](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/components): ui shell · 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](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-app/src/App.tsx): browser app · Top-level React application composition and editor page bootstrap. · `packages/fossflow-app/src/App.tsx`
- [Persisted diagram](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-app/src/usePersistedDiagram.ts): app state · Browser persistence orchestration for loading, saving, and restoring diagrams. · `packages/fossflow-app/src/usePersistedDiagram.ts`
- [App services](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-app/src/services/storageService.ts): pwa services · Storage abstraction, icon pack management, i18n, and service worker registration. · `packages/fossflow-app/src/services/storageService.ts`
- [App pages](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-app/src/EditorPage.tsx): app runtime · 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](https://github.com/stan-smith/fossflow/blob/HEAD/packages/fossflow-backend/server.js): node backend · Optional backend process used for Docker/server-side diagram storage and auth. · `packages/fossflow-backend/server.js`
- [Nginx edge](https://github.com/stan-smith/fossflow/blob/HEAD/nginx.conf): container edge · Container-side static serving and proxy layer for production deployment. · `nginx.conf`
- [Docker stack](https://github.com/stan-smith/fossflow/tree/HEAD/Dockerfile): deployment · Compose and entrypoint setup for containerized frontend and optional backend runtime. · `Dockerfile`

### Docs & examples

Documentation and reference compositions for the library.

- [Examples](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src/examples): reference modes · Basic editor, readonly mode, debug tools, and initial data compositions. · `packages/fossflow-lib/src/examples`
- [Docs site](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/docs): next docs · Separate documentation site for install, quickstart, API, isopacks, and contributing. · `packages/fossflow-lib/docs`

### Quality gates

Automated validation across library, app, and deployment flows.

- [E2E tests](https://github.com/stan-smith/fossflow/tree/HEAD/e2e-tests/tests): browser tests · End-to-end browser and deployment tests covering load, routing, import/export, undo, and placement. · `e2e-tests/tests`
- [Lib tests](https://github.com/stan-smith/fossflow/tree/HEAD/packages/fossflow-lib/src): unit tests · Jest coverage for schemas, reducers, hooks, utilities, and UI components. · `packages/fossflow-lib/src`

## Connections

- 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.
