Web demo

.dockerignore

@@ -0,0 +1,66 @@
+# Dependencies
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# Testing
+coverage
+.nyc_output
+tests/tmp
+
+# Next.js
+.next/
+out/
+
+# Production build
+dist
+build
+
+# Environment variables
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+# Vercel
+.vercel
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Documentation
+README.md
+docs/
+*.md
+!CLAUDE.md
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+*.log
+
+# E2E test artifacts
+__fs_snapshots__/
+tmp/test-e2e-*
+
+# Development only files
+.eslintrc*
+prettier.config.*
+jest.config.*
+tailwind.config.*
+tsconfig*.json

DEPLOYMENT.md

@@ -0,0 +1,110 @@
+# Presentation Demo - Deployment Guide
+
+## Railway Deployment
+
+### Prerequisites
+
+- Railway account (railway.app)
+- GitHub repository connected to Railway
+
+### Deployment Steps
+
+1. **Connect Repository**
+
+   ```bash
+   # Install Railway CLI (optional)
+   npm install -g @railway/cli
+   railway login
+   ```
+
+2. **Create New Project**
+   - Go to railway.app
+   - Click "New Project"
+   - Choose "Deploy from GitHub repo"
+   - Select your repository
+
+3. **Configure Environment**
+   Railway will automatically:
+   - Detect the Dockerfile
+   - Build with system dependencies (pandoc, chromium)
+   - Install Mermaid CLI
+   - Expose port 3000
+
+4. **Custom Domain (Optional)**
+   - Go to project settings
+   - Add custom domain
+   - Update Postman environment variable
+
+### Environment Variables
+
+No additional environment variables required for basic functionality.
+
+Optional configurations:
+
+- `NODE_ENV=production` (auto-set by Railway)
+- `PORT=3000` (auto-set by Railway)
+
+### Build Process
+
+The Dockerfile handles:
+
+- Installing pandoc for document conversion
+- Installing Chromium for Mermaid diagram generation
+- Installing Mermaid CLI globally
+- Building Next.js application
+- Setting up proper permissions
+
+### Monitoring
+
+- Railway provides automatic logs
+- Health check endpoint: `/api/presentations/templates`
+- Monitor build logs for any dependency issues
+
+### Troubleshooting
+
+**Build Failures:**
+
+- Check Dockerfile syntax
+- Verify all dependencies are available in Alpine Linux
+- Check build logs for specific error messages
+
+**Runtime Issues:**
+
+- Verify Mermaid CLI can access Chromium
+- Check file permissions for temp directory
+- Monitor memory usage (Railway has limits per plan)
+
+**API Issues:**
+
+- Test endpoints with Postman collection
+- Check server logs in Railway dashboard
+- Verify all presentation templates are accessible
+
+### Local Testing
+
+Before deploying, test the Docker build locally:
+
+```bash
+# Build the image
+docker build -t presentation-demo .
+
+# Run locally
+docker run -p 3000:3000 presentation-demo
+
+# Test endpoints
+curl http://localhost:3000/api/presentations/templates
+```
+
+### Performance Considerations
+
+- PPTX generation can take 30-60 seconds
+- Mermaid diagram rendering requires Chromium (memory intensive)
+- Consider Railway Pro plan for production use
+- File cleanup happens automatically (temp directory is ephemeral)
+
+### Security
+
+- Application runs as non-root user
+- Temp files are isolated per container
+- No persistent storage of user data
+- All generated files are cleaned up on container restart

Dockerfile

@@ -0,0 +1,71 @@
+# Multi-stage build for markdown-workflow presentation demo
+FROM node:20-alpine AS base
+
+# Install system dependencies
+RUN apk add --no-cache \
+    # Pandoc for document conversion
+    pandoc \
+    # Chromium and dependencies for Mermaid CLI
+    chromium \
+    nss \
+    freetype \
+    freetype-dev \
+    harfbuzz \
+    ca-certificates \
+    ttf-freefont \
+    # Additional fonts for better PDF/PPTX output
+    font-noto \
+    font-noto-cjk \
+    # Git for potential version control features
+    git \
+    # Build tools
+    make \
+    g++
+
+# Configure Puppeteer to use installed Chromium
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+ENV PUPPETEER_ARGS="--no-sandbox --disable-setuid-sandbox --disable-dev-shm-usage --disable-gpu"
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+COPY pnpm-lock.yaml ./
+
+# Install pnpm
+RUN npm install -g pnpm
+
+# Install Mermaid CLI globally (before app dependencies to leverage caching)
+RUN npm install -g @mermaid-js/mermaid-cli
+
+# Install app dependencies
+RUN pnpm install --frozen-lockfile
+
+# Copy source code
+COPY . .
+
+# Build the Next.js application
+RUN pnpm run build
+
+# Create non-root user for security
+RUN addgroup -g 1001 -S nodejs
+RUN adduser -S nextjs -u 1001
+
+# Create temp directory for presentations with proper permissions
+RUN mkdir -p /app/tmp/presentation-demo && \
+    chown -R nextjs:nodejs /app/tmp
+
+# Switch to non-root user
+USER nextjs
+
+# Expose port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+  CMD curl -f http://localhost:3000/api/presentations/templates || exit 1
+
+# Start the application
+CMD ["pnpm", "start"]

