📋 AI-Powered Checklist Generator

A .NET 9 web application that converts DOCX documents to interactive SurveyJS forms using Google Gemini AI for intelligent document analysis and checklist generation.

🌐 Live Application

🚀 Currently deployed and running:

Production: https://checklist.stephentyrrell.ie ⭐ (Custom Domain - HTTPS)
Azure URL: https://checklist-generator-stable.eastus.azurecontainer.io
HTTP Fallback: http://checklist.stephentyrrell.ie

Upload your DOCX files and convert them to interactive SurveyJS forms instantly using AI-powered analysis!

🤖 AI-Enhanced: This application now uses Google Gemini AI to intelligently analyze document content, extract actionable items, and generate comprehensive checklists. No more regex patterns or static parsing - the AI understands context and creates meaningful, structured forms from any document type.

✨ AI-Powered Features

🎯 Complete AI Integration (Recently Updated)

All document processing has been migrated from static regex patterns to Google Gemini AI for intelligent analysis:

🧠 Intelligent Document Analysis: Gemini AI understands document structure and content context
📝 Smart Checklist Generation: Automatically identifies actionable items, requirements, and compliance points
🎯 Context-Aware Processing: AI preserves important regulatory and procedural information
🔄 Enhanced SurveyJS Conversion: Better form generation with appropriate question types
📊 Structured Excel Output: AI-generated Excel files with proper categorization and formatting

🔧 Technical AI Implementation

GeminiService: Centralized AI service using HTTP REST API integration
ExcelProcessor: AI-powered Excel content analysis and checklist extraction
SurveyJSConverter: Intelligent form generation with question type detection
DocxToExcelConverter: Enhanced document processing with AI-driven content understanding
Error Handling: Robust fallbacks and graceful degradation when AI is unavailable

🚀 Benefits Over Previous System

No More Regex: Replaced complex pattern matching with intelligent content understanding
Flexible Processing: Works with any document structure or content type
Better Accuracy: AI understands context, relationships, and document intent
Improved Output: More relevant and actionable checklist items
Future-Proof: Easy to enhance and adapt AI prompts for specific use cases

📚 Table of Contents

Quick Start
AI Configuration
Features
API Endpoints
Architecture
Document Processing Workflow
Deployment Options
Local Development
Azure Setup
Custom Domain Configuration
Cloudflare Integration
GitHub Codespaces
Testing
Troubleshooting
Technology Stack
Project Status
Getting Started Checklist

🚀 Quick Start

Option 1: Use Live Application

Visit https://checklist.stephentyrrell.ie and start converting DOCX files immediately!

Option 2: GitHub Codespaces (Development)

Click Code → Codespaces → Create codespace
Run ./start.sh in the terminal
Access via forwarded port URL

Option 3: Local Development

cd ChecklistGenerator
dotnet restore
dotnet run
# Visit http://localhost:5000

📋 API Endpoints

POST /api/checklist/upload

Upload and convert a Word document to SurveyJS format with automatic format detection and conversion.

Request:

Content-Type: multipart/form-data
Body: Word document file (.docx)

Response:

{
  "success": true,
  "fileName": "document.docx",
  "itemCount": 5,
  "surveyJS": { /* SurveyJS JSON format */ },
  "excelDownloadId": "guid-string",
  "excelFileName": "document_20250726_103254.xlsx",
  "message": "Successfully processed document using DOCX to Excel conversion.",
  "hasIssues": false
}

GET /api/checklist/downloadExcel/{downloadId}

Download the generated Excel file using the download ID from the upload response.

Parameters:

downloadId: The download ID returned from the upload response

Response:

Excel file download (.xlsx format)

GET /api/checklist/sample

Get a sample SurveyJS JSON for testing purposes.

Response:

{
  "success": true,
  "surveyJS": { /* Sample survey JSON in SurveyJS format */ }
}

GET /api/checklist/samples

Get available sample documents for testing.

Response:

{
  "success": true,
  "samples": [
    {
      "fileName": "ucits-section2.docx",
      "displayName": "UCITS Section 2",
      "description": "European investment fund compliance checklist",
      "icon": "📊",
      "downloadUrl": "/samples/ucits-section2.docx"
    }
  ]
}

POST /api/checklist/saveResults

Save survey response data for analysis and record keeping.

Request:

Content-Type: application/json
Body:

