USER_MANUAL.md

B&W Flowchart Sketcher - User Manual

This manual provides a detailed guide on installing, launching, and designing beautiful black-and-white (B&W) flowcharts using either the Tkinter Desktop App (flowchart_app.py) or the Streamlit Web App (app.py).

---

Table of Contents

1. System Requirements & Installation
2. Interface Overview
3. Managing Nodes
4. Managing Edges (Connectors)
5. Arranging & Laying Out the Chart
6. Saving, Loading, & Exporting
7. Tips for Creating Professional Diagrams

---

1. System Requirements & Installation

Requirements

• Python: Version 3.8 or higher.
• Operating System: Windows, macOS, or Linux.

Installation Steps

1. Clone or download the repository to your local machine.
2. Install the necessary dependencies (primarily Pillow for image generation, and streamlit if running the web application):

   pip install Pillow streamlit
   

---

2. Interface Overview

The program provides a unified side-by-side workspace:

• Left Panel (Sidebar): Input forms, lists, action triggers, and file operations.
• Right Panel (Canvas): Live preview area rendering the flowchart. In the desktop version, this canvas is scrollable and fully interactive with drag-and-drop support.

---

3. Managing Nodes

Every node represents a step or symbol in your diagram.

Adding a New Node

1. Navigate to the Node Manager section in the sidebar.
2. Designation / Label (Short ID): Enter a short, unique name for the node (e.g., Start, Step 1, A, Q1). This ID serves as the identifier when connecting nodes with edges.
3. Icon Shape: Select a shape from the dropdown menu:
   • Circle: Typically used for start/end terminals or connectors.
   • Oval: Used for starting/ending process bounds.
   • Square: Standard process step, task, or operation.
   • Diamond: Decision point (creates branching paths).
   • Inverted Triangle: Data input/output, yield, or storage.
4. Description: Enter the text that will be displayed inside the node shape. This text automatically word-wraps to fit the shape boundaries.
5. Click Add/Save Node. The node will appear at the center of the canvas.

Editing an Existing Node

• Desktop: Click on a node in the Canvas. Its properties will load into the Node Manager. Change the shape or description, and click Save Node.
• Web: Type the node's Short ID into the form. The details will update once you click Add/Save Node.

Deleting a Node

Select the node (or enter its ID in the form) and click Delete Node. This will also remove any connecting edges associated with that node.

---

4. Managing Edges (Connectors)

Edges connect your nodes together. The application allows you to connect multiple nodes in a single input path.

Adding Edges

1. Locate the Edge Manager section in the sidebar.
2. Path: Input a path of nodes using delimiters. Supported formats:
   • Arrows: Start -> Step 1 -> Check
   • Commas: Start, Step 1, Check
   • Spaces: Start Step 1 Check
3. Connector Line Style: Select the style of the lines:
   • Straight: A crisp, direct line from the border of the source node to the border of the target node.
   • Curved: A smooth, sweeping Bezier curve that arcs around other elements (helpful for loops).
   • Dotted: A dashed, clean B&W line (often used for alternative flow paths or data streams).
4. Click Add Edges.

Deleting Edges

In the Edge List section:

1. Select the edge you wish to delete from the listbox (formatted as Source -> Target (Style)).
2. Click Delete Selected Edge.

---

5. Arranging & Laying Out the Chart

The application provides both automatic sorting and manual positioning.

Auto-Layout

Click the Auto-Layout button under Actions. The application will compute a clean, hierarchical tree layout from top to bottom based on the flow direction of your edges. Disconnected nodes or cycles will be handled gracefully.

Manual Adjustments

• Desktop (Drag-and-Drop): Left-click on any node in the canvas and drag it with your mouse to your desired position. All arrows will stretch and pivot in real-time.
• Web (Coordinate Sliders): Expand the Manual Node Positioning section in the sidebar, select a node, and slide the X and Y coordinate controls to reposition it precisely.

---

6. Saving, Loading, & Exporting

Save / Load Projects (JSON)

To save your work so you can edit it later:

• Click Save Project (Desktop) or Download JSON Project File (Web). This saves the configurations of all nodes (positions, shapes, text) and edges to a lightweight .json file.
• Click Load Project (Desktop) or Upload JSON Project (Web) and select a previously saved .json file to restore the chart.

Exporting Flowcharts (PNG)

To export the diagram for use in your documents, slides, or papers:

1. Click Export PNG (Desktop) or Download Flowchart Image (Web).
2. Save the file.
3. The exported PNG features:
   • A clean white background (grid lines and editing highlights are hidden).
   • High-contrast B&W rendering.
   • Auto-Cropping: The image bounds are automatically cropped to the contents of the flowchart with a clean 50px border margin (no wasted blank space).

---

7. Tips for Creating Professional Diagrams

• Use the Grid: In the desktop app, visual gridlines help you align nodes.
• Looping Back: When drawing a connector that loops back to a previous stage (e.g. Error -> Start), set the edge style to Curved so it bows outward and does not overlap your straight, forward-flowing arrows.
• Decision Branches: For diamonds (decisions), try to route one branch straight down and the other out to the side to keep the flow readable.
• Short Texts: Keep description labels concise. Long descriptions will wrap to multiple lines, which can crowd smaller shapes like diamonds or circles.