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.

Key Features
  • 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:

  1. Stage 1: Detection & Classification - Scans uploaded PDFs for PII and identifies potential workflow sections
  2. Stage 2: Analysis - Performs deep analysis of identified workflows, extracting actors, complexity, steps, and decision points
  3. Stage 3: Diagram Generation - Generates Mermaid diagram code with auto-validation and retry logic
Performance Optimization
Stage 2 analysis runs in the background while users review Stage 1 results, reducing perceived latency and improving the user experience.

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

Install Dependencies
# Clone the repository
git clone <repository-url>
cd diagram-generator

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env.local

Configuration

Configure your environment variables in .env.local:

.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
Security Notice
Never commit .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

uploadAndScanPDF
PII Scanning
The upload process automatically scans for personally identifiable information (PII) including names, addresses, phone numbers, emails, and social security numbers.

Workflow Identification

identifyWorkflowsFromText

Diagram Generation

generateDiagramForWorkflow
Auto-validation
Generated diagrams are automatically validated by rendering them in a hidden container. If rendering fails, the system retries with automatic syntax fixes up to 3 times.

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.

Authentication Flow
// 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:

bash
# Run type checking
npm run typecheck

# Run tests
npm run test

# Build for production
npm run build

# Start production server
npm start
Build Requirements
Ensure all environment variables are set before building. The build process requires valid Firebase credentials and at least one AI provider API key.

Environment Variables

Required environment variables for production deployment:

VariableRequiredDescription
NEXT_PUBLIC_FIREBASE_*YesFirebase configuration
ANTHROPIC_API_KEYOptionalAnthropic Claude API access
OPENAI_API_KEYOptionalOpenAI GPT-4 API access
GOOGLE_AI_API_KEYOptionalGoogle Gemini API access
UPSTASH_REDIS_*RecommendedRedis caching configuration
Firebase Hosting Ready
This application is configured for Firebase App Hosting with Next.js SSR support. Seeapphosting.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.