Initial commit

docs/UI Deployment Guide.md

@@ -0,0 +1,268 @@
+# Deployment Guide
+
+This document provides instructions for deploying the Tax Agent Platform UI in various environments.
+
+## Prerequisites
+
+- Docker and Docker Compose
+- Node.js 20+ (for local development)
+- Access to the backend API services
+- Traefik reverse proxy with Authentik authentication (for production)
+
+## Environment Variables
+
+Create a `.env` file based on `.env.example`:
+
+```bash
+# API Configuration
+NEXT_PUBLIC_API_BASE_URL=https://api.tax-agent.local
+NEXT_PUBLIC_APP_ENV=production
+
+# Application Configuration
+NEXT_PUBLIC_APP_BASE=https://ui.tax-agent.local
+```
+
+## Docker Deployment
+
+### 1. Build the Docker Image
+
+```bash
+docker build -t tax-agent-ui:latest .
+```
+
+### 2. Run with Docker Compose
+
+```bash
+docker-compose up -d
+```
+
+### 3. Verify Deployment
+
+```bash
+# Check container status
+docker-compose ps
+
+# Check logs
+docker-compose logs -f ui-review
+
+# Test health endpoint
+curl http://localhost:3000/api/health
+```
+
+## Production Deployment
+
+### 1. Traefik Configuration
+
+Ensure your Traefik configuration includes:
+
+```yaml
+# traefik.yml
+http:
+  middlewares:
+    auth:
+      forwardAuth:
+        address: "http://authentik:9000/outpost.goauthentik.io/auth/traefik"
+        trustForwardHeader: true
+        authResponseHeaders:
+          - X-Authenticated-User
+          - X-Authenticated-Email
+          - X-Authenticated-Groups
+```
+
+### 2. Docker Compose for Production
+
+```yaml
+version: '3.8'
+
+services:
+  ui-review:
+    image: tax-agent-ui:latest
+    environment:
+      - NODE_ENV=production
+      - NEXT_PUBLIC_API_BASE_URL=https://api.tax-agent.local
+      - NEXT_PUBLIC_APP_ENV=production
+    labels:
+      - "traefik.enable=true"
+      - "traefik.http.routers.ui-review.rule=Host(`ui.tax-agent.local`)"
+      - "traefik.http.routers.ui-review.entrypoints=websecure"
+      - "traefik.http.routers.ui-review.tls=true"
+      - "traefik.http.routers.ui-review.middlewares=auth@file"
+    networks:
+      - tax-agent-network
+    restart: unless-stopped
+
+networks:
+  tax-agent-network:
+    external: true
+```
+
+### 3. SSL/TLS Configuration
+
+Ensure SSL certificates are properly configured in Traefik for HTTPS access.
+
+## Local Development
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Set Environment Variables
+
+```bash
+cp .env.example .env.local
+# Edit .env.local with your local API endpoints
+```
+
+### 3. Run Development Server
+
+```bash
+npm run dev
+```
+
+### 4. Run Tests
+
+```bash
+# Unit tests
+npm run test
+
+# E2E tests
+npm run test:e2e
+
+# Accessibility tests
+npm run test:a11y
+```
+
+## Monitoring and Logging
+
+### Health Checks
+
+The application provides a health check endpoint at `/api/health`:
+
+```json
+{
+  "status": "healthy",
+  "timestamp": "2024-01-10T15:30:00.000Z",
+  "version": "1.0.0",
+  "environment": "production"
+}
+```
+
+### Logging
+
+Application logs are written to stdout and can be collected by Docker:
+
+```bash
+# View logs
+docker-compose logs -f ui-review
+
+# Export logs
+docker-compose logs ui-review > app.log
+```
+
+### Performance Monitoring
+
+The application includes:
+- Web Vitals reporting
+- OpenTelemetry integration (when configured)
+- Sentry error tracking (when configured)
+
+## Security Considerations
+
+### Authentication
+
+- All routes require authentication via Traefik/Authentik
+- No in-app authentication flows
+- User claims are forwarded via headers
+
+### Content Security Policy
+
+The application includes security headers:
+- X-Frame-Options: DENY
+- X-Content-Type-Options: nosniff
+- Referrer-Policy: strict-origin-when-cross-origin
+
+### HTTPS
+
+- Always use HTTPS in production
+- Configure proper SSL certificates
+- Enable HSTS headers in Traefik
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Authentication not working**
+   - Check Traefik middleware configuration
+   - Verify Authentik is running and accessible
+   - Check forwarded headers in browser dev tools
+
+2. **API calls failing**
+   - Verify NEXT_PUBLIC_API_BASE_URL is correct
+   - Check network connectivity to backend services
+   - Review CORS configuration
+
+3. **Build failures**
+   - Ensure Node.js version is 20+
+   - Clear npm cache: `npm cache clean --force`
+   - Delete node_modules and reinstall
+
+### Debug Mode
+
+Enable debug logging:
+
+```bash
+# Set environment variable
+DEBUG=* npm run dev
+
+# Or in Docker
+docker-compose -f docker-compose.debug.yml up
+```
+
+### Performance Issues
+
+1. Check bundle size: `npm run analyze`
+2. Review Lighthouse reports: `npm run lighthouse`
+3. Monitor Web Vitals in production
+
+## Backup and Recovery
+
+### Configuration Backup
+
+Backup these files:
+- `.env` (production environment variables)
+- `docker-compose.yml`
+- Traefik configuration files
+
+### Data Recovery
+
+The UI is stateless - all data is stored in backend services. No specific backup procedures required for the UI itself.
+
+## Updates and Maintenance
+
+### Updating the Application
+
+1. Pull latest code
+2. Build new Docker image
+3. Update docker-compose.yml if needed
+4. Deploy with zero downtime:
+
+```bash
+docker-compose pull
+docker-compose up -d --no-deps ui-review
+```
+
+### Security Updates
+
+- Regularly update Node.js base image
+- Update npm dependencies: `npm audit fix`
+- Monitor security advisories
+
+## Support
+
+For deployment issues:
+1. Check application logs
+2. Verify environment configuration
+3. Test health endpoints
+4. Review Traefik/Authentik logs if authentication issues