# Flowmaster Frontend

> FlowMaster frontend components and UI patterns for process automation

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

---


# FlowMaster Frontend Skill

---

## ⛔ CRITICAL UI DESIGN RULES — READ BEFORE WRITING ANY CODE

These are absolute constraints. No exceptions without explicit user request.

| Rule | Enforcement |
|---|---|
| **NO dashboards** | Do not build KPI card grids, metric panels, or summary widget layouts |
| **NO meaningless colors** | Only use semantic tokens: success=green, warning=amber, danger=red, brand=primary. No decorative palette (no purple, teal, indigo, etc.) |
| **NO theme deviation** | Use theme CSS variables only. No hardcoded hex, no ad-hoc Tailwind color classes that aren't in the token system |
| **NO icons unless requested** | Do not add icons. If not explicitly asked for, use text. Existing icons may stay |

### v3 Design Token Reference (Blue theme — default)
```
--brand: #0F3460       → primary actions, active nav
--success: #10b981     → pass, active, healthy
--warning: #f59e0b     → warn, pending, degraded
--danger: #dc2626      → fail, error, critical
--text: #0f172a        → primary text
--text-secondary: #475569
--text-muted: #94a3b8
--border: #cbd5e1
--bg-subtle: #f1f5f9
--sidebar-bg: #f0f4f8
```

### v3 Spacing & Scale Reference
```
font-size: 12px base, line-height: 1.4
--topbar-h: 34px   --sidebar-w: 210px
Toolbar buttons: h-22px, icons 13×13
Nav items: 11px text, 14×14 icons, 4px 8px 4px 14px padding
No box-shadow (except nodes/dropdowns)
Border-radius: 2-5px max
```

---

## Overview
FlowMaster frontend comprises three independent applications serving different user roles in a process automation platform:
1. **Frontend Admin** - Admin dashboard for process/service management
2. **Engage App** - Employee-facing task execution interface with AI assistance
3. **DXG Frontend** - Development/testing UI for DXG (Data eXperience Generator)

Plus two supporting tools: SDX Frontend (data mapping) and planned Manager App (escalation handling).

## 1. Frontend Admin (flowmaster-frontend-nextjs)

### Stack & Architecture
- **Framework**: Next.js 14+ (React/TypeScript) with 236 TS/TSX files
- **UI Library**: Radix UI components (shadcn/ui), TailwindCSS for styling
- **Forms**: React Hook Form + Zod validation for type-safe inputs
- **Architecture**: Feature-based organization (process design, execution, task management)

### Core Components
- **Admin Dashboard**: Overview of system health, active processes, user activity
- **Process Management UI**:
  - Process Explorer: Browse and view all defined processes
  - Process Designer: Visual workflow builder with drag-drop support
  - Process configuration and version control
- **User Management**: Create, edit, remove users and manage roles
- **Service Monitoring**: View status and metrics for backend services
- **Authentication Flow Integration**: Handle login, session management, token refresh

### API Connections
- **API Gateway**: REST endpoints at port 9000 for process/service data
- **WebSocket Gateway**: Real-time updates for process execution status and system events

### Known Gaps (per baseline)
- R08: Field mapping confirmation UI (SDX integration)
- R17: Affiliated Organizations management
- D12: Process Designer integration completeness

---

## 2. Engage App (flowmaster-engage)

### Stack & Architecture
- **Framework**: Next.js 16 (React 19/TypeScript) with 242 TS/TSX files
- **Purpose**: Employee-facing app for executing workflow process steps with AI-powered task intelligence
- **Design Pattern**: Progressive disclosure - show only what's needed at each step

### Key Routes & Screens

#### `/tasks` - Task Queue Dashboard
- Displays all assigned tasks in filterable table
- Filters: Status, Priority, Due Date
- Status badges: Not Started, In Progress, Pending Review, Completed
- Quick navigation to individual task detail pages

