Documentation
Complete technical documentation for the HFD Workflow Visualizer. Learn about system architecture, API usage, deployment, and more.
Overview
The HFD Workflow Visualizer is an AI-powered tool designed to transform Honolulu Fire Department policy documents into interactive, structured workflow diagrams. The system uses advanced language models to identify workflows, analyze procedural steps, and generate Mermaid diagrams that visualize complex operational procedures.
- Automatic workflow detection from PDF documents
- AI-powered analysis with multiple model providers (Anthropic, OpenAI, Google)
- Real-time PII scanning and protection
- Interactive Mermaid diagram generation
- User attestation and audit logging
- Secure Firebase authentication
Architecture
The application is built using Next.js 16 with the App Router, React 19, and integrates with multiple AI providers through a unified interface. The architecture follows a three-stage pipeline for document processing.
System Components
Frontend
- Next.js 16 (App Router)
- React 19
- Tailwind CSS
- Radix UI Components
- Mermaid.js for diagrams
Backend & Storage
- Next.js Server Actions
- Firebase Firestore
- Firebase Authentication
- Upstash Redis (caching)
AI Pipeline
- Anthropic Claude
- OpenAI GPT-4
- Google Gemini
- Vercel AI SDK
Security
- PII Detection
- Firebase Auth
- Session Management
- Audit Logging
Data Flow
The system processes documents through a three-stage pipeline:
- Stage 1: Detection & Classification - Scans uploaded PDFs for PII and identifies potential workflow sections
- Stage 2: Analysis - Performs deep analysis of identified workflows, extracting actors, complexity, steps, and decision points
- Stage 3: Diagram Generation - Generates Mermaid diagram code with auto-validation and retry logic
Getting Started
Prerequisites
Before installing, ensure you have the following:
- Node.js 20.x or higher
- npm or pnpm package manager
- Firebase project with Firestore and Authentication enabled
- API keys for at least one AI provider (Anthropic, OpenAI, or Google)
Installation
# Clone the repository
git clone <repository-url>
cd diagram-generator
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.localConfiguration
Configure your environment variables in .env.local:
# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
FIREBASE_ADMIN_PRIVATE_KEY=your_private_key
# AI Provider Keys (at least one required)
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GOOGLE_AI_API_KEY=your_google_key
# Redis Cache (optional but recommended)
UPSTASH_REDIS_REST_URL=your_redis_url
UPSTASH_REDIS_REST_TOKEN=your_redis_token.env.local to version control. Keep all API keys and credentials secure and rotate them regularly.API Reference
The application exposes server actions for document processing. All actions are authenticated and require a valid Firebase session.
Upload & Scan
1 import { uploadAndScanPDF } from '@/app/actions'; 2
3 const formData = new FormData(); 4 formData.append('file', pdfFile); 5 formData.append('sessionId', sessionId); 6
7 const result = await uploadAndScanPDF(formData); 8
9 if (result.success) { 10 console.log('Document text:', result.text); 11 console.log('PII findings:', result.piiFindings); 12 } else if (result.piiBlocked) { 13 console.log('PII detected, requires override'); 14 }
Workflow Identification
1 import { identifyWorkflowsFromText } from '@/app/actions'; 2
3 const result = await identifyWorkflowsFromText( 4 documentText, 5 fileName, 6 fileSize, 7 sessionId, 8 'anthropic', // model provider 9 'JD', // user initials 10 piiScanData, 11 attestationData, 12 false, // override PII 13 0, // retry count 14 'blue' // prompt version 15 ); 16
17 if (result.success && result.workflows) { 18 result.workflows.forEach(workflow => { 19 console.log('Title:', workflow.title); 20 console.log('Location:', workflow.location); 21 console.log('Summary:', workflow.summary); 22 }); 23 }
Diagram Generation
1 import { generateDiagramForWorkflow } from '@/app/actions'; 2
3 const input = { 4 workflowTitle: 'Emergency Response Protocol', 5 pageRange: 'Pages 1-3', 6 relevantPdfTextSection: extractedText, 7 workflowId: 'WF-12345', 8 uploadId: uploadId, 9 // Optional enriched data from Stage 2 10 complexity: 'medium', 11 actors: ['Dispatcher', 'Captain', 'Firefighter'], 12 structuredSteps: [...], 13 decisionPoints: [...], 14 }; 15
16 const result = await generateDiagramForWorkflow( 17 input, 18 'anthropic', 19 { sessionId, promptVersion: 'blue' } 20 ); 21
22 if (result.mermaidCode && result.details) { 23 console.log('Diagram code:', result.mermaidCode); 24 console.log('Workflow details:', result.details); 25 }
Security & Privacy
PII Detection
The system implements comprehensive PII detection using pattern matching and validation rules:
- Names (with confidence scoring)
- Email addresses
- Phone numbers (multiple formats)
- Social Security Numbers
- Physical addresses
- Credit card numbers
When PII is detected, the system blocks processing and requires supervisor override with additional attestation before proceeding.
Authentication
Firebase Authentication handles all user sessions with support for Google OAuth and email/password authentication. Session tokens are refreshed automatically and stored as secure HTTP-only cookies.
// Client-side authentication monitoring
useEffect(() => {
const unsubscribe = onAuthStateChanged(auth, async (user) => {
if (user) {
const token = await user.getIdToken(true);
await setAuthCookie(token);
} else {
await clearAuthCookie();
}
});
return () => unsubscribe();
}, []);Deployment
Build Process
The application is optimized for production deployment with the following commands:
# Run type checking
npm run typecheck
# Run tests
npm run test
# Build for production
npm run build
# Start production server
npm startEnvironment Variables
Required environment variables for production deployment:
| Variable | Required | Description |
|---|---|---|
| NEXT_PUBLIC_FIREBASE_* | Yes | Firebase configuration |
| ANTHROPIC_API_KEY | Optional | Anthropic Claude API access |
| OPENAI_API_KEY | Optional | OpenAI GPT-4 API access |
| GOOGLE_AI_API_KEY | Optional | Google Gemini API access |
| UPSTASH_REDIS_* | Recommended | Redis caching configuration |
apphosting.yaml for deployment configuration.Need Help?
Check out the User Guide for step-by-step instructions, or reach out to the development team via the Slack channel.