📦 EqualifyEverything / equalify-reflow

equalify-reflow / clients / viewer / README.md
📄 README.md · 319 lines 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319# Equalify Reflow - Demo UI

**⚠️ IMPORTANT: This is a DEMO/DEVELOPER TOOL only, NOT the production interface.**

## Overview

Browser-based demo interface for testing the Equalify Reflow REST API and demonstrating document processing workflows to stakeholders. The production interface will use Canvas LMS integration.

**Purpose:**
- Developer testing during implementation
- Stakeholder presentations and demos
- QA validation of API functionality
- Visual debugging of document processing pipeline

## Tech Stack

- **Framework**: Vite 6.3 + React 18.3 + TypeScript 5.9
- **Package Manager**: pnpm 9.0+ (latest versions installed)
- **UI Components**: ShadCN UI (Radix + Tailwind CSS)
- **State Management**: React Query 5.90 + Zustand 5.0
- **Charts**: Recharts 2.15
- **Icons**: Lucide React 0.462
- **Styling**: Tailwind CSS 3.4 with UIC branding

## Quick Start

### Prerequisites

- Docker and Docker Compose installed
- Backend API running (`make dev` in project root)

### Option 1: Docker (Recommended)

```bash
# From project root, start all services including demo UI
make dev

# The demo UI will be available at:
# http://localhost:5173

# API runs at:
# http://localhost:8080
```

The frontend runs in a Docker container with hot-reload enabled. Edit files in `frontend/demo-ui/src/` and changes will appear automatically in the browser.

### Option 2: Local Development (Without Docker)

```bash
cd frontend/demo-ui

# Install pnpm if not installed
npm install -g pnpm

# Install dependencies (latest versions)
pnpm install

# Create .env file
cp .env.example .env

# Start dev server
pnpm run dev

# Open browser
open http://localhost:5173
```

## Features

### 1. Document Upload & Tracking
- Drag-and-drop PDF upload interface
- Real-time job status updates (polling every 2 seconds)
- Job list with status badges
- Job detail view with comprehensive information

### 2. PII Review Workflow
- Token-based approval URLs
- Visual display of PII findings with confidence scores
- Approve/deny decision form with justification
- High-confidence PII highlighted in red

### 3. System Monitoring Dashboard
- System health indicators (API, Redis, S3)
- Worker status display (PII, Processing, Timeout workers)
- Queue depth visualization (if dev endpoints enabled)
- Real-time metrics updates

