Fuscorrespondence Deployment Guide

Overview

Fuscorrespondence is a full-stack application with:

Backend API: Node.js + Express + TypeScript deployed to AWS Lambda via Serverless Framework
Frontend Web App: React + TypeScript + Vite with static hosting deployment
Database: DynamoDB monotable integration (reuses existing infrastructure)
Authentication: JWT integration with existing fuscauth service

Current Deployment Status

✅ Backend (Production Ready)

Deployed URL: https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence
Environment: AWS Lambda + API Gateway
Database: DynamoDB fuscapp-monotable-dev
Status: Fully functional with all endpoints implemented

✅ Frontend (Development Complete)

Build System: Vite with TypeScript
Status: Ready for deployment to static hosting
Features: All pages implemented with responsive design and mobile animations

Prerequisites

Required Tools

Node.js: 18+ with npm
AWS CLI: Configured with appropriate permissions
Serverless Framework: npm install -g serverless
Git: For version control

Required AWS Permissions

Lambda: Create, update, and invoke functions
API Gateway: Create and manage REST APIs
DynamoDB: Read/write access to fuscapp-monotable-dev
CloudWatch: Logs access for monitoring
IAM: Role creation and management

Backend Deployment

Project Structure

api/
    ├── src/
    │   ├── controllers/         # Request handlers
    │   ├── routes/             # API route definitions
    │   ├── middlewares/        # Auth and error handling
    │   ├── services/           # Database operations
    │   ├── utils/              # Helper functions
    │   └── lambdaHandler.ts    # AWS Lambda entry point
    ├── serverless.yml          # Serverless Framework configuration
    ├── package.json
    └── tsconfig.json

1. Initial Setup

Navigate to API directory:

bash

cd fuscorrespondence/api

Install dependencies:

bash

npm install

2. Environment Configuration

Development Environment:

bash

# No additional .env file needed
    # Configuration is handled in serverless.yml

Production Environment:

bash

# Update serverless.yml for production stage
    # Modify DYNAMODB_TABLE and other environment variables as needed

3. Deploy Backend

Deploy to Development:

bash

# Deploy using Serverless Framework
    npm run deploy
    
    # Or directly with serverless
    serverless deploy

Deploy to Production:

bash

# Deploy to production stage
    serverless deploy --stage prod

4. Verify Backend Deployment

Test the API endpoints:

bash

# Health check (if implemented)
    curl https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence/health
    
    # Test with authentication (requires valid JWT)
    curl -H "Authorization: Bearer <jwt_token>" \
    https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence/mailbox

Frontend Deployment

Project Structure

web/
    ├── public/
    │   ├── index.html
    │   └── fuscorrespondence_logo_transparent.png
    ├── src/
    │   ├── components/         # UI components
    │   ├── pages/             # Route components
    │   ├── hooks/             # Custom React hooks
    │   ├── lib/               # API client and utilities
    │   ├── App.tsx            # Main application
    │   └── main.tsx           # Entry point
    ├── package.json
    ├── vite.config.ts         # Vite configuration
    ├── tailwind.config.ts     # Tailwind CSS configuration
    └── components.json        # shadcn/ui configuration

1. Initial Setup

Navigate to web directory:

bash

cd fuscorrespondence/web

Install dependencies:

bash

npm install

2. Environment Configuration

Create environment files for different stages:

Development (.env.development):

env

VITE_API_BASE_URL=https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence
    VITE_FUSCAUTH_URL=https://your-fuscauth-url.com

Production (.env.production):

env

VITE_API_BASE_URL=https://your-production-api-url.com/prod/fuscorrespondence
    VITE_FUSCAUTH_URL=https://your-production-fuscauth-url.com

3. Build for Production

Create optimized production build:

bash

npm run build

This generates a dist/ directory with optimized static assets.

4. Deployment Options

Option A: Netlify Deployment

bash

# Install Netlify CLI
    npm install -g netlify-cli
    
    # Deploy to Netlify
    netlify deploy
    
    # Deploy to production
    netlify deploy --prod

Option B: Vercel Deployment

bash

# Install Vercel CLI
    npm install -g vercel
    
    # Deploy to Vercel
    vercel
    
    # Deploy to production
    vercel --prod

Option C: AWS S3 + CloudFront

bash

# Build the project
    npm run build
    
    # Sync to S3 bucket
    aws s3 sync dist/ s3://your-bucket-name --delete
    
    # Invalidate CloudFront cache
    aws cloudfront create-invalidation --distribution-id YOUR_DISTRIBUTION_ID --paths "/*"

Option D: Manual Static Hosting

bash

# Build the project
    npm run build
    
    # Upload contents of dist/ directory to your web server
    # Ensure proper MIME types for .js, .css, .html files
    # Configure server for SPA routing (all routes should serve index.html)

Database Configuration

DynamoDB Table Structure

The application uses the existing monotable fuscapp-monotable-dev:

Entities:

Mailbox: PK = USER#{userId}, SK = MAILBOX#{mailboxId}
    Letter:  PK = LETTER#{letterId}, SK = LETTER#{letterId}

Indexes:

Primary Key: PK (partition key), SK (sort key)
No additional GSIs required for current functionality

Data Migration

If migrating from previous schema:

bash

# No migration script needed
    # New simplified schema is backward compatible
    # Old records will work with new status logic

Monitoring and Logging

Backend Monitoring

AWS CloudWatch Logs:

Lambda function logs: /aws/lambda/fuscorrespondence-dev-api
API Gateway logs: Configured in serverless.yml

Key Metrics to Monitor:

