Onboarding: alyssaxuu/flowy

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/alyssaxuu/flowy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Stale — last commit 2y ago

• 2 active contributors
• MIT licensed
• ⚠ Stale — last commit 2y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 99% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live alyssaxuu/flowy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/alyssaxuu/flowy.

What it runs against: a local clone of alyssaxuu/flowy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in alyssaxuu/flowy | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 692 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>alyssaxuu/flowy</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of alyssaxuu/flowy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/alyssaxuu/flowy.git
#   cd flowy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of alyssaxuu/flowy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "alyssaxuu/flowy(\\.git)?\\b" \\
  && ok "origin remote is alyssaxuu/flowy" \\
  || miss "origin remote is not alyssaxuu/flowy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "engine/flowy.js" \\
  && ok "engine/flowy.js" \\
  || miss "missing critical file: engine/flowy.js"
test -f "engine/flowy.css" \\
  && ok "engine/flowy.css" \\
  || miss "missing critical file: engine/flowy.css"
test -f "demo/index.html" \\
  && ok "demo/index.html" \\
  || miss "missing critical file: demo/index.html"
test -f "demo/main.js" \\
  && ok "demo/main.js" \\
  || miss "missing critical file: demo/main.js"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 692 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~662d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/alyssaxuu/flowy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Flowy is a vanilla JavaScript library (41KB of code, no dependencies) that enables drag-and-drop flowchart creation in web applications. It provides automatic block snapping, canvas scrolling, block rearrangement, and data persistence — allowing developers to build automation tools, mind maps, or visual programming environments by adding the library and marking draggable elements with the .create-flowy CSS class. Monolithic structure: the core engine lives in /engine/flowy.js and /engine/flowy.css, with minified production builds at root (flowy.min.js). The /demo/ directory contains a complete working example (demo/index.html, demo/main.js, demo/styles.css) showcasing the API. Assets are SVG icons in /demo/assets/. No src/ folder or build toolchain visible — minification likely happens externally.

Who it's for

Web developers building visual workflow editors, automation platforms, or mind-mapping tools who want flowchart functionality without learning D3.js or React Flow. Specifically targets developers who prefer lightweight, dependency-free solutions and need mobile-friendly drag-and-drop interfaces.

Maturity & risk