docs/postman/README.md

@@ -0,0 +1,128 @@
+# Presentation API - Postman Collection
+
+This Postman collection provides comprehensive testing for the Presentation API endpoints.
+
+## Setup
+
+1. **Import Collection**: Import `presentation-demo.json` into Postman
+2. **Set Environment**: Create environment with the following variables:
+   - `baseUrl`: `http://localhost:3000` (for local development)
+   - `collectionId`: Leave empty (auto-populated by tests)
+
+## API Endpoints
+
+### 1. GET /api/presentations/templates
+
+**Purpose**: Retrieve available presentation templates  
+**Tests**: Validates response structure and template properties
+
+### 2. POST /api/presentations/create
+
+**Purpose**: Create a new presentation collection  
+**Body**:
+
+```json
+{
+  "title": "API Test Presentation",
+  "templateName": "default"
+}
+```
+
+**Tests**: Validates collection creation and auto-captures `collectionId`
+
+### 3. POST /api/presentations/format
+
+**Purpose**: Format presentation to PPTX with custom content  
+**Body**:
+
+```json
+{
+  "collectionId": "{{collectionId}}",
+  "content": "# Custom markdown content...",
+  "mermaidOptions": {
+    "theme": "default",
+    "output_format": "png",
+    "timeout": 30
+  }
+}
+```
+
+**Tests**: Validates formatting success and download URL
+
+### 4. GET /api/presentations/download/{id}
+
+**Purpose**: Download the generated PPTX file  
+**Tests**: Validates file download headers and content type
+
+## Running Tests
+
+### Individual Requests
+
+Run requests in sequence (1 → 2 → 3 → 4) for full workflow testing.
+
+### Collection Runner
+
+1. Click "Run Collection"
+2. Select all requests
+3. Run with 1-2 second delay between requests
+4. All tests should pass for successful API functionality
+
+## Environment Variables
+
+### Local Development
+
+```
+baseUrl: http://localhost:3000
+collectionId: (auto-populated)
+```
+
+### Production (Railway)
+
+```
+baseUrl: https://your-app.railway.app
+collectionId: (auto-populated)
+```
+
+## Expected Results
+
+- **Templates**: Should return at least `default` and `beginner` templates
+- **Create**: Returns collection ID like `api_test_presentation_20250801`
+- **Format**: Processing time varies (30s-2min depending on diagrams)
+- **Download**: PPTX file typically 50KB-500KB depending on content
+
+## Troubleshooting
+
+### Common Issues
+
+**404 on templates**: Check that presentation workflow exists in `workflows/presentation/`
+
+**500 on create**: Verify WorkflowEngine can write to temp directory
+
+**Timeout on format**: Mermaid CLI or pandoc may not be installed
+
+**404 on download**: File may not have been generated successfully
+
+### Debug Tips
+
+1. Check server logs for detailed error messages
+2. Verify temp directory has proper write permissions
+3. Test individual components (Mermaid CLI, pandoc) separately
+4. Use environment variables to switch between local/production testing
+
+## Test Data
+
+The collection includes realistic test data:
+
+- Professional presentation title
+- Custom markdown content with Mermaid diagrams
+- Standard Mermaid configuration options
+- Proper MIME types and headers
+
+## Integration Testing
+
+This collection can be used for:
+
+- **Development**: Quick API validation during development
+- **CI/CD**: Automated testing in deployment pipelines
+- **Documentation**: Living API examples and expected responses
+- **Debugging**: Isolate backend issues from frontend problems