{
  "surveyData": {
    "item_1": "Company ABC",
    "item_2": true,
    "item_3": "UCITS"
  },
  "timestamp": "2025-07-26T10:30:00.000Z"
}

Response:

{
  "success": true,
  "id": "unique-submission-id",
  "message": "Survey results saved successfully",
  "timestamp": "2025-07-26T10:30:00.000Z"
}

GET /health

Health check endpoint provided by nginx for monitoring and load balancing.

Response:

healthy

Error Response (All Endpoints):

{
  "success": false,
  "message": "Error description",
  "details": "Additional error information"
}

🤖 AI Configuration

Getting Started with Gemini AI

Get a Gemini API Key:
- Visit Google AI Studio
- Create a new API key
- Copy the key

Configure the Application:

For Local Development (Recommended - Secure):

# Use .NET User Secrets (keeps API key out of source control)
dotnet user-secrets init
dotnet user-secrets set "GeminiApiKey" "your_actual_api_key_here"

Alternative for Local Development:

# Copy example file and update with your key
cp appsettings.example.json appsettings.local.json
# Edit appsettings.local.json and add your API key
# Note: appsettings.local.json is excluded from git

For Production/Azure:

# Set environment variable
export GeminiApiKey="your_actual_api_key_here"

# Or in Azure Container Instances
az container create \
  --environment-variables GeminiApiKey="your_actual_api_key_here"

⚠️ Security Note: Never commit API keys to source control. The main appsettings.json should not contain sensitive values.

Verify Configuration:
- Upload a test DOCX file
- Check logs for "processing with Gemini AI" messages
- Confirm AI-generated checklist items in response

AI Processing Features

Core Services Enhanced with AI:

GeminiService.cs: New centralized AI service handling all Gemini API interactions
ExcelProcessor.cs: Completely rewritten to use AI for content extraction and analysis
SurveyJSConverter.cs: Enhanced with AI-powered form generation and question type detection
DocxToExcelConverter.cs: Upgraded with AI-driven document understanding and structuring

AI Capabilities:

Document Analysis: Extracts meaningful content from complex documents with context understanding
Checklist Generation: Creates actionable items with proper categorization and priority
SurveyJS Conversion: Generates appropriate question types and logical form structures
Content Interpretation: Understands regulatory text, procedures, and compliance requirements
Error Handling: Graceful fallbacks when AI processing fails, with comprehensive logging

Performance & Reliability:

Async Processing: Non-blocking AI calls for better application responsiveness
HTTP Client Pool: Efficient connection management for Gemini API requests
Retry Logic: Built-in error handling and retry mechanisms
Fallback Systems: Graceful degradation when AI services are unavailable

🔄 Document Processing Workflow

The application uses a sophisticated multi-stage processing workflow:

Stage 1: DOCX Processing & Validation

File Upload: Secure handling with format validation (.docx only)
Size Limits: 50MB maximum file size for optimal performance
Security: In-memory processing without persistent storage
Format Detection: Automatic validation of DOCX structure

Stage 2: DOCX to Excel Conversion

Modern Processing: Direct processing of .docx files using DocumentFormat.OpenXml
Structured Extraction: Conversion to Excel format for better data analysis
Content Preservation: Maintains formatting, tables, and structure
In-Memory Generation: Creates Excel file for download without disk storage

Stage 3: Content Analysis & Extraction

The application intelligently analyzes Excel data for:

Question Detection: Text patterns indicating questions (?, "please", interrogative words)
Table Processing: Structured data from tables with question/answer relationships
Form Elements: Recognition of checkboxes, input fields, and interactive components
List Recognition: Numbered, lettered, or bulleted option lists
Required Fields: Detection of mandatory field indicators (*, "required", "mandatory")
Context Understanding: Relationships between questions, choices, and sections

Stage 4: SurveyJS Conversion & Optimization

Type Inference: Automatic determination of appropriate question types:
- Text: Open-ended questions and text input
- Boolean: Yes/No questions and binary choices
- Radio Group: Single selection from multiple options
- Checkbox: Multiple selection capabilities
- Dropdown: Selection from dropdown lists
- Comment: Large text areas for detailed responses
Structure Optimization: Logical grouping and ordering of survey elements
Validation: Ensuring generated JSON meets SurveyJS schema requirements
Metadata Generation: Title, description, and configuration settings

Stage 5: Interactive Preview & Testing

