VA Form Tool - Technical Specification Executive Summary The VA Form Tool is an enterprise-grade AI-powered application that automates the creation of VA.gov Simple Forms. It transforms PDF form documents into production-ready React applications using Claude Opus 4.1, multi-agent orchestration, and pattern-based code generation.

Key Metrics:

Generation Speed: 2 minutes for a 25-page form (5x faster than single-agent approach) Success Rate: 95%+ for forms with gold standard examples Code Quality: Automated verification with 9 categories of checks Scale: Supports forms from 1-50 pages with conditional logic and array builders Table of Contents Architecture Overview Core Features Multi-Agent System Technology Stack API Reference User Workflows AI/ML Pipeline Integration Points Code Generation Verification System Performance & Scalability Security & Privacy

1. Architecture Overview 1.1 System Architecture ┌─────────────────────────────────────────────────────────────┐ │ VA Form Tool │ │ ┌────────────┐ ┌─────────────┐ ┌──────────────────────┐ │ │ │ Next.js UI │ │ API Layer │ │ AI Multi-Agent │ │ │ │ (React) │◄─┤ (20 routes)├─►│ Orchestrator │ │ │ └────────────┘ └─────────────┘ └──────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────┐ ┌─────────────┐ ┌──────────────────────┐ │ │ │ Wizard │ │ PDF Process │ │ Pattern Analyzer │ │ │ │ 6 Steps │ │ (pdftk) │ │ Gold Standards │ │ │ └────────────┘ └─────────────┘ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────┐ │ External Integrations │ │ ┌────────────┐ ┌────────────────────┐ │ │ │ vets- │ │ Anthropic API │ │ │ │ website │ │ Claude Opus 4.1 │ │ │ └────────────┘ └────────────────────┘ │ │ ┌────────────┐ ┌────────────────────┐ │ │ │ VADS MCP │ │ Blueprint Library │ │ │ │ Server │ │ (8 forms) │ │ │ └────────────┘ └────────────────────┘ │ └──────────────────────────────────────────┘ 1.2 Technology Layers Presentation Layer

Next.js 14 App Router React 18 with TypeScript Tailwind CSS 4.1 Radix UI + shadcn/ui components Business Logic Layer

AI orchestration (multi-agent pipeline) Pattern matching and analysis Code generation and verification PDF processing and field extraction Data Layer

File-based job storage (JSON) Blueprint library (8 pre-built forms) Gold standard indexing Feedback collection (JSONL) Integration Layer

vets-website repository Anthropic API (Claude models) VADS MCP Server pdftk (PDF processing) 2. Core Features 2.1 PDF Processing & Field Extraction Capabilities:

Upload VA form PDFs (drag-and-drop, up to 50MB) Extract form fields using two methods: pdftk: Native PDF field extraction (fastest) AI Analysis: Claude Opus analyzes PDF text and structure Extract metadata: title, form number, subject, author, creation date Auto-detect VA form numbers from content Generate PDF previews (first page only) Implementation:

/lib/pdf-processor.ts (1,009 lines) - Main orchestration /lib/pdftk-extractor.ts (631 lines) - pdftk integration /lib/va-form-analyzer.ts (212 lines) - AI-powered analysis /app/api/upload/route.ts - Upload endpoint with streaming Output:

{ formNumber: "21P-530", title: "Application for Burial Benefits", fields: [ { name: "veteranFullName", type: "text", page: 1 }, { name: "veteranSSN", type: "ssn", page: 1 } ], metadata: { author: "VA", creationDate: "2023-01-01" } } 2.2 Yeoman Scaffold Generation Purpose: Creates the base VA Simple Form scaffold in vets-website

Why Not Native Yeoman?

Yeoman requires interactive prompts Cannot run non-interactively Sub-generators don't receive all options PTY/stdin workarounds fail in Next.js Solution: YeomanFallback

Custom generator that creates all required files Generates 10+ files programmatically Tries native Yeoman first, falls back automatically Generated Files:

