flowdoc 0.0.0rc3

Generate business flow diagrams from Python code decorators

FlowDoc

Generate business flow diagrams from Python code decorators.

Unlike tools that trace technical execution paths, FlowDoc captures business logic flow -- the high-level process steps that describe what your application does from a business perspective. Annotate your code with lightweight decorators, and FlowDoc uses AST analysis to infer the flow graph and render it as a diagram.

✨ Features

• Inference over declaration -- annotate steps, and FlowDoc discovers connections by analyzing your code
• Pure AST analysis -- no code execution, safe to run on untrusted code
• Cross-module discovery -- analyze flows spanning multiple files with automatic file discovery
• Multiple output formats -- Mermaid markdown (default), PNG, SVG, PDF, DOT (Graphviz formats require optional graphviz extra)
• Docstring tooltips -- include @step docstrings as tooltips in SVG/DOT/Mermaid output
• Flexible patterns -- class-based flows, standalone functions, async/await, and web frameworks (FastAPI, Flask)
• Built-in validation -- detect dead steps, missing entry points, and other flow issues
• CLI included -- generate diagrams and validate flows from the command line

📦 Installation

pip install flowdoc

FlowDoc requires Python 3.10+. The base install supports Mermaid and DOT output with no extra dependencies.

For PNG, SVG, and PDF output, install the Graphviz extra and the Graphviz system package:

pip install flowdoc[graphviz]

🚀 Quick Start

Decorate your business logic with @flow and @step:

from flowdoc import flow, step

@flow(name="Order Processing", description="Handle customer orders")
class OrderProcessor:
    @step(name="Receive Order")
    def receive_order(self, order_data):
        return self.validate_payment(order_data)

    @step(name="Validate Payment")
    def validate_payment(self, order):
        if order.get("payment_valid"):
            return self.fulfill_order(order)
        else:
            return self.send_failure_email(order)

    @step(name="Fulfill Order")
    def fulfill_order(self, order):
        return self.send_confirmation(order)

    @step(name="Send Confirmation")
    def send_confirmation(self, order):
        return {"status": "confirmed", "order": order}

    @step(name="Send Failure Email")
    def send_failure_email(self, order):
        return {"status": "failed", "order": order}

Generate the diagram:

flowdoc generate order_processor.py

FlowDoc analyzes the code, detects that validate_payment branches into two paths, and produces a flowchart with decision diamonds, regular steps, and terminal nodes.

💻 Usage

CLI

# Generate a Mermaid diagram (default)
flowdoc generate mymodule.py

# Choose output format
flowdoc generate mymodule.py --format svg
flowdoc generate mymodule.py --format png
flowdoc generate mymodule.py --format dot

# Generate from a directory (cross-module discovery)
flowdoc generate src/

# Include docstrings as tooltips (SVG, DOT, Mermaid only)
flowdoc generate mymodule.py --format svg --docstrings

# Exclude directories during discovery
flowdoc generate src/ --exclude migrations --exclude scripts

# Validate a flow for issues
flowdoc validate mymodule.py

Programmatic API

from flowdoc import FlowParser, create_generator, FlowValidator

# Parse a single file
parser = FlowParser()
flows = parser.parse_file("mymodule.py")

# Or parse a directory (cross-module discovery)
flows = parser.parse_directory("src/")

# Generate a diagram
generator = create_generator("mermaid")
for flow_data in flows:
    generator.generate(flow_data, "output")

# Generate with docstring tooltips
generator = create_generator("svg", include_docstrings=True)
for flow_data in flows:
    generator.generate(flow_data, "output")

# Validate
validator = FlowValidator()
for flow_data in flows:
    messages = validator.validate(flow_data)
    for msg in messages:
        print(f"[{msg.level}] {msg.message}")

🔧 Supported Patterns

Class-based flows

Use @flow on a class and @step on its methods. FlowDoc detects self.method() calls to build the graph.

Function-based flows

Use @step on standalone functions. FlowDoc detects direct function calls between decorated functions.

from flowdoc import step

@step(name="Process Order")
def process_order(order_data):
    validated = validate_order(order_data)
    return charge_payment(validated)

@step(name="Validate Order")
def validate_order(order_data):
    return order_data

@step(name="Charge Payment")
def charge_payment(order):
    return {"status": "charged"}

Async functions

from flowdoc import step

@step(name="Create Order")
async def create_order(order):
    validated = await validate_order(order)
    return await save_order(validated)

Web framework integration

Works alongside FastAPI, Flask, and other decorator-based frameworks:

from fastapi import FastAPI
from flowdoc import step

app = FastAPI()

@app.post("/orders")
@step(name="Create Order Endpoint")
async def create_order(order: OrderData):
    validated = await validate_order(order)
    return await save_order(validated)