### 4. UIC Branding
- Navy (#001e62) and red (#d50032) color scheme
- "DEMO ONLY" badge prominently displayed
- Accessible UI components (WCAG 2.1 AA)
- Mobile-responsive design

## Project Structure

```
frontend/demo-ui/
├── src/
│   ├── components/
│   │   ├── ui/                # ShadCN primitives (Button, Card, etc.)
│   │   ├── layout/            # Header, Sidebar, DashboardLayout
│   │   ├── document/          # Upload, JobList, JobCard, JobDetail
│   │   └── monitoring/        # SystemHealth, QueueMonitor, WorkerStatus
│   │
│   ├── pages/
│   │   ├── Dashboard.tsx      # Main page (upload + job list)
│   │   ├── JobDetailPage.tsx  # Single job view
│   │   ├── ApprovalReviewPage.tsx  # PII review interface
│   │   └── MonitoringPage.tsx # System monitoring dashboard
│   │
│   ├── hooks/
│   │   ├── useJob.ts          # Job status polling
│   │   ├── useSystemHealth.ts # Health check polling
│   │   └── useQueueMetrics.ts # Queue depth polling
│   │
│   ├── lib/
│   │   ├── api.ts             # Typed API client
│   │   ├── utils.ts           # Helper functions
│   │   └── queryClient.ts     # React Query configuration
│   │
│   └── types/
│       └── api.ts             # TypeScript API types
│
├── Dockerfile.dev             # Docker configuration
├── vite.config.ts             # Vite configuration
├── tailwind.config.js         # UIC branding colors
└── package.json               # Dependencies
```

## API Endpoints Used

**Document Management:**
- `POST /api/documents/submit` - Upload PDF
- `GET /api/documents/{job_id}` - Get job status
- `GET /api/documents/{job_id}/result` - Get processing results

**Approval Workflow:**
- `GET /api/approval/{token}/review` - Get PII review data
- `POST /api/approval/{token}/decision` - Submit approval decision

**System Health:**
- `GET /health` - System health check

**Dev Monitoring (Optional):**
- `GET /api/dev/monitoring/queues` - Queue depth metrics (dev-only)

## Demo Script (For Stakeholders)

### Scenario 1: Clean Document (No PII)

1. **Upload Document**
   - Navigate to Dashboard
   - Click "Upload PDF" and select a clean document
   - Watch status change: `pending` → `pii_scanning` → `processing` → `completed`

2. **View Results**
   - Click on job card to view details
   - Click "View Results" to see processed output

### Scenario 2: Document with PII

1. **Upload Document with PII**
   - Upload a document containing names, emails, or SSNs
   - Status changes to `awaiting_approval`
   - Note the PII detection message

2. **Review PII**
   - Copy approval URL from API response (or check logs)
   - Open URL in new tab
   - Review detected PII entities with confidence scores
   - High-risk PII (>80% confidence) highlighted in red

3. **Approve/Deny**
   - Select "Approve" or "Deny"
   - Enter reviewer name
   - Add justification (10-1000 characters)
   - Submit decision
   - Watch job status update

### Scenario 3: System Monitoring

1. **View Health Dashboard**
   - Navigate to "Monitoring" page
   - Verify all systems show green (API, Redis, S3)
   - Check worker status (all should show "Running")

2. **Monitor Queue Activity**
   - Upload multiple documents
   - Watch queue depths increase in bar chart
   - Observe real-time updates every 2 seconds

## Development

### Hot Reload

The Docker setup includes hot-reload for rapid development:

```bash
# Edit any file in frontend/demo-ui/src/
# Browser automatically refreshes

# If changes don't appear, try:
docker-compose restart demo-ui
```

### Building for Production

```bash
pnpm run build

# Output in dist/ directory
# Can be served with any static host
```

### TypeScript Type Checking

```bash
pnpm run build  # Runs tsc before build
```

## Environment Variables

Create `.env` file (see `.env.example`):

```bash
# API Configuration
VITE_API_URL=http://localhost:8080

# Optional: Grafana URL (if PRD-009A complete)
VITE_GRAFANA_URL=http://localhost:3001
```

**Important:** In Docker, `VITE_API_URL` must be `http://localhost:8080` because the browser (not the container) makes API requests.

## Accessibility

- WCAG 2.1 AA compliant components (Radix UI)
- Keyboard navigation supported
- Screen reader compatible
- Color contrast validated
- Focus indicators visible

## Mobile Responsive

Tested on:
- Desktop (1920x1080+)
- Tablet (768x1024)
- Phone (375x667)

All layouts adapt gracefully.

## Troubleshooting

### Frontend not loading

```bash
# Check if container is running
docker ps | grep demo-ui

# View logs
docker logs equalify-pdf-demo-ui

# Restart container
docker-compose restart demo-ui
```

### API requests failing

```bash
# Verify API is running
curl http://localhost:8080/health

# Check CORS configuration
# Should allow localhost:5173 origin
```

### Hot reload not working

```bash
# Verify volume mounts
docker inspect equalify-pdf-demo-ui

# Should see mounts for src/, public/, etc.
```

## Known Limitations

1. **Queue Monitoring**: Requires optional dev endpoints (PRD-009B)
2. **Grafana Embedding**: Requires PRD-009A implementation
3. **Job Persistence**: Jobs not persisted between API restarts
4. **Authentication**: None (dev-only tool)

## Future Enhancements

- [ ] Grafana dashboard embedding (PRD-009A)
- [ ] Job history persistence
- [ ] Document preview before upload
- [ ] Export job list to CSV
- [ ] Dark mode toggle

## Support

This is a demo tool for internal use. For issues:

1. Check Docker logs: `make logs`
2. Verify backend API is healthy: `curl http://localhost:8080/health`
3. Review browser console for errors
4. Check network tab for failed requests

## Related Documentation

- [PRD-009B](../../ai-docs/PRDs/phase-3-integration/PRD-009B-demo-rest-ui.md) - Demo UI requirements
- [PRD-004](../../ai-docs/PRDs/phase-2-services/PRD-004-api-endpoints.md) - API endpoints
- [PRD-006](../../ai-docs/PRDs/phase-2-services/PRD-006-approval-api.md) - Approval workflow

---

**Remember: This is a DEMO ONLY interface for testing and presentations. Production will use Canvas LMS integration.**