manifest.json - App metadata and routing app-entry.jsx - Webpack entry point routes.jsx - React Router configuration reducers/index.js - Redux store sass/{form-name}.scss - Form-specific styles containers/App.jsx - Main container with save-in-progress containers/IntroductionPage.jsx - Landing page containers/ConfirmationPage.jsx - Submission confirmation config/form.js - Form configuration (chapters, pages) pages/nameAndDateOfBirth.js - Sample page config/prefill-transformer.js - Data prefill logic config/submit-transformer.js - Submission payload transformation Implementation:

/lib/yeoman-fallback.ts (488 lines) /lib/yeoman-runner.ts (180 lines) - Tries native first /scripts/run-yeoman.js - Standalone Yeoman script /app/api/yeoman/execute/route.ts - API endpoint 2.3 Pattern Matching & Gold Standards Gold Standard Discovery:

Searches vets-website for similar forms Analyzes 200+ existing forms Scores by similarity (category, complexity, features) Extracts reusable patterns Similarity Scoring:

score = categoryMatch * 40 + // Same category (pension, disability, etc.) complexityMatch * 20 + // Similar complexity level featureOverlap * 30 + // Shared features (arrays, conditionals) formPrefixMatch * 10 // Form number prefix similarity Pattern Catalog (50+ patterns):

fullNameUI + fullNameSchema addressUI + addressSchema dateOfBirthUI + dateOfBirthSchema ssnUI + ssnSchema phoneUI + phoneSchema emailUI + emailSchema yesNoUI + yesNoSchema arrayBuilderPages (for repeating items) fileUploadUI + fileUploadSchema And 40+ more... Implementation:

/lib/pattern-analyzer.ts (921 lines) /lib/gold-standard-index.ts (172 lines) /app/api/gold-standards/search/route.ts 2.4 AI-Powered Page Generation Two Approaches:

Legacy (Single-Agent):

One AI call generates all pages 10+ minutes for complex forms Higher chance of errors Harder to debug Modern (Multi-Agent):

Specialized agents work in parallel 2 minutes for 25-page form Higher reliability Clear error isolation 5x faster Generated Code:

// Example generated page import { titleUI, fullNameUI, fullNameSchema } from 'platform/forms-system/src/js/web-component-patterns';

export default { uiSchema: { ...titleUI('Veteran information'), veteranFullName: fullNameUI(), }, schema: { type: 'object', properties: { veteranFullName: fullNameSchema, }, required: ['veteranFullName'], }, }; Implementation:

/lib/page-generator.ts (1,923 lines) - Legacy single-agent /lib/agents/multi-agent-orchestrator.ts - Modern orchestrator /app/api/pages/generate/route.ts - Single-agent endpoint /app/api/pages/generate-multi-agent/route.ts - Multi-agent endpoint 2.5 Blueprint System Pre-built Blueprints (8 forms):

21P-0516-1 (Pension claim) 21-4170 (Disability claim) 21P-4171 (Marital status) 21P-601 (Pension application) 21P-0537 (Marital questionnaire) 21P-0518-1 (Burial benefits) 10-10EZ (Health benefits) 22-1990 (Education benefits) Blueprint Contents:

{ "formNumber": "21P-530", "metadata": { "title": "Burial Benefits", "category": "pension" }, "chapters": [ { "id": "veteranInfo", "title": "Veteran Information", "pages": [ { "id": "veteranDetails", "title": "Veteran's details", "fields": [ { "fieldName": "veteranFullName", "uiPattern": "fullNameUI", "schemaPattern": "fullNameSchema", "pdfFieldMapping": ["name_first", "name_last"] } ] } ] } ] } Benefits:

Instant plan generation for known forms Higher accuracy (based on actual forms) Faster field mapping Reusable templates 3. Multi-Agent System 3.1 Architecture ┌──────────────────────────────────────────────────────┐ │ Multi-Agent Orchestrator │ └──────────────────────────────────────────────────────┘ │ ┌───────────────┼────────────────┐ ▼ ▼ ▼ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │ Structure │ │ Page Code │ │ Import/Export│ │ Planner │ │ Generator │ │ Validator │ │ │ │ (Parallel) │ │ │ │ ~5 seconds │ │ ~3-5s/page │ │ ~5 seconds │ └─────────────┘ └──────────────┘ └──────────────┘ │ │ │ └───────────────┼────────────────┘ ▼ ┌──────────────┐ │ Integration │ │ Tester │ │ ~5-10s │ └──────────────┘ │ ▼ ┌──────────────┐ │ Write Files │ │ to Disk │ └──────────────┘ 3.2 Agent Responsibilities Agent 1: Structure Planner

