FossFLOW - Isometric Diagramming Tool <img width="30" height="30" alt="fossflow" src="https://github.com/user-attachments/assets/56d78887-601c-4336-ab87-76f8ee4cde96" />

<a href="README.md">English</a> | <a href="docs/README.cn.md">简体中文</a> | <a href="docs/README.es.md">Español</a> | <a href="docs/README.pt.md">Português</a> | <a href="docs/README.fr.md">Français</a> | <a href="docs/README.hi.md">हिन्दी</a> | <a href="docs/README.bn.md">বাংলা</a> | <a href="docs/README.ru.md">Русский</a> | <a href="docs/README.id.md">Bahasa Indonesia</a> | <a href="docs/README.de.md">Deutsch</a> <a href="https://trendshift.io/repositories/15118" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15118" alt="stan-smith%2FFossFLOW | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

Hey! Stan here, if you've used FossFLOW and it's helped you, I'd really appreciate if you could donate something small :) I work full time, and finding the time to work on this project is challenging enough. If you've had a feature that I've implemented for you, or fixed a bug it'd be great if you could :) if not, that's not a problem, this software will always remain free!

Also! If you haven't yet, please check out the underlying library this is built on by <a href="https://github.com/markmanx/isoflow">@markmanx</a> I truly stand on the shoulders of a giant here 🫡

Thanks,

-Stan

Try it online

Go to --> https://stan-smith.github.io/FossFLOW/ <-- <a href="https://github.com/stan-smith/SlingShot"> Check out my latest project: SlingShot - Dead easy video streaming over QUIC </a>

FossFLOW is a powerful, open-source Progressive Web App (PWA) for creating beautiful isometric diagrams. Built with React and the <a href="https://github.com/markmanx/isoflow">Isoflow</a> (Now forked and published to NPM as fossflow) library, it runs entirely in your browser with offline support.

Screenshot_20250630_160954

🤝 CONTRIBUTING.md - How to contribute to the project.

🐳 Quick Deploy with Docker

# Using Docker Compose (recommended - includes persistent storage)
docker compose up

# Or run directly from Docker Hub with persistent storage
docker run -p 80:80 -v $(pwd)/diagrams:/data/diagrams stnsmith/fossflow:latest

Server storage is enabled by default in Docker. Your diagrams will be saved to ./diagrams on the host.

To disable server storage, set ENABLE_SERVER_STORAGE=false:

docker run -p 80:80 -e ENABLE_SERVER_STORAGE=false stnsmith/fossflow:latest

HTTP Basic Authentication (Optional)

Protect your FossFLOW instance with HTTP Basic Auth:

# With Docker Compose
HTTP_AUTH_USER=admin HTTP_AUTH_PASSWORD=secret docker compose up

# Or with docker run
docker run -p 80:80 \
  -e HTTP_AUTH_USER=admin \
  -e HTTP_AUTH_PASSWORD=secret \
  stnsmith/fossflow:latest

Note: Both variables must be set to enable authentication. If either is empty, the app is accessible without login.

Quick Start (Local Development)

# Clone the repository
git clone https://github.com/stan-smith/FossFLOW
cd FossFLOW

# Install dependencies
npm install

# Build the library (required first time)
npm run build:lib

# Start development server
npm run dev

Open http://localhost:3000 in your browser.

Monorepo Structure

This is a monorepo containing two packages:

packages/fossflow-lib - React component library for drawing network diagrams (built with Webpack)
packages/fossflow-app - Progressive Web App which wraps the lib and presents it (built with RSBuild)

Development Commands

# Development
npm run dev          # Start app development server
npm run dev:lib      # Watch mode for library development

# Building
npm run build        # Build both library and app
npm run build:lib    # Build library only
npm run build:app    # Build app only

# Testing & Linting
npm test             # Run unit tests
npm run lint         # Check for linting errors

# E2E Tests (Selenium)
cd e2e-tests
./run-tests.sh       # Run end-to-end tests (requires Docker & Python)

# Publishing
npm run publish:lib  # Publish library to npm

How to Use

Creating Diagrams

Add Items:
- Press the "+" button on the top right menu, the library of components will appear on the left
- Drag and drop components from the library onto the canvas
- Or right-click on the grid and select "Add node"
Connect Items:
- Select the Connector tool (press 'C' or click connector icon)
- Click mode (default): Click first node, then click second node
- Drag mode (optional): Click and drag from first to second node
- Switch modes in Settings → Connectors tab
Save Your Work:
- Quick Save - Saves to browser session
- Export - Download as JSON file
- Import - Load from JSON file

Storage Options

Session Storage: Temporary saves cleared when browser closes
Export/Import: Permanent storage as JSON files
Auto-Save: Automatically saves changes every 5 seconds to session

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Documentation

FOSSFLOW_ENCYCLOPEDIA.md - Comprehensive guide to the codebase
CONTRIBUTING.md - Contributing guidelines

License

MIT

FossFLOW

Install / Use

README