Real-time Rendering: Generated JSON rendered using actual SurveyJS library
Response Testing: Complete surveys directly in the application
Validation Testing: Test required fields and validation rules
Export Capabilities: Download responses and survey definitions

✨ Features

Core Functionality

DOCX Upload: Upload Word documents (.docx format only)
Intelligent Content Extraction: Automatically extract checklist items and questions from complex documents
Excel Conversion: Automatically converts DOCX to Excel format in memory for structured processing
SurveyJS Output: Generates industry-standard interactive forms from document content
Interactive Survey Preview: Real-time preview of generated surveys using actual SurveyJS rendering
Survey Response Testing: Complete and test surveys directly in the application
Response Export: Save and export survey responses in JSON format
Download Support: Download the converted Excel file for reference
Sample Documents: Access built-in sample documents for testing
In-Memory Processing: Files are processed securely in memory without local storage

Advanced Processing Features

Smart Question Detection: Identifies questions (text ending with ?, starting with "please", etc.)
Table Processing: Extracts structured data from tables with question/answer pairs
Form Elements Recognition: Detects checkboxes, form fields, and interactive elements
List Recognition: Processes numbered or lettered option lists and choice structures
Required Field Detection: Identifies indicators like *, "required", "mandatory"
Context Understanding: Maintains relationships between questions and answer choices
Multiple Question Types: Supports text, boolean, radio, checkbox, dropdown, and comment types

Enterprise Features

HTTPS Support: SSL encryption with certificates
Custom Domain: Professional branding (checklist.stephentyrrell.ie)
nginx Reverse Proxy: Production-ready with security headers
Auto-scaling: Azure Container Instances with scaling
CI/CD Pipeline: Automated building, testing, and deployment
Global CDN: Cloudflare integration for worldwide performance
DDoS Protection: Enterprise-level security
Health Monitoring: Built-in health check endpoints

Developer Features

Comprehensive Testing: 50+ unit tests with coverage reports
Multiple Deployment Options: Azure, Codespaces, Local
Docker Support: Containerized for consistent environments
GitHub Actions: Automated workflows and deployment
Service-Oriented Architecture: Clean separation of concerns with dedicated services

🏗️ Architecture

High-Level Architecture

Internet → Cloudflare CDN → nginx (80/443) → .NET App (5000)
         ↗ SSL Termination     ↗ HTTP/HTTPS        ↗ Application Logic
         ↘ DDoS Protection     ↘ Load Balancing    ↘ Document Processing

Service-Oriented Architecture

The application follows a clean, service-oriented architecture with clear separation of concerns:

Core Services

DocxToExcelConverter: Converts .docx files to Excel format for structured processing
ExcelProcessor: Processes Excel files and extracts structured content to identify checklist items
SurveyJSConverter: Converts extracted content to SurveyJS JSON format

Controllers

ChecklistController: REST API endpoints for file upload, processing, and download operations

Models

ChecklistItem: Data model for extracted checklist items with type information
SurveyJSForm: Models for SurveyJS schema and survey elements

Processing Pipeline

File Upload & Validation: Secure file handling with format detection
Document to Excel Conversion: Convert DOCX files to Excel format for structured data extraction
Content Analysis: Intelligent parsing of Excel data to extract questions and form elements
Data Transformation: Conversion to SurveyJS-compatible format
Response Generation: JSON output with comprehensive status information

Technology Stack

.NET 9: Modern web framework with minimal APIs and high performance
DocumentFormat.OpenXml: Modern .docx document processing and manipulation
ClosedXML: Excel generation and formatting
NPOI: Additional Excel support and compatibility
nginx: Reverse proxy and SSL termination
Docker: Containerization and deployment
Azure Container Instances: Cloud hosting
Cloudflare: CDN, SSL, and security
GitHub Actions: CI/CD automation

Security Features

✅ SSL/TLS Encryption (TLSv1.2, TLSv1.3)
✅ Security Headers (HSTS, XSS Protection, Content-Type)
✅ Rate Limiting (10 requests/second protection)
✅ DDoS Protection (Cloudflare)
✅ Input Validation (File type and size limits)
✅ In-Memory Processing (No persistent file storage)
✅ CORS Configuration (Controlled cross-origin access)

🌍 Deployment Options

⭐ Production (Current)

