FOSSFLOW_ENCYCLOPEDIA.md
Last Updated: October 2025 Original Created: August 14, 2025 (commit 94bf3c0) Major Updates: 79 commits since creation including backend storage, i18n, lasso tools, and connector enhancements
FossFLOW is a monorepo containing both a React component library for drawing isometric network diagrams (fossflow-lib), a Progressive Web App that uses this library (fossflow-app), and an optional backend server for persistent storage (fossflow-backend). This encyclopedia provides a comprehensive guide to navigating and understanding the codebase structure, making it easy to locate specific functionality and understand the architecture.
fossflow-monorepo/
├── packages/
│ ├── fossflow-lib/ # React component library
│ │ ├── src/ # Library source code
│ │ │ ├── Isoflow.tsx # Main component entry
│ │ │ ├── index.tsx # Development entry
│ │ │ ├── config/ # Configuration (NEW)
│ │ │ │ ├── hotkeys.ts # Hotkey profiles
│ │ │ │ ├── panSettings.ts
│ │ │ │ └── zoomSettings.ts
│ │ │ ├── components/ # React components
│ │ │ ├── stores/ # State management (Zustand)
│ │ │ ├── hooks/ # Custom React hooks
│ │ │ ├── types/ # TypeScript types
│ │ │ ├── schemas/ # Zod validation
│ │ │ ├── interaction/ # Interaction handling
│ │ │ ├── i18n/ # Translations (NEW)
│ │ │ │ ├── en-US.ts
│ │ │ │ └── zh-CN.ts
│ │ │ ├── utils/ # Utility functions
│ │ │ ├── assets/ # Static assets
│ │ │ └── styles/ # Styling
│ │ ├── webpack.config.js # Webpack configuration
│ │ ├── package.json # Library dependencies
│ │ └── tsconfig.json # TypeScript config
│ │
│ ├── fossflow-app/ # Progressive Web App
│ │ ├── src/ # App source code
│ │ │ ├── index.tsx # App entry point
│ │ │ ├── App.tsx # Main app component
│ │ │ ├── components/ # App-specific components
│ │ │ ├── services/ # Services (storage)
│ │ │ ├── i18n.ts # i18n configuration (NEW)
│ │ │ ├── serviceWorkerRegistration.ts
│ │ │ └── setupTests.ts
│ │ ├── public/ # Static assets
│ │ │ └── locales/ # i18n translation files (NEW)
│ │ ├── rsbuild.config.ts # RSBuild configuration
│ │ ├── package.json # App dependencies
│ │ └── tsconfig.json # TypeScript config
│ │
│ └── fossflow-backend/ # Backend server (NEW - Added ~Aug 2025)
│ ├── server.js # Express server
│ ├── package.json # Backend dependencies
│ └── .env.example # Environment config template
│
├── package.json # Root workspace configuration
├── Dockerfile # Multi-stage Docker build
├── compose.yml # Docker Compose config
├── README.md # Project documentation
├── CONTRIBUTORS.md # Contributing guidelines
└── FOSSFLOW_TODO.md # Issues and roadmap
packages/fossflow-lib/src/index.tsx: Development mode entry with examplespackages/fossflow-lib/src/Isoflow.tsx: Main component exported for library usagepackages/fossflow-lib/src/index-docker.tsx: Docker-specific entry point<ThemeProvider>
<LocaleProvider> // i18n support (NEW)
<ModelProvider> // Core data model
<SceneProvider> // Visual state
<UiStateProvider> // UI interaction state
<App>
<Renderer /> // Canvas rendering
<UiOverlay /> // UI controls
</App>
</UiStateProvider>
</SceneProvider>
</ModelProvider>
</LocaleProvider>
</ThemeProvider>
Added: August 2025 (commit bf3a30f) Purpose: Optional Express.js server for persistent diagram storage
The backend package provides server-side storage capabilities, allowing diagrams to persist across browser sessions and devices. It's particularly useful in Docker deployments.
Location: /packages/fossflow-backend/
server.js)BACKEND_PORT)GET /api/storage/status
Response: { enabled: boolean, gitBackup: boolean, version: string }
GET /api/diagrams
Response: Array<{ id, name, lastModified, size }>
GET /api/diagrams/:id
Response: Diagram JSON data
POST /api/diagrams/:id
Body: Diagram JSON data
Response: { success: boolean, message: string }
DELETE /api/diagrams/:id
Response: { success: boolean }
Environment Variables (.env):
ENABLE_SERVER_STORAGE: Enable/disable storage endpoints (default: true)STORAGE_PATH: Directory for diagram files (default: /data/diagrams)BACKEND_PORT: Server port (default: 3001)ENABLE_GIT_BACKUP: Enable Git version control (default: false)/data/diagrams/ (or STORAGE_PATH){diagram-id}.jsonApp Service (packages/fossflow-app/src/services/storageService.ts):
src/stores/modelStore.tsx)Purpose: Core business data
Key Data:
items: Diagram elements (nodes)views: Different diagram perspectivesicons: Available icon librarycolors: Color paletteNew Features (since Aug 2025):
Location: /packages/fossflow-lib/src/stores/modelStore.tsx
Types: /packages/fossflow-lib/src/types/model.ts
src/stores/sceneStore.tsx)Purpose: Visual/rendering state
Key Data:
connectors: Path and position dataconnectorLabels: New flexible label system (Added: commit d5e02ea)textBoxes: Size informationNew Features (since Aug 2025):
Location: /packages/fossflow-lib/src/stores/sceneStore.tsx
Types: /packages/fossflow-lib/src/types/scene.ts
src/stores/uiStateStore.tsx)Purpose: User interface state
Key Data:
zoom: Current zoom levelscroll: Viewport positionmode: Interaction modeeditorMode: Edit/readonly statehotkeyProfile: Selected hotkey scheme (NEW)panSettings: Pan control configuration (NEW)connectorInteractionMode: 'click' or 'drag' (NEW)locale: Current language (NEW)New Features (since Aug 2025):
Location: /packages/fossflow-lib/src/stores/uiStateStore.tsx
Types: /packages/fossflow-lib/src/types/ui.ts
The FossFLOW application is a Progressive Web App (PWA) built with RSBuild that provides a complete diagram editor interface using the fossflow-lib library.
packages/fossflow-app/src/index.tsx)packages/fossflow-app/src/App.tsx)Major Updates (since Aug 2025):
packages/fossflow-app/src/serviceWorkerRegistration.tspackages/fossflow-lib/src/components/Renderer/)Renderer.tsx: Container componentsrc/components/UiOverlay/)UiOverlay.tsx: Control panel containersrc/components/SceneLayer/)SceneLayer.tsx: Transform containerpackages/fossflow-lib/src/components/SceneLayers/)/Nodes/)Node.tsx: Individual node componentNodes.tsx: Node collection rendererIsometricIcon.tsx: 3D-style iconsNonIsometricIcon.tsx: Flat icons/Connectors/)Connector.tsx: Individual connectorConnectors.tsx: Connector collection/ConnectorLabels/) [NEW]Added: August 2025 (commit d5e02ea) Purpose: Multiple labels along connector paths
Key Files:
ConnectorLabel.tsx: Individual label componentConnectorLabels.tsx: Label collection rendererFeatures:
Related Utilities:
/src/utils/connectorLabels.ts: Label migration and positioning logic/Rectangles/)Rectangle.tsx: Individual rectangleRectangles.tsx: Rectangle collection/TextBoxes/)TextBox.tsx: Individual text boxTextBoxes.tsx: Text box collection/Lasso/)Added: August 2025 (commit fec8878) Purpose: Rectangle-based multi-selection
Key Files:
Lasso.tsx: Rectangle lasso componentFeatures:
/FreehandLasso/)Added: August 2025 (commit 96047f3) Purpose: Freeform multi-selection
Key Files:
FreehandLasso.tsx: Freehand lasso componentFeatures:
Interaction Modes:
/src/interaction/modes/Lasso.ts: Rectangle lasso mode/src/interaction/modes/FreehandLasso.ts: Freehand lasso modepackages/fossflow-lib/src/components/MainMenu/)packages/fossflow-lib/src/components/ToolMenu/)packages/fossflow-lib/src/components/ItemControls/)/NodeControls/: Node properties
QuickIconSelector.tsx: Quick icon picker (NEW - commit 8576e30)/ConnectorControls/: Connector properties
/RectangleControls/: Rectangle properties/TextBoxControls/: Text properties/IconSelectionControls/: Icon picker
HotkeySettings (/HotkeySettings/)
Added: August 2025 (commit ef258df)
Purpose: Configure keyboard shortcuts
Features:
ConnectorSettings (/ConnectorSettings/)
Added: August 2025 (commit 5ff21cc)
Purpose: Configure connector creation mode
Features:
PanSettings (/PanSettings/)
Added: August 2025 (commit 83c9b3a)
Purpose: Configure pan controls
Features:
Added: August-September 2025 (commits 9d9a0dd, a2a47b4, 5df41f9)
ConnectorHintTooltip (/ConnectorHintTooltip/)
ConnectorRerouteTooltip (/ConnectorRerouteTooltip/)
ConnectorEmptySpaceTooltip (/ConnectorEmptySpaceTooltip/)
LassoHintTooltip (/LassoHintTooltip/)
ImportHintTooltip (/ImportHintTooltip/)
packages/fossflow-lib/src/components/TransformControlsManager/)TransformAnchor.tsx: Resize handlesNodeTransformControls.tsx: Node-specific controls/ErrorBoundary/) [NEW]Added: August 2025 (commit 179b512) Purpose: Graceful error handling
Features:
/Grid/): Isometric grid overlay/Cursor/): Custom cursor display/ContextMenu/): Right-click menus/ZoomControls/): Zoom in/out buttons
/ColorSelector/): Color picker UI/ExportImageDialog/): Export to PNG dialog
Added: August 2025 (commits ef258df, 83c9b3a)
The configuration system provides type-safe, centralized settings for hotkeys, pan controls, and zoom behavior.
Location: /packages/fossflow-lib/src/config/
hotkeys.ts)Purpose: Define keyboard shortcuts for tools
Types:
type HotkeyProfile = 'qwerty' | 'smnrct' | 'none';
Profiles:
QWERTY (Q-W-E-R-T-Y layout):
SMNRCT (Default - S-M-N-R-C-T layout):
None: All hotkeys disabled
Usage:
panSettings.ts)Purpose: Configure pan/scroll controls
Settings:
Mouse Options:
middleClickPan: Middle mouse button (default: true)rightClickPan: Right mouse buttonctrlClickPan: Ctrl+ClickaltClickPan: Alt+ClickemptyAreaClickPan: Click empty canvas area (default: true)Keyboard Options:
arrowKeysPan: Arrow keys (default: true)wasdPan: WASD keysijklPan: IJKL keyskeyboardPanSpeed: Pan distance (default: 20px)zoomSettings.ts)Purpose: Zoom behavior configuration
Settings:
Added: August 2025 (commits 2145981, 5d6cf0e, a2a47b4)
FossFLOW supports multiple languages using react-i18next with automatic language detection.
packages/fossflow-lib/src/i18n/)Supported Languages:
en-US.ts: English (default)zh-CN.ts: Simplified Chinese (added commit 556ef4a)Translation Structure:
{
tools: { select: "Select", pan: "Pan", ... },
contextMenu: { addNode: "Add Node", ... },
settings: { hotkeys: "Hotkeys", ... },
tooltips: { connector: "Click mode: ...", ... }
}
Components:
/src/stores/localeStore.tsx: Locale state management/src/components/ChangeLanguage/: Language switcher (app-level)packages/fossflow-app/src/)Configuration: i18n.ts
Translation Files: public/locales/{lang}/app.json
Features (commit 4d12c01):
The project uses NPM workspaces to manage three packages:
/packages/fossflow-lib/webpack.config.js/packages/fossflow-app/rsbuild.config.tsbuild/ directory"type": "module" in package.json# Development
npm run dev # Start app development server
npm run dev:lib # Watch mode for library development
npm run dev:backend # Start backend server (NEW)
# Building
npm run build # Build both library and app
npm run build:lib # Build library only
npm run build:app # Build app only
# Testing & Quality
npm test # Run tests in all workspaces
npm run lint # Lint all workspaces
# Publishing
npm run publish:lib # Build and publish library to npm
# Docker
npm run docker:build # Build Docker image locally
npm run docker:run # Run with Docker Compose
# Clean
npm run clean # Clean all build artifacts
# Multi-stage build
FROM node:22 AS build
WORKDIR /app
# Install dependencies for monorepo
RUN npm install
# Build library first, then app
RUN npm run build:lib && npm run build:app
# Production stage with backend
FROM node:22-alpine
# Install backend dependencies
COPY packages/fossflow-backend /app/backend
# Copy built frontend
COPY --from=build /app/packages/fossflow-app/build /app/frontend
# Start backend server serving frontend
Updates (commit bf3a30f):
packages/fossflow-lib/src/**/__tests__/packages/fossflow-app/src/**/*.test.tsxpackages/fossflow-lib/src/fixtures//packages/fossflow-lib/src/schemas/__tests__/: Schema validation (completed ✅)/packages/fossflow-lib/src/stores/reducers/__tests__/: State logic
/packages/fossflow-lib/src/utils/__tests__/: Utility functionsUpdates (commits 70b1f56, 2bd1318):
git clone https://github.com/stan-smith/FossFLOW
cd FossFLOW
npm install # Installs dependencies for all workspaces
# First build the library (required for initial setup)
npm run build:lib
# Start app development (includes library in dev mode)
npm run dev
# Optional: Start backend server in separate terminal
npm run dev:backend
packages/fossflow-lib/src/packages/fossflow-app/src/packages/fossflow-backend/server.jspackages/fossflow-lib/src/config.ts)Key Constants:
TILE_SIZE: Base tile dimensionsDEFAULT_ZOOM: Initial zoom levelDEFAULT_FONT_SIZE: Text defaultsINITIAL_DATA: Default model statepackages/fossflow-lib/src/hooks/)Common Hooks:
useScene.ts: Merged scene datauseModelItem.ts: Individual item access (returns ModelItem | null)useViewItem.ts: View item access (returns ViewItem | null)useConnector.ts: Connector management (returns Connector | null)useRectangle.ts: Rectangle access (returns Rectangle | null)useTextBox.ts: Text box access (returns TextBox | null)useIcon.tsx: Icon access (returns Icon | null)useColor.ts: Color access (returns Color | null)useIsoProjection.ts: Coordinate conversionuseDiagramUtils.ts: Diagram operationsuseHistory.ts: Undo/redo transaction system [NEW]Important: All item access hooks now return null instead of throwing when items don't exist, preventing React unmount errors.
packages/fossflow-lib/src/interaction/)Main File: useInteractionManager.ts
Interaction Modes (/modes/):
Cursor.ts: Selection modePan.ts: Canvas panningPlaceIcon.ts: Icon placement
Connector.ts: Drawing connections
DragItems.ts: Moving elementsRectangle/: Rectangle toolsTextBox.ts: Text editingLasso.ts: Rectangle lasso selection [NEW]FreehandLasso.ts: Freehand lasso selection [NEW]packages/fossflow-lib/src/utils/)Key Utilities:
CoordsUtils.ts: Coordinate calculationsSizeUtils.ts: Size computationsrenderer.ts: Rendering helpersmodel.ts: Model manipulationpathfinder.ts: Connector routingconnectorLabels.ts: Label migration and positioning [NEW]common.ts: Common helpers
getItemById: Null-safe item access (prevents errors)packages/fossflow-lib/src/types/)Core Types:
model.ts: Business data types
ConnectorLabel interface (commit d5e02ea)scene.ts: Visual state typesui.ts: Interface types
common.ts: Shared typesinteractions.ts: Interaction typesisoflowProps.ts: Component prop typespackages/fossflow-lib/src/schemas/)Validation Schemas:
model.ts: Model validationconnector.ts: Connector validation
rectangle.ts: Rectangle validationtextBox.ts: Text box validationviews.ts: View validationAdded: August 2025 (contributor: pi22by7) Status: ⚠️ Implemented but has known issues under investigation
The undo/redo system uses a transaction-based approach to ensure atomic operations:
Key Components:
useHistory.ts)Key File: /packages/fossflow-lib/src/hooks/useHistory.ts
API:
const { undo, redo, canUndo, canRedo, transaction } = useHistory();
// Group multiple operations
transaction(() => {
// Multiple state changes here
// All will be undone/redone together
});
Important Considerations:
⚠️ Current Status: Stan is investigating edge cases and bugs in the undo/redo system. While functional for basic operations, some complex interactions may cause issues.
Problem: Components can try to access deleted items during React unmounting Solution: Graceful null handling throughout the codebase
Key Changes:
getItemById utility that returns null instead of throwingnull when items don't existAffected Files:
/src/utils/common.ts: Added getItemById function/src/hooks/: Updated to handle missing itemsRelated Fixes:
Icons? → /src/components/ItemControls/IconSelectionControls/
Custom icon import? → /src/components/ItemControls/IconSelectionControls/IconGrid.tsx
Node rendering? → /src/components/SceneLayers/Nodes/
Connector drawing? → /src/components/SceneLayers/Connectors/
Connector labels? → /src/components/SceneLayers/ConnectorLabels/ [NEW]
Connector creation mode? → /src/interaction/modes/Connector.ts + /src/components/ConnectorSettings/ [NEW]
Lasso selection? → /src/components/Lasso/, /src/components/FreehandLasso/ [NEW]
Zoom behavior? → /src/stores/uiStateStore.tsx + /src/components/ZoomControls/
Grid display? → /src/components/Grid/
Export functionality? → /src/components/ExportImageDialog/
Color picker? → /src/components/ColorSelector/
Context menus? → /src/components/ContextMenu/
Keyboard shortcuts? → /src/interaction/useInteractionManager.ts + /src/config/hotkeys.ts [NEW]
Tool selection? → /src/components/ToolMenu/
Selection handles? → /src/components/TransformControlsManager/
Undo/Redo? → /src/hooks/useHistory.ts [NEW]
i18n translations? → /src/i18n/en-US.ts, /src/i18n/zh-CN.ts [NEW]
Server storage? → /packages/fossflow-backend/server.js [NEW]
Pan settings? → /src/config/panSettings.ts + /src/components/PanSettings/ [NEW]
Tooltips? → Various /src/components/*Tooltip/ components [NEW]
How items are positioned? → /src/hooks/useIsoProjection.ts
How connectors find paths? → /src/utils/pathfinder.ts
How state updates work? → /src/stores/reducers/
How validation works? → /src/schemas/
Available icons? → /src/fixtures/icons.ts
Default configurations? → /src/config.ts + /src/config/* [NEW]
How labels are positioned? → /src/utils/connectorLabels.ts [NEW]
How transactions work? → /src/hooks/useHistory.ts [NEW]
How i18n works? → /src/i18n/, /src/stores/localeStore.tsx [NEW]
Backend API? → /packages/fossflow-backend/server.js [NEW]
| Purpose | File Path | Notes |
|---|---|---|
| Main entry | /src/Isoflow.tsx | |
| Configuration | /src/config.ts | |
| Hotkey config | /src/config/hotkeys.ts | [NEW] |
| Pan settings | /src/config/panSettings.ts | [NEW] |
| Model types | /src/types/model.ts | Updated with ConnectorLabel |
| UI state types | /src/types/ui.ts | Updated with hotkeys, pan, locale |
| Model store | /src/stores/modelStore.tsx | With undo/redo |
| Scene store | /src/stores/sceneStore.tsx | With connector labels |
| UI store | /src/stores/uiStateStore.tsx | With new settings |
| Locale store | /src/stores/localeStore.tsx | [NEW] |
| Main renderer | /src/components/Renderer/Renderer.tsx | |
| UI overlay | /src/components/UiOverlay/UiOverlay.tsx | With tooltips |
| Interaction manager | /src/interaction/useInteractionManager.ts | Updated modes |
| Coordinate utils | /src/utils/CoordsUtils.ts | |
| Connector labels util | /src/utils/connectorLabels.ts | [NEW] |
| History/Undo hook | /src/hooks/useHistory.ts | [NEW] |
| Public API hook | /src/hooks/useIsoflow.ts | |
| Backend server | /packages/fossflow-backend/server.js | [NEW] |
| App i18n config | /packages/fossflow-app/src/i18n.ts | [NEW] |
| English translations | /src/i18n/en-US.ts | [NEW] |
| Chinese translations | /src/i18n/zh-CN.ts | [NEW] |
This encyclopedia serves as a comprehensive guide to the FossFLOW codebase. Use the table of contents and quick references to efficiently navigate to the areas you need to modify or understand.
For Contributors: See CONTRIBUTORS.md for contribution guidelines and FOSSFLOW_TODO.md for current issues and roadmap.