#### `/tasks/[id]` - Task Detail & Execution
**Left Panel (Task Briefing)**:
- `ContextBriefingPanel`: AI-generated case summary with key facts
- `SmartReviewForm`: DXG-generated pre-filled HTML form for task data input
  - Auto-filled with AI suggestions (shows confidence levels)
  - Employee can modify/override values
  - Field-level provenance (shows where data came from)

**Right Sidebar**:
- `InteractiveQueryChat`: Ask AI questions about task context
  - Example: "What was the customer's previous order?"
  - "When is the deadline for escalation?"

**Footer Actions**:
- Save Draft (persist partial completion)
- Approve & Submit (advance process to next step)
- Reject (return to sender with reason)

#### `/dashboard` - Overview Dashboard
- Cards showing task metrics (open, pending review, completed today)
- Recent activity stream
- Quick stats on process adherence

#### `/history` - Task History
- Completed tasks with execution timeline
- View submitted forms and approval chain
- Audit trail of changes

#### `/agents` - AI Agent Management
- View active AI agents assisting with task execution
- Agent performance metrics
- Configure AI behavior preferences

### DXG Integration (Next.js API Proxy)
Engage proxies requests to DXG backend via `/api/dxg/*` endpoints:

```
GET  /api/dxg/analyze/{taskId}
     → DXG unified analysis: domain context, case summary, key metrics, risk flags

GET  /api/dxg/smart-form/{taskId}
     → DXG form generation: pre-filled HTML form based on task data + LLM

POST /api/dxg/query/{taskId}
     → DXG interactive Q&A: employee asks questions, AI responds with context-aware answers
```

### Task Execution Flow
1. Employee opens `/tasks` → fetch assigned tasks from Human Task Service (REST)
2. Click task card → navigate to `/tasks/{id}`
3. Parallel DXG calls: `analyzeTask()` + `getSmartForm()`
4. Display briefing panel + smart form + enable chat sidebar
5. Employee reviews pre-filled form and modifies as needed
6. Click "Approve & Submit" → `POST /api/tasks/{taskId}/complete`
7. Execution Engine advances process to next step

### Design Patterns
- **Pre-filled Forms**: AI suggests values, employee confirms/overrides
- **Contextual Briefing**: Show relevant case info before form
- **Inline Help**: Chat sidebar for Q&A without leaving task
- **Data Provenance**: Display where each form value came from
- **Draft Saving**: Allow incomplete submissions for later resumption

### Known Gaps (per baseline)
- R25: Full case data loading completeness
- R26: Complete AI Q&A functionality
- R27: Preemptive contextual info (showing task context without asking)
- R28-R29: Design-time analytics (track form accuracy, task completion times)

---

## 3. DXG Frontend (dxg)

### Stack & Architecture
- **Framework**: React + Vite + TypeScript (development/testing UI)
- **Purpose**: NOT end-user facing; used by developers/designers to build and test DXG experiences

### Panels & Layout
- **Left Panel**: Prompt editor, configuration settings, saved designs library
- **Center Panel**: Real-time HTML preview of generated UI
- **Right Panel**: Data structure inspector, LLM API traffic viewer, error logs
- **UIRenderer Component**: Sandboxed HTML preview with style isolation

### Workflow
1. Developer writes natural language prompt: "Create a customer complaint form with escalation path"
2. Click "Generate" → calls DXG backend `/api/v1/generate`
3. Backend returns HTML + metadata
4. Vite preview renders HTML with sandboxing
5. Developer inspects generated form structure, field types, validation rules
6. Refine prompt → iterate until satisfied
7. Export/save design → used by Engage app

### Backend Endpoints (consumed by both DXG Frontend & Engage)
```
POST /api/v1/generate
    Input: { prompt, context, rules }
    Output: { html, fields, metadata, validationRules }

GET  /api/v1/analyze/{task_id}
    Output: { domain, caseSummary, keyMetrics, riskFlags }

GET  /api/v1/smart-form/{task_id}
    Output: { html, fieldValues, confidence, provenance }

POST /api/v1/query/{task_id}
    Input: { question }
    Output: { answer, sources, confidence }

GET  /api/v1/briefing/{task_id}
    Output: { summary, timeline, activeAlerts }
```