Lambda invocation count and duration
API Gateway 4xx/5xx error rates
DynamoDB read/write capacity utilization

Frontend Monitoring

Web Analytics:

Configure Google Analytics or similar service
Monitor page load times and user interactions
Track error rates and user flows

Error Tracking:

javascript

// Add to main.tsx for error tracking
    window.addEventListener("error", (event) => {
    console.error("Frontend error:", event.error)
    // Send to monitoring service
    })

Security Configuration

API Security

CORS: Configured for specific origins only
Authentication: JWT validation on all protected endpoints
Input Validation: Server-side validation for all user inputs
Rate Limiting: Consider implementing for production

Frontend Security

Content Security Policy: Configure CSP headers
HTTPS Only: Ensure all traffic uses HTTPS
Secure Token Storage: JWT tokens in localStorage (consider upgrading to httpOnly cookies)

Performance Optimization

Backend Optimization

Lambda Cold Starts: Optimized bundle size and initialization
DynamoDB: Efficient queries using monotable pattern
Caching: Consider adding Redis for frequently accessed data

Frontend Optimization

Code Splitting: Implemented with React Router lazy loading
Bundle Size: Optimized with Vite tree shaking
CDN: Use CDN for static assets in production
Image Optimization: Compress and optimize logo/icons

Troubleshooting

Common Backend Issues

Lambda Function Timeout:

bash

# Check CloudWatch logs
    aws logs tail /aws/lambda/fuscorrespondence-dev-api --follow
    
    # Increase timeout in serverless.yml if needed
    timeout: 30  # seconds

DynamoDB Access Denied:

bash

# Verify IAM role permissions
    aws iam get-role-policy --role-name fuscorrespondence-dev-us-east-1-lambdaRole --policy-name DynamoDBAccess

API Gateway CORS Issues:

bash

# Verify CORS configuration in serverless.yml
    cors:
    origin: https://your-frontend-domain.com
    headers:
    - Authorization
    - Content-Type

Common Frontend Issues

Build Errors:

bash

# Clear node_modules and reinstall
    rm -rf node_modules package-lock.json
    npm install
    
    # Check TypeScript errors
    npm run type-check

Runtime API Errors:

bash

# Check network tab in browser dev tools
    # Verify API_BASE_URL environment variable
    # Confirm CORS headers in API responses

Authentication Issues:

bash

# Check JWT token in localStorage
    console.log(localStorage.getItem('authToken'));
    
    # Verify token format and expiration
    # Test token with backend API directly

Rollback Procedures

Backend Rollback

bash

# List recent deployments
    serverless deploy list
    
    # Rollback to previous version
    serverless rollback --timestamp 2024-01-01T10:00:00.000Z

Frontend Rollback

bash

# Netlify
    netlify rollback
    
    # Vercel
    vercel rollback
    
    # AWS S3
    # Restore from S3 versioning or redeploy previous build

Environment-Specific Configuration

Development Environment

API URL: https://6nnj8no7u0.execute-api.us-east-1.amazonaws.com/dev/fuscorrespondence
Database: fuscapp-monotable-dev
Logging: Verbose logging enabled
CORS: Permissive for development

Production Environment

API URL: Update to production domain
Database: Consider separate production table
Logging: Error-level logging only
CORS: Restricted to production domain
Monitoring: Enhanced monitoring and alerting

Post-Deployment Checklist

Backend Verification

All API endpoints respond correctly
Authentication middleware works
Database read/write operations function
Error handling returns proper status codes
Logging is working in CloudWatch

Frontend Verification

All pages load correctly
Navigation works on desktop and mobile
API calls succeed with proper authentication
Mobile animations function smoothly
Error states display appropriately
Onboarding flow guides new users properly

Integration Testing

End-to-end user flow: signup → mailbox setup → compose → send → receive
Cross-browser compatibility testing
Mobile device testing on iOS and Android
Performance testing under load

Maintenance

Regular Tasks

Weekly: Monitor CloudWatch logs for errors
Monthly: Review API usage patterns and optimize
Quarterly: Update dependencies and security patches

Capacity Planning

Monitor DynamoDB read/write capacity
Track Lambda execution duration and memory usage
Plan for user growth and scaling needs

Last Updated: January 2025
Current Status: Production Ready
Backend Deployed: ✅ | Frontend Ready: ✅

Fuscorrespondence Deployment Guide

Fuscorrespondence Deployment Guide

Overview

Current Deployment Status

✅ Backend (Production Ready)

✅ Frontend (Development Complete)

Prerequisites

Required Tools

Required AWS Permissions

Backend Deployment

Project Structure

1. Initial Setup

2. Environment Configuration

3. Deploy Backend

4. Verify Backend Deployment

Frontend Deployment

Project Structure

1. Initial Setup

2. Environment Configuration

3. Build for Production

4. Deployment Options

Option A: Netlify Deployment

Option B: Vercel Deployment

Option C: AWS S3 + CloudFront

Option D: Manual Static Hosting

Database Configuration

DynamoDB Table Structure

Data Migration

Monitoring and Logging

Backend Monitoring

Frontend Monitoring

Security Configuration

API Security

Frontend Security

Performance Optimization

Backend Optimization

Frontend Optimization

Troubleshooting

Common Backend Issues

Common Frontend Issues

Rollback Procedures

Backend Rollback

Frontend Rollback

Environment-Specific Configuration

Development Environment

Production Environment

Post-Deployment Checklist

Backend Verification

Frontend Verification

Integration Testing

Maintenance

Regular Tasks

Capacity Planning

fuscorrespondence Docs