URL: https://checklist.stephentyrrell.ie
Platform: Azure Container Instances + Cloudflare
SSL: Trusted certificates via Cloudflare
Performance: Global CDN with caching
Cost: FREE (within Azure and Cloudflare free tiers)
Features: Full enterprise features with health monitoring

☁️ Azure Container Instances

Automatic: Push to main branch triggers deployment
Manual: Use GitHub Actions → "Build and Deploy"
Scaling: Easy to scale up as needed
Monitoring: Azure built-in monitoring
Stable DNS: Uses checklist-generator-stable.eastus.azurecontainer.io

🧪 GitHub Codespaces (Development)

Purpose: Development and testing
Setup: Automatic environment configuration
Access: Forwarded port URL with HTTPS
Cost: Free (60 hours/month)
Features: Full VS Code environment with pre-configured dependencies

🏠 Local Development

Requirements: .NET 9 SDK
Port: http://localhost:5000
Hot Reload: Automatic during development
Database: No external dependencies required

🔧 Local Development

Prerequisites

.NET 9 SDK
Git
Optional: Docker (for container testing)

Setup

# Clone repository
git clone https://github.com/stephenjtyrrell/checklist-generator.git
cd checklist-generator

# Restore dependencies
cd ChecklistGenerator
dotnet restore

# Run application
dotnet run

# Visit application
open http://localhost:5000

Development Commands

# Build
dotnet build

# Run tests
cd ChecklistGenerator.Tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Publish for deployment
dotnet publish --configuration Release

☁️ Azure Setup

Required GitHub Secrets

For automated Azure deployment, configure these secrets in GitHub repository settings:

1. `AZURE_CREDENTIALS`

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "subscriptionId": "your-subscription-id",
  "tenantId": "your-tenant-id",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

2. `AZURE_CONTAINER_REGISTRY_NAME`

Your Azure Container Registry name (e.g., "checklistgen")

3. `GEMINI_API_KEY`

Your Google Gemini API key for AI-powered document processing

Create Azure Resources

# Login to Azure
az login

# Create resource group
az group create --name checklist-generator-rg --location eastus

# Create container registry
az acr create --resource-group checklist-generator-rg \
  --name YOUR_UNIQUE_NAME --sku Basic --admin-enabled true

# Create service principal for GitHub Actions
az ad sp create-for-rbac --name "checklist-generator-github" \
  --role contributor \
  --scopes /subscriptions/YOUR_SUBSCRIPTION_ID

Manual Deployment

# Build and push image
az acr build --registry YOUR_REGISTRY_NAME --image checklist-generator .

# Deploy container with stable DNS name
az container create \
  --resource-group checklist-generator-rg \
  --name checklist-generator \
  --image YOUR_REGISTRY.azurecr.io/checklist-generator:latest \
  --ports 80 443 \
  --environment-variables GeminiApiKey="YOUR_GEMINI_API_KEY" \
  --dns-name-label checklist-generator-stable

🌐 Custom Domain Configuration

Current Setup: checklist.stephentyrrell.ie

The application is configured with a professional custom domain using DNS CNAME records.

Stable DNS Configuration (Updated 2024)

The container now uses a stable DNS label that doesn't change between deployments:

Type: CNAME
Name: checklist
Value: checklist-generator-stable.eastus.azurecontainer.io
TTL: 300

⚠️ Action Required: Update your DNS CNAME record to point to the new stable FQDN above.

Legacy DNS (Will be deprecated)

Type: CNAME
Name: checklist  
Value: checklist-generator-1753371092.eastus.azurecontainer.io (timestamp-based - changes on redeploy)
TTL: 300

Benefits

✅ Professional Appearance: No Azure URLs in production
✅ Brand Consistency: matches stephentyrrell.ie domain
✅ SEO Friendly: Better search engine optimization
✅ SSL Ready: Works with Cloudflare SSL

Setting Up Your Own Domain

Purchase/Configure Domain: Get a domain name
Add DNS Record: Create CNAME pointing to Azure container
Wait for Propagation: 5-30 minutes typically
Test Access: Verify domain works
Optional: Add Cloudflare for SSL and performance

🌩️ Cloudflare Integration

Current Setup

The production application uses Cloudflare for:

✅ Free SSL Certificates (trusted by browsers)
✅ Global CDN (faster loading worldwide)
✅ DDoS Protection (enterprise-level security)
✅ Performance Optimization (caching, compression)
✅ Analytics (visitor insights)

Cloudflare Configuration

1. Add Domain to Cloudflare

