DesysFlow OSS is a local-first, agentic system design platform that converts your codebase and product goals into versioned architecture artifacts. It provides a CLI for fast iteration, a local API backend, and a lightweight UI for guided design and refinement.

It includes:

• A simple CLI (desysflow) for local generation and refinement
• A local FastAPI backend
• A lightweight React UI for prompting and artifact inspection

• Local-first workflow with repo-native outputs
• Versioned design artifacts (v1, v2, ...)
• Structured outputs (HLD, LLD, technical report, non-technical brief, diagrams, diffs)
• Provider-flexible LLM support (ollama, openai, anthropic, groq)
• Optional secret-leak guardrail on LLM output
• Configurable via desysflow.config.yml (roles, languages, providers, defaults)

• Python 3.11+
• uv
• Node.js + npm

curl -fsSL https://raw.githubusercontent.com/kmeanskaran/desysflow-oss/main/scripts/install.sh | bash
source ~/.bashrc    # or: source ~/.zshrc
letsvibedesign

The installer is intended for macOS, Linux, and WSL2. It clones the repo into ~/.letsvibedesign/desysflow-oss, bootstraps the local environment, and installs a global letsvibedesign launcher into ~/.local/bin.

LETSVIBEDESIGN_LOCAL_REPO="$PWD" LETSVIBEDESIGN_OFFLINE=1 ./scripts/install.sh
source ~/.bashrc    # or: source ~/.zshrc
letsvibedesign

uv sync
uv run desysflow --help

Equivalent module form:

python -m desysflow_cli --help

pip install -e .
desysflow --help

• letsvibedesign: convenience launcher that bootstraps the repo, then opens the interactive CLI loop
• letsvibedesign studio: convenience launcher that starts the API and UI together
• desysflow: the actual CLI console script defined in pyproject.toml
• python -m desysflow_cli: module-based equivalent of desysflow

letsvibedesign
letsvibedesign studio
uv run desysflow design --source .
python -m desysflow_cli design --source .

Run the basic guided CLI:

letsvibedesign

letsvibedesign stays open after each generation and shows a letsdesign> prompt.

Interactive prompt commands:

• Enter or run: run again with the current saved stack
• design: asks for a prompt, then continues with the current saved stack
• design <prompt>: run directly with that prompt
• restart: clear saved selections and start from scratch
• Any plain text: treated as a prompt and runs design
• bye: exit the CLI loop

Check the available commands:

desysflow --help
desysflow design --help
desysflow redesign --help

Run from this repo without installing a global command:

uv run desysflow design --source .
python -m desysflow_cli design --source .

Run directly with flags:

desysflow design --source . --out ./desysflow --project my-project
desysflow redesign --source . --out ./desysflow --project my-project --focus "improve scaling"

Run without prompts:

desysflow design \
  --source . \
  --out ./desysflow \
  --project my-project \
  --model-provider ollama \
  --model gpt-oss:20b-cloud \
  --language python \
  --cloud local \
  --style balanced \
  --no-interactive

Interactive defaults:

• Empty repositories immediately ask what you want to design.
• Non-empty repositories detect the dominant codebase language and use it as the default language selection.
• Non-empty repositories let you add an optional prompt, or press Enter to continue vibe designing from the current codebase or latest baseline.
• Generated artifacts and local session data are stored in ./desysflow by default.

Start API + UI together:

letsvibedesign studio

Open:

• UI: http://localhost:5173
• API docs: http://localhost:8000/docs

In the UI:

• Open model settings from the gear icon.
• Choose ollama, openai, anthropic, or groq.
• Enter the model name and API key when needed.
• Click Check status.
• Enter a design prompt, then use follow-up prompts to refine the result.

• CLI:
  • interactive: desysflow design then follow prompts for provider/model/API key
  • non-interactive: desysflow design --model-provider <provider> --model <name> [--api-key <key>]
• UI:
  • open model settings (gear icon), choose provider/model, add API key for OpenAI/Anthropic/Groq
  • click Check status to run live connectivity/auth validation

Provider checks:

• OpenAI/Anthropic/Groq: verifies API key + endpoint reachability (/models probe)
• Ollama: verifies local endpoint reachability and that selected local model exists (/api/tags)

Primary LangGraph pipeline (graph/workflow.py):

1. extract_requirements
2. select_template
3. generate_architecture
4. inject_edge_cases
5. critic_agent
6. revision_agent
7. diagram_generator
8. diagram_quality_agent
9. report_generator
10. cloud_infra_agent

API also exposes additional loops on top of this base flow:

• async operation progress (/design/async, /design/followup/async)
• cloud redesign (/design/cloud-redesign: provider-specific diagram/report regeneration)

See Agentic Architecture for more detail.

DesysFlow writes versioned artifacts to ./desysflow/<project>/vN/ by default, including:

• HLD.md
• LLD.md
• TECHNICAL_REPORT.md
• NON_TECHNICAL_DOC.md
• diagram.mmd
• SUMMARY.md
• CHANGELOG.md
• DIFF.md
• METADATA.json

Edit desysflow.config.yml to customize roles, languages, cloud targets, providers, and defaults. The CLI and UI both read this file at startup.

For local Ollama runs, OLLAMA_NUM_PREDICT controls the maximum generated tokens. Lower it if generation looks slow on small local models.

Set LLM_GUARDRAIL=true in .env.example to enable secret-leak detection on LLM output. The guardrail scans for API keys, tokens, database connection strings, and other credential patterns.

• Getting Started
• CLI Guide
• Architecture
• Agentic Architecture
• Examples
• Project Overview

See CONTRIBUTING.md.

• X: @kmeanskaran
• Website: kmeanskaran.com

See CODE_OF_CONDUCT.md.

This project is licensed under the MIT License. See LICENSE.