Input: Extracted fields + blueprint (optional) Tasks: Validate form structure Deduplicate fields (field-based + arrayPath-based) Organize into chapters and pages Assign UI/schema patterns Detect conditional logic Output: ValidatedPageStructure[] Time: ~5 seconds Model: Claude Opus 4.1 Agent 2: Page Code Generator (Parallel)

Input: Single ValidatedPageStructure Tasks: Generate page component code Apply UI patterns correctly Handle conditional logic Support array builders Ensure proper export naming Output: Generated JavaScript code Time: 3-5 seconds per page Parallelization: All pages generated simultaneously Model: Claude Opus 4.1 Agent 3: Import/Export Validator

Input: All generated page files Tasks: Validate import statements Check export names match usage Fix missing imports Detect hallucinated imports Ensure barrel exports correct Output: Fixed page files + validation report Time: ~5 seconds Model: Claude Sonnet 4.5 Agent 4: Integration Tester

Input: Generated pages + config/form.js Tasks: Test for syntax errors Verify structure integrity Check required fields present Validate conditional logic Test array builder configurations Output: Test results + issue list Time: 5-10 seconds Model: Claude Sonnet 4.5 3.3 Benefits Over Single-Agent Metric Single-Agent Multi-Agent Improvement Time (25 pages) 10+ minutes ~2 minutes 5x faster Success Rate 70% 95%+ +25% Cost per Form $2-3 $1-1.50 50% cheaper Debuggability Poor Excellent Clear agent boundaries Parallelization None Full All pages at once Error Isolation Hard Easy Agent-specific errors 3.4 Deduplication Strategy Problem: AI often generates duplicate fields or pages

Solution: Two-Tier Deduplication

Field-Based Deduplication (within a page)

Merges fields with same name Preserves all unique properties Combines conditional logic ArrayPath-Based Deduplication (across pages)

Identifies duplicate array builders by arrayPath Merges field definitions Prevents duplicate imports Implementation:

// Field-based dedup const uniqueFields = Array.from( fieldsMap.values() ).map(group => ({ ...group[0], // Merge all unique properties from duplicates ...Object.assign({}, ...group) }))

// ArrayPath-based dedup const uniquePages = pages.reduce((acc, page) => { if (page.isArrayBuilder) { const existing = acc.find(p => p.isArrayBuilder && p.arrayConfig?.arrayPath === page.arrayConfig?.arrayPath ) if (existing) { // Merge fields existing.fields.push(...page.fields) return acc } } acc.push(page) return acc }, []) 4. Technology Stack 4.1 Frontend { "framework": "Next.js 14 (App Router)", "language": "TypeScript 5.3", "ui": { "library": "React 18", "styling": "Tailwind CSS 4.1", "components": [ "Radix UI (primitives)", "shadcn/ui (high-level)", "lucide-react (icons)", "sonner (toasts)" ] }, "forms": "react-hook-form + zod", "fileUpload": "react-dropzone", "codeDisplay": "react-syntax-highlighter", "charts": "recharts" } 4.2 Backend { "runtime": "Node.js 18+ (22+ recommended)", "api": "Next.js API Routes", "streaming": "Server-Sent Events (SSE)", "pdfProcessing": "pdftk + pdftotext", "fileOps": "fs/promises (native)" } 4.3 AI/ML { "provider": "Anthropic", "models": { "primary": "claude-opus-4-1-20250805", "secondary": "claude-sonnet-4-5-20250929" }, "sdk": "@ai-sdk/anthropic + ai (Vercel AI SDK)", "contextWindows": { "opus": "200K tokens", "sonnet": "1M tokens" }, "maxOutput": "64K tokens (both models)" } 4.4 External Tools

Required

pdftk # PDF field extraction pdftotext # Text extraction from PDFs

Optional