Experimental but polished for its scope. The repo shows 41KB of production-grade JavaScript with a working live demo (alyssax.com/x/flowy) and has received social validation (Dribbble shot, Twitter presence). However, the absence of package.json, test suites, CI configuration (.github/workflows/), and npm publishing (see issue #10 in README) indicates it's a solo hobby project by Alyssa X rather than an enterprise-maintained library. No recent commit metadata is visible, making recency unclear.

Single-maintainer risk is high: no visible test coverage, no CI/CD pipeline, and the README acknowledges npm publication is a pending feature request. The library uses vanilla DOM manipulation without abstractions, so DOM API changes or browser quirks could require broad rewrites. No documented breaking change policy or semantic versioning visible. Dependency-free is an asset here, but lack of automated testing means regressions could slip into minified assets (flowy.min.js, flowy.min.css).

Active areas of work

Unknown from provided data. No commit history, PR list, or Issues dashboard visible in the file structure. The README mentions GitHub Sponsors and an open feature request for npm installation, suggesting the maintainer is open to contributions but the repo may be in maintenance mode rather than active development.

Get running

git clone https://github.com/alyssaxuu/flowy.git
cd flowy
# No npm install needed — open demo/index.html in a browser or serve with any HTTP server:
python3 -m http.server 8000
# Then visit http://localhost:8000/demo/

Daily commands: Open demo/index.html in a browser directly, or serve via any HTTP server (python3 -m http.server, npx http-server, etc.). The demo is self-contained; no build step required. For development, edit /engine/flowy.js and /engine/flowy.css, then manually minify or use a tool to update flowy.min.js and flowy.min.css.

Map of the codebase

• engine/flowy.js — Core library implementation containing all flowchart creation, drag-drop, snapping, and event handling logic—the entry point for the entire system
• engine/flowy.css — Stylesheet defining visual layout, positioning, and animations for flowchart blocks and connections—essential for understanding UI rendering
• demo/index.html — Reference implementation showing how to initialize Flowy, structure HTML blocks, and integrate the library into a working application
• demo/main.js — Concrete example of callback handlers, block creation, data export/import, and real-world Flowy API usage patterns
• README.md — Complete API documentation covering initialization, callbacks, methods, and usage examples—mandatory reference for understanding library contract

Components & responsibilities

• engine/flowy.js (Vanilla JavaScript, DOM API, event listeners) — Core state machine managing block positions, connections, drag operations, and serialization; exposes public API (export, import, callbacks)
  • Failure mode: Corrupted flowchart state if drag handlers are interrupted or callbacks throw exceptions
• engine/flowy.css (CSS3 (transform, transition, pointer-events), SVG styling) — Visual rendering: block layout, connection line styling, drag placeholder appearance, animations
  • Failure mode: Blocks invisible or misaligned if CSS is not loaded; drag feedback broken
• demo/main.js (JavaScript, localStorage API, event handlers) — Application layer: callback handlers, block creation, user interaction workflows, data persistence UI
  • Failure mode: Application logic errors if callbacks have bugs; data loss if export/import not implemented correctly
• demo/index.html (HTML5, inline SVG/images) — DOM structure: block templates, container element, script initialization, icon references
  • Failure mode: Flowy cannot initialize if container missing or blocks have wrong class names

Data flow

• User (drag interaction) → engine/flowy.js (event handler) — Mouse events trigger drag state updates; block position and connection state changes
• engine/flowy.js → engine/flowy.css — Core library updates DOM transform properties; CSS renders visual changes and animations
• engine/flowy.js → demo/main.js (callbacks) — Flowy triggers onGrab, onRelease, onSnap, onRearrange callbacks with block and connection context
• demo/main.js → engine/flowy.js (export/import) — Application calls flowy.export() to serialize state; calls flowy.import(data) to restore from saved JSON
• demo/main.js → Browser storage (localStorage) — Application persists exported flowchart JSON for session recovery

How to make changes

Add a new block type to your flowchart

1. Create a new HTML element with class 'block' and unique id in demo/index.html (demo/index.html)
2. Add custom SVG icon or image to demo/assets/ directory (demo/assets/)
3. Style the block type using custom classes in demo/styles.css (demo/styles.css)
4. Register the block in demo/main.js within the initialization callback to define its behavior (demo/main.js)

Implement custom block interaction handler

1. Read the onGrab, onRelease, onSnap, and onRearrange callback signatures in README.md (README.md)
2. Define callback function in demo/main.js to handle block events (e.g., validation, side effects) (demo/main.js)
3. Pass callback to flowy.setOnGrab(), setOnRelease(), etc. during initialization (demo/main.js)

Export and persist flowchart state

1. Call flowy.export() to serialize current flowchart structure as JSON (engine/flowy.js)
2. Store exported data in localStorage or send to backend in demo/main.js (demo/main.js)
3. On page load, retrieve saved data and call flowy.import(data) to restore flowchart (demo/main.js)

Customize flowchart visual appearance

1. Override Flowy default styles by adding CSS rules in demo/styles.css that target block and connection classes (demo/styles.css)
2. Modify engine/flowy.css variables (colors, sizes, animations) for global theme changes (engine/flowy.css)
3. Add custom block template HTML with data attributes in demo/index.html for dynamic styling (demo/index.html)

Why these technologies

• Vanilla JavaScript (no framework) — Enables minimal library footprint and zero external dependencies for easy integration into any web project
• CSS Grid/Flexbox + Transform — Provides performant DOM positioning without heavy animation libraries; avoids layout thrashing
• SVG icons — Scalable, crisp graphics that remain sharp at any zoom level; minimal file size compared to raster images

Trade-offs already made

• No state management library (Redux, MobX, etc.)

  • Why: Keeps library minimal and dependency-free; simpler learning curve for contributors
  • Consequence: Applications must manage complex flowchart state through callbacks; larger apps may need custom state layer

• DOM-based rather than canvas/WebGL rendering

  • Why: Simpler DOM manipulation, native HTML/CSS styling, better accessibility
  • Consequence: Performance degrades with very large flowcharts (1000+ blocks); not suitable for real-time collaborative editors

• Synchronous event model (no async handlers)

  • Why: Keeps event loop simple and predictable; easier to debug
  • Consequence: Callbacks cannot perform async validation; complex logic must happen outside event handler

Non-goals (don't propose these)

• Does not provide authentication or user management
• Does not include backend persistence or database integration
• Does not support real-time collaborative editing
• Does not render to canvas or WebGL for extreme scale (1000+ nodes)
• Does not include built-in undo/redo system
• Does not provide accessibility features beyond semantic HTML

Anti-patterns to avoid

• Global state mutation in callbacks (Medium) — demo/main.js (callback handlers): Callbacks receive block/connection data and can mutate external state; no immutability guarantees, risking silent state inconsistencies
• Synchronous DOM queries in drag loop — engine/flowy.js (drag event handler): undefined

Traps & gotchas

No minification toolchain visible — changes to /engine/flowy.js or .css require manual or external minification to update the root flowy.min.* files, or the minified versions will be stale. No test suite means visual regression testing must be manual (open demo in multiple browsers). The library relies on DOM class manipulation (.create-flowy) without validation, so markup must match exactly or blocks won't be draggable. Auto-scrolling behavior is hard-coded based on canvas geometry; custom scroll containers or nested canvases may not work. No TypeScript definitions exist, so IDE autocompletion will be limited.

Architecture

Concepts to learn

• Drag-and-drop event lifecycle — Flowy's core feature is built on mousedown/touchstart, mousemove/touchmove, and mouseup/touchend events with coordinate tracking; understanding browser event bubbling and preventDefault() is essential to extending or debugging block movement.
• Collision detection and snapping — The library automatically snaps blocks together when they're close — this requires bounding-box or distance-based collision math; modifying snap thresholds or adding conditional snapping (callbacks) requires understanding the geometry calculations.
• Canvas/DOM coordinate systems — Flowy tracks block positions in absolute coordinates and offsets them relative to the canvas container; confusion between pageX/pageY, clientX/clientY, and offsetX/offsetY is a common source of positioning bugs.
• JSON serialization for state persistence — The export() and import() methods convert the flowchart structure (nodes and edges) to/from JSON; understanding the data model (which fields are serialized, how connections are represented) is critical for saving and restoring diagrams.
• Touch event handling and mobile adaptation — The README advertises mobile support, meaning the code handles both mouse and touch events (touchstart, touchmove, touchend); polyfills or event normalization logic may exist to make desktop and mobile drag-and-drop work identically.
• CSS class-based styling and state — Flowy uses DOM classes (e.g., .create-flowy, likely .dragging, .snapped) to apply visual styles during interactions; the line between CSS presentation and JavaScript state management is blurred, so CSS changes can break functionality if class names are altered.
• Event delegation and dynamic element creation — Blocks can be added and removed dynamically; the library must use event delegation (attaching listeners to the canvas rather than individual blocks) to avoid memory leaks and ensure new blocks are immediately draggable.

Related repos

• burakcan/react-flow — React-based flowchart library with similar drag-and-drop, snapping, and export features; most direct modern alternative with TypeScript support and active maintenance.
• prabhuignoto/react-chrono — Timeline/flowchart component for React; shares the use case of visual workflow representation but focuses on timeline layouts rather than free-form node graphs.
• dagrejs/dagre — Graph layout engine (not drag-and-drop) that automatically positions flowchart nodes; often paired with D3.js or custom renderers for the visual layer that Flowy provides.
• cytoscape/cytoscape.js — Heavyweight graph visualization library with built-in layout algorithms, snapping, and mobile support; overlaps with Flowy's scope but for complex graph analytics use cases.
• alyssaxuu/wiggle — Sister project by the same author demonstrating interactive prototyping; similar vanilla JS, no-dependency philosophy and DOM manipulation patterns.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add ESLint configuration and enforce code quality standards

The repo has engine/flowy.js as the main source file but lacks any linting configuration (.eslintrc, .prettierrc). This would help maintain code consistency across contributions and catch common JavaScript issues early. Given that demo/ and engine/ both have JS files, establishing linting standards is critical before the codebase grows.

• [ ] Create .eslintrc.json with recommended rules for ES6+ JavaScript
• [ ] Create .prettierrc for consistent code formatting
• [ ] Add pre-commit hook configuration (.husky or similar) to engine/flowy.js
• [ ] Run linter against engine/flowy.js and demo/main.js, fix violations
• [ ] Document linting setup in README under a 'Development' section

Create unit tests for engine/flowy.js core functionality

There are no test files in the repo structure, making it difficult to verify that refactoring or new features don't break existing functionality. Since flowy.js is a library with public APIs (initialization, callbacks for 'on grab', 'on release', 'on snap'), unit tests would provide confidence for contributors and maintainers.

• [ ] Set up Jest or Vitest configuration at repo root (package.json, jest.config.js)
• [ ] Create test/flowy.test.js covering initialization and basic flowchart creation
• [ ] Add tests for callback functions mentioned in README (on grab, on release, on snap)
• [ ] Test DOM manipulation (adding nodes, connections between nodes)
• [ ] Add test command to package.json and document in README's 'Running Tests' section

Add TypeScript definitions file (flowy.d.ts) for better IDE support

The library currently lacks TypeScript definitions, which limits adoption among TypeScript projects and reduces IDE autocomplete/type-checking capabilities. Creating a .d.ts file would help developers understand the API surface without reading the source code.

• [ ] Create engine/flowy.d.ts with type definitions for all exported functions and classes
• [ ] Document the main initialization function signature, callback parameters, and options object structure
• [ ] Add 'types' field pointing to 'engine/flowy.d.ts' in package.json (if it exists)
• [ ] Include example TypeScript usage in README under an 'TypeScript Support' section
• [ ] Test definitions work by creating a demo/index.ts that uses the library

Good first issues

• Add unit tests: Create a /test/ directory with Jest or Mocha specs for core functions in flowy.js (drag event handler, snapping algorithm, data serialization). Currently there are zero tests, making it impossible to verify refactors or catch regressions.
• Document the data format: The README mentions flowy.export() and flowy.import() methods but doesn't specify the JSON schema. Create a /docs/data-format.md file with examples of the exported structure and edge cases (nested blocks, circular references).
• Add TypeScript definitions: Create flowy.d.ts with type signatures for the flowy() function, callback parameters, and export/import return types. This would enable better IDE support and catch integration bugs early.

Top contributors

• @alyssaxuu — 99 commits
• @aelassas — 1 commits

Recent commits

• e977380 — Update README.md (alyssaxuu)
• 8efa428 — Update flowy.min.js (alyssaxuu)
• 23bd976 — Update flowy.min.js (alyssaxuu)
• f5a0b10 — Rearrange fix (alyssaxuu)
• 1bda310 — Optimizations (alyssaxuu)
• 0502ee0 — Optimizations (alyssaxuu)
• 3072a16 — Optimizations (alyssaxuu)
• f144938 — Collapsible panel fix (alyssaxuu)
• d41781f — Collapsible panel fix (alyssaxuu)
• 3784bad — Collapsible panel fix (alyssaxuu)

Security observations

The Flowy library appears to be a lightweight, client-side JavaScript flowchart engine with a minimal attack surface. No critical vulnerabilities were identified from the visible file structure. However, the analysis is limited by the absence of a package.json file, making it impossible to assess dependency vulnerabilities. The main concerns are around supply chain security (missing dependency manifest), lack of security documentation, and the opacity of minified distribution files. For a production deployment, ensure proper dependency management, security policies, and clear integration guidelines for developers using this library.

• Medium · No Package.json or Dependency Lock File Provided — Repository root. The analysis was unable to identify the dependencies or their versions. Without a package.json or lock file (package-lock.json, yarn.lock), it's impossible to detect vulnerable dependencies. This is a common vector for supply chain attacks. Fix: Ensure package.json and lock files are present and regularly audit dependencies using 'npm audit' or 'yarn audit'. Keep dependencies up to date.
• Medium · Minified JavaScript Files in Distribution — flowy.min.js, flowy.min.css, demo/flowy.min.js, demo/flowy.min.css. The repository includes minified JavaScript files (flowy.min.js, flowy.min.css) without corresponding source maps or clear documentation. This makes security auditing difficult and obscures potential vulnerabilities in the distribution. Fix: Provide source maps (.map files) alongside minified assets for easier debugging. Ensure the minification process doesn't introduce security issues. Document the build process.
• Low · No Security.md or Security Policy — Repository root. There is no visible security.md or security policy file in the repository. This makes it difficult for security researchers to responsibly report vulnerabilities they may discover. Fix: Create a SECURITY.md file with clear instructions for reporting security vulnerabilities, responsible disclosure timeline, and contact information.
• Low · Missing Content Security Policy Documentation — README.md, engine/flowy.js. The library is a JavaScript flowchart engine that likely manipulates the DOM. Without clear documentation on CSP headers and XSS prevention measures, developers may integrate it unsafely. Fix: Document CSP requirements and best practices for safe integration. Clarify how the library handles user input and DOM manipulation.
• Low · No License SPDX Identifier in Package Metadata — LICENSE file. While a LICENSE file exists, there's no clear indication of dependency license compatibility or SPDX identifier in visible package metadata. Fix: Ensure package.json includes a clear 'license' field with SPDX identifier. Document any license restrictions for dependencies.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.