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](#1-system-requirements--installation)
2. [Interface Overview](#2-interface-overview)
3. [Managing Nodes](#3-managing-nodes)
4. [Managing Edges (Connectors)](#4-managing-edges-connectors)
5. [Arranging & Laying Out the Chart](#5-arranging--laying-out-the-chart)
6. [Saving, Loading, & Exporting](#6-saving-loading--exporting)
7. [Tips for Creating Professional Diagrams](#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):
   ```bash
   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.