Neo4j Arrows

neo4j-arrows-app is a web-based tool designed for drawing pictures of graphs. It is composed of two primary parts:

1. Dependency-free JS code: Used for rendering graphs to Canvas and SVG.
2. React-Redux application: A full application for creating and editing graph pictures.

It is the logical successor to the original apcj/arrows project but is a complete rewrite with no shared code.

The tool provides the following capabilities:

• Intuitive Drawing: Quick graph creation using a mouse.
• Neo4j Property Graph Model Support: Explicit support for nodes, relationships, properties, and labels.
• Fine-grained Styling: Precise control over sizes, positions, and colors.
• Image Export: Ability to export graphs as images, primarily for use in documents or presentations.
• Cypher Export: Ability to export the drawn graph as Cypher queries to recreate the graph in a Neo4j database.

The @arrows-code/format-json package provides utilities to read, write, and canonicalize the .arrows JSON format. It is designed to ensure structural equality and stability when working with graph data in this specific format.

import { readGraph, writeGraph, canonicalize } from '@arrows-code/format-json';

// Read a graph from a string
const { graph, diagnostics } = readGraph(text);

// Write a graph object back to a string
const text = writeGraph(graph);

// Get a normalized version of the graph
const normalized = canonicalize(graph);

The extension provides several tools for graph modeling within your development environment:

• Canvas Editor: Visual editing for .arrows files.
• Two-way Sync: Real-time synchronization between the visual canvas and the underlying JSON file.
• Exporting: Support for exporting graphs to Cypher or SVG.
• Validation: A built-in validator that flags broken graphs in the VS Code Problems panel.
• Refactoring: Project-wide rename functionality for labels and relationship types.
• Sidebar: Access to workspace .arrows files and bundled examples.

Tasks within the migration specification follow a specific format and organizational structure:

• Task Format: [ID] [P?] [Story] Description
• Task Types: [P] tasks represent different files or tasks that have no dependency on other tasks within the same phase.
• Traceability: The [Story] label maps a task to a specific User Story.
• Testing: Each user story is designed to be independently testable per the "Independent Test" specification.
• File Paths: All paths are relative to the repository root. The primary application is located at apps/arrows-ts/.

The extension uses a plain JSON format identical to the web-based arrows.app. This allows for two-way synchronization: you can edit the visual canvas or the JSON text, and both will stay in sync.

When modeling your graphs, follow these naming conventions to ensure compatibility with Neo4j Cypher exports:

• Labels: PascalCase (e.g., User)
• Relationship Types: SCREAMING_SNAKE_CASE (e.g., FOLLOWS_USER)
• Properties: camelCase (e.g., firstName)

The legacy gapi.drive.share.ShareClient is being replaced by direct usage of the Drive API v3.

To manage sharing, use Drive API endpoints to:

1. Create permissions for files.
2. Retrieve file metadata (such as webViewLink) to provide a "Copy link" feature.
3. Implement a minimal permissions control UI within the app using these API calls.

When performing the incremental migration of the Arrows codebase, follow these best practices to minimize regression:

• One slice at a time: Convert one reducer, its actions, its selectors, and its connected components as a single unit. This allows you to verify the app and tests after every logical change.
• Continuous Testing: Run nx run arrows-ts:test and end-to-end (e2e) tests after every phase or Pull Request.
• Branching Strategy: Use short-lived branches for each phase or feature area to keep the main branch buildable and green.
• Library Integrity: When extending libraries (Phase 1), ensure new exports are covered by unit tests and pass CI builds.

Modify the Redux reducer (e.g., reducers/googleDrive.js) to manage the new authentication state:

• State Keys: Add accessToken and optionally expiresAt to the state.
• Derived State: The signedIn status should be derived from the presence of a valid accessToken.
• Error Handling: If a 401 Unauthorized error is received from any Google Drive or Picker call, the application must clear the accessToken and set signedIn to false.