git # For vets-website integration 4.5 Development & Testing { "testing": { "framework": "Jest + ts-jest", "runner": "Bun (fast) or Node (compatible)", "types": [ "Unit tests", "Integration tests", "API route tests" ] }, "tools": { "linting": "ESLint + TypeScript ESLint", "formatting": "Prettier", "validation": "Zod schemas" } } 5. API Reference 5.1 Upload & Jobs POST /api/upload

Upload PDF and extract fields Supports streaming responses (SSE) Max file size: 50MB Returns: Job ID GET /api/jobs

List all processing jobs Returns: Job[] with status GET /api/jobs/[id]

Get specific job details Returns: Job with extracted fields DELETE /api/jobs/clear

Clear jobs older than 24 hours Returns: Count of cleared jobs 5.2 Planning & Blueprints POST /api/generate-plan

Generate form implementation plan Input: Extracted fields + optional blueprint Returns: Plan with chapters and pages POST /api/transform

Transform fields to submission payload Input: Fields + blueprint Returns: Transformed payload GET /api/blueprints

List available blueprints Returns: Blueprint metadata array 5.3 Pattern & Gold Standards POST /api/patterns/analyze

Analyze fields and match patterns Input: Extracted fields Returns: Pattern matches with scores POST /api/gold-standards/search

Find similar forms in vets-website Input: Form metadata + fields Returns: Ranked list of similar forms GET /api/vads/search?q={query}

Search VA Design System patterns Uses: VADS MCP Server Returns: Pattern examples and docs GET /api/vads/component?name={component}

Get specific VADS component details Returns: Component documentation 5.4 Page Generation POST /api/pages/generate

Generate pages (single-agent, legacy) Input: Plan + gold standards Returns: Generated page files POST /api/pages/generate-multi-agent

Generate pages (multi-agent, recommended) Input: Plan + gold standards Returns: Streaming progress + files POST /api/pages/verify

Verify generated code Input: Form files Returns: Verification results (9 categories) POST /api/pages/fix

Auto-fix verification failures Input: Verification results Returns: Fixed files POST /api/pages/feedback

Submit feedback on generated code Input: File path + feedback + code snippet Returns: Success GET /api/pages/feedback?formNumber={number}

Get feedback for a form Returns: Feedback entries 5.5 Utilities POST /api/preview

Generate PDF preview (first page) Input: PDF file Returns: Image data URL POST /api/scaffold

Execute Yeoman scaffold Input: Scaffold configuration Returns: Streaming progress + files 6. User Workflows 6.1 Quick Extract (Simple)

1. Upload PDF ↓
2. Extract fields (pdftk + AI) ↓
3. View results ↓
4. Export JSON/CSV Use Case: Just need field data, not full form generation

Time: 30-60 seconds

6.2 Full Wizard (Recommended)

1. Upload & Extract ↓
2. Configure Yeoman ├─ Form number ├─ App name ├─ Folder name ├─ Tracking prefix └─ Template type ↓
3. Generate Scaffold ├─ Try native Yeoman ├─ Fallback if needed └─ Create 10+ files ↓
4. Find Gold Standards ├─ Search vets-website ├─ Score by similarity └─ Select best matches ↓
5. Analyze Patterns ├─ Map fields to patterns ├─ Detect conditional logic ├─ Identify array builders └─ Generate structure plan ↓
6. Generate Pages (Multi-Agent) ├─ Validate structure (5s) ├─ Generate pages in parallel (3-5s each) ├─ Validate imports/exports (5s) └─ Test integration (5-10s) ↓
7. Verify & Deploy ├─ Run verification checks ├─ Auto-fix issues └─ Ready for development Use Case: Complete form generation from PDF to production-ready code

Time: 5-10 minutes (mostly AI generation)

6.3 Manual Field Mapping

1. Upload PDF ↓
2. Extract fields ↓
3. Open Interactive Mapper ├─ Drag PDF fields to blueprint structure ├─ Search VADS patterns in real-time ├─ Assign UI/schema patterns └─ Configure conditional logic ↓
4. Generate with custom mapping Use Case: Complex forms that need manual intervention

Time: 15-30 minutes

7. AI/ML Pipeline 7.1 Model Selection Claude Opus 4.1 (Primary)