Sign up at https://cloudflare.com (free)
Add stephentyrrell.ie to account
Update nameservers at domain registrar

2. DNS Records

Type: CNAME
Name: checklist
Value: checklist-generator-stable.eastus.azurecontainer.io
Proxy: ✅ Proxied (orange cloud)

3. SSL Settings

Encryption Mode: Full (not Full Strict)
Always Use HTTPS: Enabled
Min TLS Version: 1.2
Automatic HTTPS Rewrites: Enabled

4. Performance Settings

Auto Minify: CSS, JavaScript, HTML
Brotli Compression: Enabled
Browser Cache TTL: 4 hours

Benefits

Free Forever: No ongoing costs
Enterprise Features: DDoS protection, WAF, analytics
Global Performance: 200+ data centers worldwide
Reliability: 99.99% uptime SLA

🧪 GitHub Codespaces

Features

Instant Development Environment: Pre-configured with all dependencies
VS Code in Browser: Full IDE experience
Port Forwarding: Access application via HTTPS URL
Free Tier: 60 hours/month for free accounts

Usage

Option 1: Quick Start

Visit https://github.com/stephenjtyrrell/checklist-generator
Click Code → Codespaces → Create codespace
Wait for environment setup (2-3 minutes)
Run ./start.sh in terminal
Click forwarded port URL when prompted

Option 2: Customized Setup

# After codespace starts
cd ChecklistGenerator
dotnet restore
dotnet run

# Access via forwarded port 5000

Configuration Files

.devcontainer/devcontainer.json: Main configuration
.devcontainer/devcontainer-simple.json: Fallback configuration
start.sh: Application startup script

Troubleshooting Codespaces

Container Setup Issues

Rebuild Container: Ctrl+Shift+P → "Codespaces: Rebuild Container"
Check Logs: View → Output → "Dev Containers"
Use Simple Config: Rename devcontainer-simple.json if needed

Application Issues

# Check .NET installation
dotnet --version

# Restore packages
dotnet restore

# Build project
dotnet build

# Check port availability
netstat -tulpn | grep :5000

🧪 Testing

Test Coverage

The project includes comprehensive testing with 50+ unit tests covering:

✅ Models: Complete coverage of data models and DTOs
- ChecklistItemTests.cs - ChecklistItem model and ChecklistItemType enum
- SurveyJSFormTests.cs - All SurveyJS-related models
✅ Services: Core business logic and document processing
- SurveyJSConverterTests.cs - SurveyJS format conversion
- DocxToExcelConverterTests.cs - DOCX to Excel conversion functionality
- ExcelProcessorTests.cs - Excel file processing and content extraction
✅ Controllers: API endpoint testing
- ChecklistControllerTests.cs - Unit tests with mocked dependencies
✅ Integration: End-to-end API testing
- ChecklistControllerIntegrationTests.cs - Full workflow testing
✅ Configuration: Application setup validation
- StartupConfigurationTests.cs - Dependency injection and configuration
✅ Edge Cases: Extreme scenarios and error handling
- EdgeCaseTests.cs - Large files, unicode, malformed content
✅ Build Validation: Infrastructure testing
- BuildValidationTests.cs - Package references and build configuration

Test Categories

Unit Tests: Individual component testing with 90%+ coverage
Integration Tests: End-to-end workflow testing
Security Tests: Input validation and error handling
Performance Tests: Large file handling and memory management
Unicode Support: International character and special symbol testing

Running Tests

Local Testing

# Run all tests
cd ChecklistGenerator.Tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Generate coverage report
dotnet tool install --global dotnet-reportgenerator-globaltool
reportgenerator -reports:"**/coverage.cobertura.xml" -targetdir:"./coverage"

# Run specific test class
dotnet test --filter "ChecklistControllerTests"

# Run with verbose output
dotnet test --verbosity normal

GitHub Actions

Tests run automatically on:

Every push to main branch
All pull requests
Manual workflow dispatch
Feature branch pushes

Coverage Reports

HTML Reports: Detailed analysis with line-by-line coverage
Cobertura Format: CI integration and metrics
Text Summary: Quick overview in console output

Test Dependencies

xUnit: Primary testing framework
FluentAssertions: Fluent assertion library for readable tests
Moq: Mocking framework for dependency isolation
Microsoft.AspNetCore.Mvc.Testing: Integration testing support
coverlet.collector: Code coverage collection

