Workflow - Human-AI Workflow Orchestration Platform

AI agents and human operators collaborate on complex workflows. AI handles routine tasks autonomously, escalating to humans when confidence is low. Full audit trail on every action.

Local Demo (5 minutes)

Prerequisites

• Java 21 (brew install openjdk@21)
• Docker (for PostgreSQL)
• Ollama (optional, for AI agent features): brew install ollama
• Node.js 20+ (for frontend)

1. Start PostgreSQL

docker compose up -d db

2. Generate secrets and start the backend

cd backend

# Generate a JWT secret (one-time)
export WORKFLOW_JWT_SECRET=$(openssl rand -base64 64 | tr -d '\n')
export WORKFLOW_DB_PASSWORD=workflow

# Start (auto-seeds demo data on first run)
./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

The backend starts on http://localhost:8000. On first run with the dev profile, it automatically creates demo users and two sample workflows.

3. Start the frontend

cd frontend
npm install
npm run dev

Dashboard at http://localhost:5173.

4. (Optional) Start Ollama for AI agent processing

ollama pull llama3.2
ollama serve

Without Ollama running, you can still use the full UI, create workflows, assign tasks, and work through the human review flow. AI agent tasks will fail gracefully and escalate to human review.

Demo Accounts

Email	Password	Role
admin@workflow.dev	admin123	Admin
manager@workflow.dev	manager123	Manager
operator1@workflow.dev	operator123	Operator
operator2@workflow.dev	operator123	Operator

Try It

1. Log in as admin@workflow.dev
2. Go to Workflows, find "Document Review Pipeline"
3. Click Run, provide some context (any JSON, e.g. {"document": "loan_app.pdf"})
4. Watch the AI agent pick up the task (if Ollama is running) or see it in the task queue
5. Log in as operator1@workflow.dev to see the task inbox
6. Review the AI's reasoning, approve or correct its work
7. Check the Audit page to see the full trail

Architecture

React Dashboard --> Spring Boot API --> PostgreSQL
                        |
                   Spring AI Agent
                   (Ollama / Anthropic / OpenAI)

Component	Technology	Purpose
Backend	Java 21, Spring Boot 3.4, Spring AI 1.0	REST API, workflow engine, auth
AI Agents	Spring AI + ChatClient	Task analysis, document processing, HITL
Database	PostgreSQL 16, Flyway	System of record, append-only audit log
Auth	Spring Security, JWT, BCrypt-12	Authentication, rate limiting
Frontend	React 18, Vite, Tailwind	Dashboard, task inbox, workflow management
Documents	Apache PDFBox, Tesseract	PDF extraction, OCR

Commands

# Build (compile + tests)
cd backend && ./mvnw clean install

# Run tests only
cd backend && ./mvnw test

# Run locally
cd backend && WORKFLOW_JWT_SECRET=<secret> ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev

# Full stack via Docker
WORKFLOW_DB_PASSWORD=<secret> WORKFLOW_JWT_SECRET=<secret> docker compose up

API Endpoints

Method	Path	Description
POST	/api/auth/login	Login, returns JWT
POST	/api/auth/register	Register new user
GET	/api/auth/me	Current user info
GET	/api/workflows	List workflow definitions
POST	/api/workflows	Create workflow
POST	/api/workflows/{id}/run	Start a workflow run
GET	/api/workflows/runs	List all runs
GET	/api/tasks/inbox	Your assigned tasks
GET	/api/tasks/queue	Unassigned tasks
POST	/api/tasks/{id}/complete	Complete a task
POST	/api/tasks/{id}/escalate	Escalate to human
POST	/api/tasks/{id}/feedback	Approve/reject/correct
GET	/api/analytics/dashboard	Real-time metrics
GET	/api/audit	Query audit log
GET	/actuator/health	Health check
GET	/actuator/prometheus	Metrics export

Project Structure

workflow/
├── backend/                    # Java 21 + Spring Boot
│   ├── src/main/java/com/workflow/
│   │   ├── config/            # Security, AI, CORS, data seeder
│   │   ├── security/          # JWT, rate limiting, auth filter
│   │   ├── domain/            # Entities, repositories, business logic
│   │   │   ├── workflow/      # DAG engine, conditional branching
│   │   │   ├── task/          # State machine, skill-based routing
│   │   │   ├── audit/         # Append-only audit log
│   │   │   └── document/      # Document storage
│   │   ├── agent/             # Spring AI task agent, worker
│   │   └── api/               # REST controllers, DTOs, error handling
│   └── src/test/              # 36 tests (domain, security, agent)
├── frontend/                   # React 18 + Vite + Tailwind
│   └── src/pages/             # Dashboard, Inbox, Tasks, Workflows, Audit
├── docker-compose.yml
└── CLAUDE.md                   # Development conventions