Use Cases: Plan generation Field transformation Page code generation Code fixing Context: 200K tokens Output: 64K tokens Strengths: High-quality code, follows complex instructions Claude Sonnet 4.5 (Secondary)

Use Cases: Pattern analysis (needs 1M context for large forms) Import/export validation Integration testing Context: 1M tokens (extended) Output: 64K tokens Strengths: Faster, cheaper, great for validation tasks 7.2 Prompt Engineering Key Techniques:

Few-Shot Learning: Provide 2-3 gold standard examples Chain of Thought: Break down complex tasks into steps Structured Output: Use JSON schemas for validation Negative Examples: Show what NOT to do Empathic Instructions: Emphasize critical rules multiple times Example Prompt Structure:

CONTEXT

You are a VA.gov form generator...

EXAMPLE (Follow this EXACTLY)

[Gold standard example]

REQUIREMENTS

1. Use ONLY platform/forms-system patterns
2. NO vets-json-schema imports
3. Double quotes for all strings ...

INPUT

[Extracted fields]

OUTPUT FORMAT

Return ONLY valid JavaScript code. No markdown, no explanations. 7.3 Code Sanitization Pipeline Stage 1: Quote Normalization

Convert single quotes → double quotes (linter requirement) Fix mismatched quotes (e.g., "text' → "text") Convert straight apostrophes → curly apostrophes (U+2019) in user-facing text Stage 2: Import Cleanup

Remove vets-json-schema imports Fix platform import paths Remove test-data.json imports Remove hallucinated constants files Stage 3: Structure Validation

Ensure all pages are top-level (no nested paths) Validate array builder export names match arrayPath Check for signature pages (should be removed) Stage 4: Pattern Validation

Verify all UI patterns have matching schema patterns Check for deprecated patterns Validate conditional logic syntax Implementation: /lib/page-generator.ts:26-96 (sanitizeGeneratedCode)

7.4 Hallucination Prevention Common AI Hallucinations:

Importing non-existent test-data.json Creating constants.js files that don't exist Using vets-json-schema (simple forms don't use it) Inventing new pattern names Incorrect platform import paths Prevention Strategies:

Explicit negative instructions ("DO NOT import test-data.json") Provide exhaustive list of valid patterns Show correct import paths in every example Post-processing removal of hallucinated imports Validation step catches and fixes 8. Integration Points 8.1 vets-website Location: ../vets-website (default) or $VETS_WEBSITE_PATH

Integration Points:

Scaffold Output: Creates files in src/applications/simple-forms/{form-name}/ Gold Standard Search: Searches all src/applications/ for similar forms Pattern Extraction: Extracts reusable patterns from existing forms Testing: Can be tested in vets-website with yarn watch Required Setup:

Clone vets-website: git clone https://github.com/department-of-veterans-affairs/vets-website.git Set environment variable: VETS_WEBSITE_PATH=../vets-website Install dependencies: cd vets-website && yarn install Apply Node 22 patch (see README) 8.2 Anthropic API Configuration:

Set ANTHROPIC_API_KEY environment variable Get key from: https://console.anthropic.com/ Usage Patterns:

Streaming for long operations (SSE) Batching for parallel page generation Retry logic with exponential backoff Cost tracking and token counting Costs (Approximate):

Small form (5 pages): $0.50-1.00 Medium form (15 pages): $1.00-2.00 Large form (30 pages): $2.00-3.00 8.3 VADS MCP Server URL: https://vads-mcp.a6lab.ai/sse

Purpose: Real-time access to VA Design System patterns

Endpoints:

/search - Search patterns by keyword /component - Get component details /patterns - List all patterns Benefits:

Up-to-date pattern documentation Accessibility guidelines Best practices from design.va.gov Real-time pattern examples Implementation: /lib/mcp/vads-client.ts