---

## 4. SDX Frontend (sdx-frontend)

### Stack & Architecture
- **Framework**: React
- **Purpose**: Data source registration and semantic field mapping UI

### Screens
- Data source explorer
- Field mapping workflow (map source fields to domain entities)
- Semantic type assignment (mark fields as Customer ID, Order Date, etc.)
- Visual data lineage diagrams

### Integration Gap (R08)
- Needs to integrate into Process Designer field mapping workflow
- Currently standalone; should be embedded in process design step

---

## 5. Manager App (PLANNED - R30-R33)

### Stack & Architecture
- **Framework**: React (mobile-optimized; can share codebase with Engage)
- **Purpose**: Manager-only interface for escalation handling ONLY
  - NOT for case approval (that's Engage employees)
  - ONLY for agent blockage resolution and guidance

### Planned Screens
- Escalation queue (tasks escalated by AI agents)
- Blockage resolution (provide context to help agent proceed)
- Guidance provision (share internal policies, precedents)
- Escalation metrics dashboard

---

## Integration Architecture

```
┌─────────────────────────────────────────────────┐
│         Frontend Admin (Next.js)                │
│  - Process Designer, User Management, Monitoring │
└──────────────┬──────────────────────────────────┘
               │ REST
               ▼
        ┌──────────────┐
        │ API Gateway  │ (:9000)
        └──────────────┘
               │
    ┌──────────┼──────────┐
    │          │          │
    ▼          ▼          ▼
[Services] [Auth] [WebSocket]

┌──────────────────────────────────┐
│     Engage App (Next.js 16)      │
│ - Task queue, execution, AI help │
└────────────┬─────────────────────┘
             │ Next.js API Routes
             ▼
        ┌────────────┐
        │ DXG Service│ (:8005)
        │ + Human    │
        │ Task Srv   │
        └────────────┘

┌──────────────────────────────────┐
│  DXG Frontend (React + Vite)     │
│  - UI design, testing, iteration │
└────────────┬─────────────────────┘
             │ REST
             ▼
        ┌────────────┐
        │ DXG Backend│ (:8005)
        │ (FastAPI)  │
        └────────────┘

┌──────────────────────────────────┐
│  SDX Frontend (React)            │
│  - Data mapping, field lineage   │
└────────────┬─────────────────────┘
             │ REST
             ▼
        ┌────────────┐
        │ SDX API    │
        └────────────┘
```

---

## Design System & Patterns

### Form Interaction Patterns
- **Progressive Disclosure**: Show complex fields only when relevant
- **Validation Feedback**: Real-time field validation with clear error messages
- **Auto-fill with Override**: AI suggests, human confirms/changes
- **Field Provenance**: Display source of pre-filled values (e.g., "From customer CRM", "AI prediction 87%")

### Navigation Patterns
- **Breadcrumb Trail**: Show path in process (e.g., Task > Approval > Handoff)
- **Sidebar Menu**: Quick access to main app sections
- **Tab Navigation**: Organize related content (Details, History, Related Tasks)

### Data Display
- **Color-Coded Status**: Pending (yellow), Active (blue), Completed (green), Blocked (red)
- **User Avatars**: Show assignee/reviewer with hover card details
- **Timeline Views**: Show task progression and handoff points
- **Empty States**: Helpful message and CTA when no tasks/data

### Real-time Features
- WebSocket updates for task status changes
- Live notifications for new task assignments
- Collaborative awareness (see who's viewing same task)

---

## When to Use This Skill

Use this skill when you need to:
- Build or modify employee task execution interfaces (Engage App)
- Design AI-assisted form pre-filling experiences (DXG integration)
- Develop admin dashboards for process monitoring and management
- Implement real-time task queue updates via WebSocket
- Create data mapping workflows for semantic field configuration (SDX)
- Debug DXG HTML generation or form pre-fill issues
- Extend task execution with new AI analysis features
- Build manager escalation handling interfaces
- Implement progressive disclosure and contextual UI patterns
- Design mobile-friendly employee task interfaces