See examples/fastapi/app.py for a complete CRUD API example with @step decorators on endpoints.

App-factory functions

For FastAPI/Flask app-factory patterns, decorate the factory function itself with @flow. FlowDoc treats it as a flow boundary and discovers nested @step inner functions:

from fastapi import FastAPI
from flowdoc import flow, step

@flow(name="Order API")
def create_app() -> FastAPI:
    app = FastAPI()

    @app.post("/orders")
    @step(name="Create Order Endpoint")
    async def create_order(payload: dict):
        return await validate_order(payload)

    @step(name="Validate Order")
    async def validate_order(payload: dict):
        return payload

    return app

See examples/fastapi_factory.py for a runnable example.

Exception-handling branches

try/except/finally blocks are detected and labeled on edges, so business error paths (payment declines, retries, failure notifications) appear in the diagram:

@step(name="Process Payment")
def process_payment(self, order):
    try:
        return self.charge_card(order)
    except PaymentError:
        return self.send_failure_email(order)
    except NetworkError:
        return self.retry_later(order)
    finally:
        self.log_attempt(order)

Edges are labeled try, except PaymentError, except NetworkError, and finally. See examples/payment_retry.py.

⚙️ How It Works

FlowDoc uses Python's ast module to statically analyze decorated functions. For each @step, it walks the function body looking for:

• Method calls (self.other_method()) and function calls (other_function()) to other @step-decorated code
• Conditional branches (if/else) to identify decision points
• Exception handling (try/except/finally) -- except handlers label edges with the exception type (e.g. except PaymentError), enabling business error-handling flows
• Call count to determine node shapes: multiple outgoing calls produce a diamond (decision), zero calls produce an ellipse (terminal), and single calls produce a box (regular step)

No code is ever executed during analysis.

Limitations

These are intentional design constraints -- FlowDoc focuses on explicit, readable business flows:

• Dynamic decorator arguments: Use literal strings (@step(name="Process")) rather than variables
• Dynamic dispatch: getattr(self, name)() is not traced -- use explicit method calls
• External object calls: processor.handle() is not followed unless that object's methods are also decorated
• Indirect references: Passing functions as arguments is not traced -- use explicit if/else

❓ Troubleshooting

Graphviz not found

PNG, SVG, and PDF output requires both the Python graphviz package and the Graphviz system package.

Install the Python extra:

pip install flowdoc[graphviz]

Install the system package:

• macOS: brew install graphviz
• Ubuntu/Debian: sudo apt-get install graphviz
• Windows: Download from graphviz.org

Mermaid and DOT formats do not require Graphviz.

No flows found

Ensure your source file contains functions or methods decorated with @step. If using class-based flows, the class must also have the @flow decorator. FlowDoc only analyzes @step and @flow decorators -- it does not detect undecorated functions.

Dynamic decorator arguments

FlowDoc only supports literal string arguments in decorators. This works:

@step(name="Process Order")  # literal string

This does not:

step_name = "Process Order"
@step(name=step_name)  # variable -- not supported

Use literal strings in all decorator arguments for FlowDoc to detect them.

ImportError when running CLI

If you see ModuleNotFoundError: No module named 'flowdoc' after installation:

# Ensure you're using the correct Python environment
python -m flowdoc --version

# Or reinstall in your active environment
pip install --force-reinstall flowdoc

🛠️ Development

Setup

# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Install in development mode
uv pip install -e .

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=flowdoc --cov-report=term-missing

# Run a specific test
uv run pytest tests/test_parser.py::test_class_flow_parsing

Code quality

# Format
uv run ruff format .

# Lint (with auto-fix)
uv run ruff check . --fix

# Type check
uv run ty check flowdoc/

Project Structure

flowdoc/
├── flowdoc/
│   ├── __init__.py       # Public API exports
│   ├── decorators.py     # @flow and @step decorators
│   ├── discovery.py      # Cross-module file discovery
│   ├── parser.py         # AST analysis and flow extraction
│   ├── generator.py      # Graphviz and Mermaid diagram generators
│   ├── validator.py      # Flow validation logic
│   └── cli.py            # CLI (Click-based)
├── tests/                # pytest test suite
├── examples/             # Example flows
├── pyproject.toml
└── LICENSE               # MIT

🤝 Contributing

Contributions are welcome. To get started:

1. Fork the repository and create a feature branch
2. Install development dependencies with uv sync
3. Make your changes, adding tests for new functionality
4. Ensure all checks pass: uv run pytest, uv run ruff check ., uv run ty check flowdoc/
5. Submit a pull request

Please keep decorators minimal, avoid executing user code, and treat validation as advisory (warnings, not errors).

📄 License

MIT -- see LICENSE for details.