8.4 Blueprint Library Location: /blueprints/*.plan.json

Structure:

{ "formNumber": "21P-530", "metadata": { "title": "...", "category": "..." }, "chapters": [...], "pdfFieldMappings": {...} } Usage:

Auto-loaded by form number Used for field-to-structure mapping Speeds up generation significantly Can be manually edited/extended 9. Code Generation 9.1 Generated File Structure src/applications/simple-forms/{form-name}/ ├── manifest.json # App metadata ├── app-entry.jsx # Webpack entry ├── routes.jsx # React Router config ├── sass/ │ └── {form-name}.scss # Form styles ├── reducers/ │ └── index.js # Redux store ├── containers/ │ ├── App.jsx # Main container │ ├── IntroductionPage.jsx # Landing page │ └── ConfirmationPage.jsx # Submission confirmation ├── config/ │ ├── form.js # Form configuration │ ├── prefill-transformer.js # Data prefill │ └── submit-transformer.js # Submission transform └── pages/ ├── index.js # Page barrel export ├── veteranInfo.js # Example page ├── contactInfo.js # Example page └── dependentsPages.js # Array builder example 9.2 Page Templates Regular Page:

import { titleUI, fullNameUI, fullNameSchema, } from 'platform/forms-system/src/js/web-component-patterns';

export default { uiSchema: { ...titleUI('Page title'), fieldName: fullNameUI(), }, schema: { type: 'object', properties: { fieldName: fullNameSchema, }, required: ['fieldName'], }, }; Array Builder Page:

import { arrayBuilderPages } from 'platform/forms-system/src/js/patterns/array-builder'; import { arrayBuilderYesNoUI, arrayBuilderYesNoSchema, arrayBuilderItemFirstPageTitleUI, fullNameUI, fullNameSchema, } from 'platform/forms-system/src/js/web-component-patterns';

const dependentsOptions = { arrayPath: 'dependents', nounSingular: 'dependent', nounPlural: 'dependents', required: true, maxItems: 10, };

export const dependentsPages = arrayBuilderPages( dependentsOptions, pageBuilder => ({ dependentsSummary: pageBuilder.summaryPage({ title: 'Dependents', path: 'dependents', uiSchema: dependentsSummaryPage.uiSchema, schema: dependentsSummaryPage.schema, }), dependentsDetails: pageBuilder.itemPage({ title: 'Dependent information', path: 'dependents/:index/details', uiSchema: dependentsDetailsPage.uiSchema, schema: dependentsDetailsPage.schema, }), }) ); Conditional Logic:

{ uiSchema: { hasRemarried: yesNoUI('Have you remarried?'), spouseName: { ...fullNameUI('Spouse name'), 'ui:options': { depends: formData => formData.hasRemarried === true } } } } 9.3 Form Configuration config/form.js Structure:

export default { formId: '21P-530', version: 0, prefillEnabled: true, savedFormMessages: { notFound: 'Please start over...', noAuth: 'Please sign in...', }, title: 'Apply for burial benefits', subTitle: 'Form 21P-530', defaultDefinitions: {}, chapters: { veteranInfo: { title: 'Veteran information', pages: { veteranDetails: { path: 'veteran-details', title: 'Veteran details', uiSchema: veteranDetailsPage.uiSchema, schema: veteranDetailsPage.schema, } } } } }; 10. Verification System 10.1 Verification Categories (9 Total)

1. Syntax & Quote Style

Unterminated strings Mixed quotes (must be double quotes) Quotes after JSX tags 2. Import Paths

Correct platform imports (platform/startup, platform/polyfills) Sass imports present No hallucinated imports 3. Required Configuration

preSubmitInfo present v3SegmentedProgressBar: true footerContent imported transformForSubmit configured prefillTransformer configured 4. No Hallucinated Imports

No test-data.json No constants.js No vets-json-schema 5. File Structure

All required files present Proper directory organization 6. Depends Logic

Proper formatting of depends functions Optional chaining (?.) usage Strict equality (===) checks 7. Sass Imports

CSS library variables Form process module Schemaform styles Form confirmation styles 8. Page Imports/Exports

pages/index.js exists All imported pages exported Barrel export pattern correct 9. PDF Accuracy

All PDF fields represented Array builders match PDF structure Conditional logic preserved 10.2 Auto-Fix Capabilities Automatic Fixes:

Remove vets-json-schema imports → Replace with platform imports Fix platform import paths → Correct to platform/startup etc. Remove test-data.json imports → Delete lines Remove constants imports → Delete lines Add missing sass imports → Append to sass file Add missing required imports → Add to file Manual Review Required:

Complex conditional logic errors Incorrect page structure Missing PDF fields Incorrect array builder configuration 10.3 Verification API POST /api/pages/verify

Input:

{ "formPath": "/path/to/form", "formNumber": "21P-530" } Output:

{ "success": false, "issues": [ { "category": "import-paths", "severity": "error", "message": "Invalid import: vets-json-schema", "file": "config/form.js", "line": 12, "autoFixable": true } ], "stats": { "totalIssues": 5, "errors": 2, "warnings": 3, "autoFixable": 4 } } 11. Performance & Scalability 11.1 Generation Performance Form Size Single-Agent Multi-Agent Speedup 5 pages 3-4 min 45-60 sec 4x 15 pages 7-10 min 90-120 sec 5x 25 pages 12-15 min 2-3 min 5-6x 40 pages 20+ min 3-4 min 6x 11.2 Scalability Limits Current Limits:

PDF Size: 50MB max (configurable) Form Complexity: Up to 50 pages (tested) Concurrent Jobs: 10 simultaneous uploads Storage: 24-hour job retention AI Context: 200K tokens (Opus), 1M tokens (Sonnet) Bottlenecks:

AI API rate limits (Anthropic tier-based) File I/O for large forms pdftk processing time for complex PDFs Optimization Strategies:

Parallel page generation (already implemented) Caching of gold standard searches Blueprint pre-loading for known forms Streaming responses for long operations 11.3 Cost Analysis Per-Form Costs (USD):

Form Size Tokens Used API Cost Time Small (5p) ~50K $0.50 1 min Medium (15p) ~150K $1.50 2 min Large (30p) ~300K $3.00 3 min Cost Breakdown:

Structure Planning: 20% Page Generation: 60% Validation/Testing: 20% Monthly Costs (Example):

10 forms/day × 30 days = 300 forms/month Average cost: $1.50/form Total: $450/month 12. Security & Privacy 12.1 Data Handling PDF Processing:

PDFs stored temporarily in /temp/pdfs/ Auto-deleted after 24 hours Not uploaded to external servers (except Anthropic API) Extracted Data:

Field names and metadata sent to Anthropic API Field values NOT sent (only structure) No PII processed or stored Generated Code:

Stored locally in vets-website Not transmitted to external services Committed to version control as needed 12.2 API Security Anthropic API:

API key stored in environment variable Not exposed to frontend All calls server-side only VADS MCP Server:

Public API, no authentication required Read-only access to design system docs No sensitive data transmitted 12.3 Access Control Current State:

No authentication (local development tool) All features available to localhost No multi-tenancy Production Recommendations:

Add OAuth/SAML authentication Role-based access control Audit logging for generated code Rate limiting per user Appendix A: Environment Variables

Required

ANTHROPIC_API_KEY=sk-ant-... # Anthropic API key

Optional

VETS_WEBSITE_PATH=../vets-website # Path to vets-website repo CONTENT_BUILD_PATH=../content-build # Path to content-build repo (optional) NODE_ENV=development # Environment (development, production) Appendix B: Common Issues Issue: pdftk not found Solution: brew install pdftk-java (Mac) or apt-get install pdftk (Linux)

Issue: Native Yeoman fails Solution: Fallback generator runs automatically, no action needed

Issue: AI generates incorrect imports Solution: Verification system auto-fixes most import issues

Issue: Form number not detected Solution: Manually enter form number in Yeoman config step

Issue: Gold standards not found Solution: Check VETS_WEBSITE_PATH environment variable

Appendix C: Development Commands

Development

npm run dev # Start dev server (port 5005) npm run build # Build for production npm run start # Start production server npm run lint # Run ESLint

Testing

npm run test # Run all tests npm run test:watch # Watch mode npm run test:coverage # Generate coverage report npm run test:integration # Integration tests only npm run test:unit # Unit tests only

Utilities

npm run analyze:tokens # Analyze AI token usage ./scripts/test-scaffold.sh FORM-NUMBER # Test scaffold generation Last Updated: November 19, 2025 Version: 2.0.0 (Multi-Agent) Author: @amponce / agile6