🔍 Troubleshooting

Common Issues

❌ Container Won't Start

# Check container status
az container show --name checklist-generator --resource-group checklist-generator-rg

# View logs
az container logs --name checklist-generator --resource-group checklist-generator-rg

# Restart container
az container restart --name checklist-generator --resource-group checklist-generator-rg

❌ Custom Domain Not Working

Check DNS Propagation:

nslookup checklist.stephentyrrell.ie
# Should return Azure container IP

Verify DNS Record: Ensure CNAME points to correct Azure URL
Clear Browser Cache: Hard refresh (Ctrl+F5)
Check TTL Settings: Lower TTL for faster updates

❌ SSL Certificate Issues

Cloudflare: Ensure SSL mode is "Full" (not "Full Strict")
Browser Warning: Expected for self-signed certs without Cloudflare
Certificate Renewal: Self-signed certs valid for 365 days

❌ Application Errors

Health Check: Visit /health endpoint (https://checklist.stephentyrrell.ie/health)
File Upload Issues: Check file size (<50MB) and format (.docx only)
Memory Issues: Restart container if processing large files
Processing Errors: Check logs for detailed error information

Application File Structure

The project follows a clean, organized structure:

ChecklistGenerator/
├── Controllers/
│   └── ChecklistController.cs        # REST API endpoints and request handling
├── Models/
│   ├── ChecklistItem.cs             # Data models for extracted content
│   └── SurveyJSForm.cs              # SurveyJS schema models and DTOs
├── Services/
│   ├── DocxToExcelConverter.cs      # .docx to Excel conversion service
│   ├── ExcelProcessor.cs            # Excel file parsing and content extraction
│   └── SurveyJSConverter.cs         # JSON conversion and SurveyJS formatting
├── wwwroot/
│   ├── index.html                   # Main web interface with drag-and-drop
│   └── samples/                     # Sample DOCX files for testing
│       ├── ucits-section2.docx
│       └── ucits-section3.docx
├── Program.cs                       # Application configuration and DI setup
└── ChecklistGenerator.csproj        # Project dependencies and configuration

ChecklistGenerator.Tests/
├── Models/
│   ├── ChecklistItemTests.cs
│   └── SurveyJSFormTests.cs
├── Services/
│   ├── SurveyJSConverterTests.cs
│   ├── DocxToExcelConverterTests.cs
│   └── ExcelProcessorTests.cs
├── Controllers/
│   └── ChecklistControllerTests.cs
├── Integration/
│   └── ChecklistControllerIntegrationTests.cs
└── TestData/
    └── test-document.docx

Infrastructure/
├── Dockerfile                      # Multi-stage container build
├── nginx.conf                      # Reverse proxy and SSL configuration
├── supervisord.conf                 # Process management configuration
├── start-container.sh              # Container startup script
├── start.sh                        # Local development startup
└── .github/workflows/              # CI/CD automation
    ├── build-and-deploy.yml
    └── codespace-deploy.yml

❌ GitHub Actions Failures

Authentication Errors

Error: Login failed with Error: Using auth-type: SERVICE_PRINCIPAL

Solution: Verify GitHub secrets are correctly configured:

AZURE_CREDENTIALS: Complete JSON with all required fields
AZURE_CONTAINER_REGISTRY_NAME: Registry name only (no .azurecr.io)

Build Failures

# Check workflow status
gh run list --limit 5

# View logs for failed run
gh run view RUN_ID --log

Deployment Issues

Resource Group: Ensure exists in correct region
Registry Access: Verify container registry permissions
Port Configuration: Ensure ports 80 and 443 are exposed

Getting Help

Health Endpoint: https://checklist.stephentyrrell.ie/health
GitHub Issues: Create issue in repository for bugs or feature requests
Azure Monitoring: Check Azure portal for container metrics and logs
Cloudflare Analytics: Monitor traffic and performance metrics
Application Logs: Use Azure Container Instances log stream for debugging

🛠️ Technology Stack

Backend (.NET 9)

ASP.NET Core 9.0: Modern web framework with minimal APIs and high performance
DocumentFormat.OpenXml 3.3.0: Modern .docx document processing and manipulation
ClosedXML 0.104.1: Excel generation and formatting
NPOI 2.7.4: Additional Excel support and compatibility
Built-in JSON Serialization: SurveyJS format generation
Dependency Injection: Service-oriented architecture with scoped services

Frontend & User Interface

HTML/CSS/JavaScript: Responsive web interface with drag-and-drop support
SurveyJS Library: Interactive survey rendering and response collection
CDN Resources: SurveyJS core and UI libraries loaded from unpkg CDN
Bootstrap: Modern responsive design framework
Real-time Preview: Client-side survey rendering and testing

Infrastructure & Deployment

nginx: High-performance reverse proxy and load balancer
Docker: Multi-stage containerization for consistent deployments
Azure Container Instances: Managed container hosting with auto-scaling
Cloudflare: CDN, SSL, and security services
GitHub Actions: CI/CD automation and deployment pipelines
Supervisor: Process management for nginx and .NET application

Development & Testing

xUnit: Comprehensive unit testing framework
FluentAssertions: Readable and maintainable test assertions
Moq: Mocking framework for isolated testing
Microsoft.AspNetCore.Mvc.Testing: Integration testing capabilities
coverlet.collector: Code coverage analysis and reporting
GitHub Codespaces: Cloud development environment
VS Code: Recommended IDE with dev container support

Monitoring & Analytics

Azure Monitor: Container and application monitoring
Cloudflare Analytics: Traffic and performance metrics
GitHub Actions: Build and deployment monitoring
nginx Health Checks: Built-in health monitoring endpoints
Structured Logging: Comprehensive application logging with ILogger

Security & Performance

SSL/TLS: Cloudflare-managed certificates with automatic renewal
Security Headers: HSTS, XSS protection, content security policies
Rate Limiting: nginx-based request throttling
DDoS Protection: Cloudflare enterprise-grade protection
CORS Configuration: Controlled cross-origin resource sharing
Input Validation: File type, size, and content validation
In-Memory Processing: Secure file handling without persistent storage

File Processing Technologies

DocumentFormat.OpenXml: Native .docx reading and manipulation
NPOI: Excel file creation and data extraction
ClosedXML: High-level Excel operations and formatting
Stream Processing: Efficient memory management for large files
Async/Await: Non-blocking I/O operations

📊 Project Status

✅ Completed Features

Core Application: Document conversion pipeline fully functional
- DOCX to Excel conversion with DocumentFormat.OpenXml
- Intelligent content extraction and question detection
- SurveyJS format generation with multiple question types
- Real-time survey preview and testing capabilities
Testing Suite: Comprehensive unit test coverage (50+ tests)
- Models, Services, Controllers, and Integration tests
- Edge case handling and unicode support
- Build validation and configuration testing
CI/CD Pipeline: Automated build, test, and Azure deployment
- GitHub Actions workflows for continuous deployment
- Automated testing on pull requests and pushes
- Multi-environment deployment support
Production Deployment: Live on Azure with custom domain
- Stable DNS configuration with Azure Container Instances
- Custom domain (checklist.stephentyrrell.ie) with professional branding
SSL/HTTPS: Trusted certificates via Cloudflare
- Automatic certificate management and renewal
- Full SSL encryption and security headers
API Infrastructure: Complete REST API with comprehensive endpoints
- File upload and processing endpoints
- Sample document management
- Excel download capabilities
- Survey response saving and export
Documentation: Complete setup and usage guides
- Comprehensive README with step-by-step instructions
- API documentation with examples
- Troubleshooting guides and deployment procedures
Performance: Optimized with CDN and caching
- Global CDN via Cloudflare
- In-memory processing for optimal performance
- Efficient file handling and memory management
Security: Enterprise-grade protection and headers
- DDoS protection, rate limiting, and input validation
- Secure file processing without persistent storage

🎯 Architecture Highlights

Scalable: Container-based with auto-scaling capabilities
- Azure Container Instances with horizontal scaling
- Stateless design for easy replication
Secure: HTTPS, security headers, rate limiting, DDoS protection
- Multiple layers of security from application to infrastructure
- Input validation and secure file processing
Fast: Global CDN, compression, and optimized delivery
- Cloudflare CDN with 200+ global data centers
- nginx reverse proxy with performance optimizations
Reliable: 99.99% uptime with Cloudflare and Azure
- Health monitoring and automatic recovery
- Redundant infrastructure and monitoring
Cost-Effective: Runs within free tiers of Azure and Cloudflare
- Optimized resource usage
- No ongoing costs for small to medium usage
Developer-Friendly: Clean architecture with comprehensive testing
- Service-oriented design with clear separation of concerns
- Extensive test coverage and documentation

🔄 Continuous Improvements

Automated Testing: Every commit triggers full test suite
- Comprehensive unit and integration testing
- Code coverage reporting and quality gates
Security Scanning: Automated vulnerability checking
- Dependency scanning and security updates
- Container security and best practices
Performance Monitoring: Real-time metrics and alerting
- Application performance monitoring
- Infrastructure health checks and monitoring
Documentation: Living documentation updated with code changes
- Automatic documentation updates with deployments
- Comprehensive API documentation and examples

🚀 Current Capabilities Summary

Document Processing: Full DOCX to SurveyJS conversion pipeline
Interactive Features: Real-time survey preview and testing
API Complete: All necessary endpoints for full functionality
Production Ready: Live deployment with enterprise features
Developer Ready: Comprehensive testing and documentation
Scalable Infrastructure: Container-based with auto-scaling
Security Compliant: Enterprise-grade security features
Performance Optimized: Global CDN and efficient processing

🚀 Getting Started Checklist

For Users

Visit https://checklist.stephentyrrell.ie
Upload a .docx file
Download converted Excel file
Copy generated SurveyJS JSON

For Developers

Clone repository
Set up local development environment
Run tests locally
Create GitHub Codespace for cloud development
Deploy to Azure (optional)

For Production Deployment

🌐 Live Application: https://checklist.stephentyrrell.ie

💻 Source Code: https://github.com/stephenjtyrrell/checklist-generator

📧 Contact: [email protected]

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.devcontainer		.devcontainer
.github		.github
.vscode		.vscode
ChecklistGenerator.Tests		ChecklistGenerator.Tests
ChecklistGenerator		ChecklistGenerator
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
codespace-update.sh		codespace-update.sh
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
start-container.sh		start-container.sh
start.sh		start.sh
supervisord.conf		supervisord.conf
webhook-deploy.sh		webhook-deploy.sh

stephenjtyrrell/checklist-generator

Folders and files

Latest commit

History

Repository files navigation

📋 AI-Powered Checklist Generator

🌐 Live Application

✨ AI-Powered Features

🎯 Complete AI Integration (Recently Updated)

🔧 Technical AI Implementation

🚀 Benefits Over Previous System

📚 Table of Contents

🚀 Quick Start

Option 1: Use Live Application

Option 2: GitHub Codespaces (Development)

Option 3: Local Development

📋 API Endpoints

POST /api/checklist/upload

GET /api/checklist/downloadExcel/{downloadId}

GET /api/checklist/sample

GET /api/checklist/samples

POST /api/checklist/saveResults

GET /health

🤖 AI Configuration

Getting Started with Gemini AI

AI Processing Features

🔄 Document Processing Workflow

Stage 1: DOCX Processing & Validation

Stage 2: DOCX to Excel Conversion

Stage 3: Content Analysis & Extraction

Stage 4: SurveyJS Conversion & Optimization

Stage 5: Interactive Preview & Testing

✨ Features

Core Functionality

Advanced Processing Features

Enterprise Features

Developer Features

🏗️ Architecture

High-Level Architecture

Service-Oriented Architecture

Core Services

Controllers

Models

Processing Pipeline

Technology Stack

Security Features

🌍 Deployment Options

⭐ Production (Current)

☁️ Azure Container Instances

🧪 GitHub Codespaces (Development)

🏠 Local Development

🔧 Local Development

Prerequisites

Setup

Development Commands

☁️ Azure Setup

Required GitHub Secrets

1. AZURE_CREDENTIALS

2. AZURE_CONTAINER_REGISTRY_NAME

3. GEMINI_API_KEY

Create Azure Resources

Manual Deployment

🌐 Custom Domain Configuration

Current Setup: checklist.stephentyrrell.ie

Stable DNS Configuration (Updated 2024)

Legacy DNS (Will be deprecated)

Benefits

Setting Up Your Own Domain

🌩️ Cloudflare Integration

Current Setup

Cloudflare Configuration

1. Add Domain to Cloudflare

2. DNS Records

3. SSL Settings

4. Performance Settings

Benefits

🧪 GitHub Codespaces

Features

Usage

Option 1: Quick Start

1. `AZURE_CREDENTIALS`

2. `AZURE_CONTAINER_REGISTRY_NAME`

3. `GEMINI_API_KEY`

Packages