# Building With Viewflow

> Use when building a Django app with the Viewflow library — workflows (BPMN), CRUD viewsets, FSM state transitions, jsonstore process data, or Viewflow forms. Loads Viewflow conventions and the full docs.

- Skill: `viewflow/building-with-viewflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add viewflow/building-with-viewflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/viewflow/building-with-viewflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: viewflow (https://skillmd.com/u/viewflow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/viewflow/building-with-viewflow

---


# Building with Viewflow

Viewflow is a low-code library for Django. It adds workflows (BPMN), CRUD,
forms, and reporting on top of normal Django models and views.

## How to use this skill

1. Fetch `https://docs.viewflow.io/llms-full.txt` — the whole documentation in
   one file. Search it before guessing an API. It is the source of truth.
2. For a quick orientation, fetch `https://docs.viewflow.io/AGENTS.md`.
3. Follow the conventions below.

## Conventions

- Install: `pip install django-viewflow`. Add `"viewflow"` (and
  `"viewflow.workflow"` for workflows) to `INSTALLED_APPS`.
- Workflows are `flow.Flow` subclasses; wire nodes with `this.<name>`. Store
  process data in `viewflow.jsonstore` fields on a proxy `Process` model — no
  per-field migrations.
- Mount with `Site`/`Application` viewsets, not hand-written URL patterns.
- For state transitions without the workflow engine, use `viewflow.fsm.State`
  and `@state.transition(source=..., target=...)`. The target state is set
  before the method body runs and rolls back on exception.
- A transition permission is a query, not a gate: the method runs regardless.
  Check `flow.<transition>.has_perm(user)` in the view and raise
  `PermissionDenied`.
- Workflow permissions are `view_<model>` and `manage_<model>`; canceling a
  process needs `manage`.
- Don't edit `viewflow/` in the open-source repo — it is generated.

## Examples

See `https://docs.viewflow.io/AGENTS.md` for minimal flow, URL, and FSM
examples, and https://github.com/viewflow/cookbook for full sample projects.