# SeeFlow

> Architecture diagrams that actually run, generated by AI agents.

![SeeFlow](./demo.gif)

Turn your static system architecture into a live control panel wired directly to your running application. Click a node, fire a real request, watch downstream services light up as your app emits events back.

## Why

- **Diagram drift** — Confluence pages go stale. SeeFlow breaks loudly when your actual system changes.
- **Onboarding friction** — New engineers click through a live flow instead of reading six-month-old docs.
- **Demo tedium** — Script it once, replay it flawlessly. No more manually clicking through microservices for stakeholders.

## Quick Start

The SeeFlow plugin reads your codebase, understands your architecture, and generates the full diagram and request scripts automatically. Works with Claude Code, Codex, Cursor, and Windsurf.

### 1. Start the studio

```bash
npx -y @tuongaz/seeflow@latest start
# then open http://localhost:4321
```

Requires Bun ≥ 1.3 (or Node with npx). The studio scans `$(pwd)/.seeflow/flow.json` on start and auto-registers that flow if present. Flows you create from the UI, plus the studio's registry, persist under `$(pwd)/.seeflow/` across restarts.

<details>
<summary>Prefer Docker? (not recommended)</summary>

> ⚠️ **Heads up:** Play and Status scripts run **inside** the container, so generated scripts that talk to services on your host — HTTP calls to `localhost`, host binaries like `psql` / `redis-cli`, your project's CLI — will not work. Interactive nodes are likely to fail. Use the native path above for full functionality.

```bash
docker run --rm -it -p 4321:4321 -v $(pwd):/workspace tuongaz/seeflow
```

The image ships with a pre-registered **Order Pipeline** demo so you can see the canvas immediately, and the studio scans `/workspace/.seeflow/flow.json` on start.

</details>

### 2. Install the plugin

**Skill installer (recommended):**

```bash
npx skills add tuongaz/seeflow
```

**Then just ask:**

```
/seeflow show me the shopping cart feature
```

The plugin scans your routes and database connections, generates `flow.json`, wires up demo scripts, and opens the canvas at localhost:4321.

### `/seeflow-wiki` — consult an existing flow

Once a flow is registered, agents can read it back as architectural ground truth:

```
/seeflow-wiki list                                    # catalog of registered flows
/seeflow-wiki flow <id>                               # nodes + connectors (no detail content)
/seeflow-wiki node <flowId> <nodeId>                  # single node with detail/html inlined
/seeflow-wiki flow <id> --full                        # everything inlined
/seeflow-wiki node <flowId> <nodeId> --with-scripts   # adds play.ts / status.ts bodies
```

Read-only. JSON output. Start cheapest (`list`) and drill in.

## Docker reference

> ⚠️ Docker is the non-preferred path. Play/Status scripts execute inside the container and cannot reach host services or host binaries, so interactive nodes generated against your local app will not work. Prefer `npx -y @tuongaz/seeflow@latest start` for the full experience.

The image is published on [Docker Hub](https://hub.docker.com/r/tuongaz/seeflow). See Quick Start above for the basic `docker run`.

### Configuration

| Variable            | Default                 | Description                                |
| ------------------- | ----------------------- | ------------------------------------------ |
| `SEEFLOW_PORT`      | `4321`                  | Port the studio listens on                 |
| `SEEFLOW_FLOW`      | `.seeflow/flow.json` | Flow file path relative to the workspace   |
| `SEEFLOW_WORKSPACE` | `/workspace`            | Workspace mount point inside the container |

### Bake demos into a derived image

Ship a container that already contains your flow:

```dockerfile
FROM tuongaz/seeflow
COPY ./my-demos /workspace
# docker build -t my-flow . && docker run --rm -it -p 4321:4321 my-flow
```

### Tags

- `:latest` — newest stable release
- `:<version>` — pinned release (e.g. `:0.1.18`)
- `:<major>.<minor>` — latest patch on a minor line (e.g. `:0.1`)

## MCP server

SeeFlow ships an MCP server so any MCP-aware editor can list, register, and edit demos directly. The studio must be running first.

**Claude Code:**

```bash
claude mcp add seeflow -- npx -y --package=@tuongaz/seeflow@latest seeflow-mcp
```

**Via `.mcp.json`** (Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "seeflow": {
      "command": "npx",
      "args": ["-y", "--package=@tuongaz/seeflow@latest", "seeflow-mcp"]
    }
  }
}
```

The MCP server talks to `http://127.0.0.1:4321/mcp` by default. Override with `SEEFLOW_STUDIO_URL` if needed.

## Develop

```bash
git clone https://github.com/tuongaz/seeflow.git
cd seeflow && bun install
make dev   # Vite (5173) + Hono studio (4321), both hot-reloading
```

`make help` lists every target. Toolchain: Bun ≥ 1.3, Hono, React Flow, Zod, Biome.

## Status

Early-stage. The schema is stable enough to author against, but expect changes. Issues, ideas, and PRs welcome.

## License

MIT — see [`LICENSE`](./LICENSE).
