JUSSAA Captioner Tool

A specialized image captioning and resizing tool designed for The Junior & Senior School Alumni Association (JUSSAA) social media team.

Overview

The JUSSAA Captioner Tool is a web-based application that helps social media interns quickly generate engaging captions for photos and resize images to optimal social media dimensions (4:5 aspect ratio). Built with React frontend and Express.js backend, it leverages OpenAI's vision capabilities for intelligent caption generation.

Features

• 🖼️ Smart Image Upload: Drag & drop or click to upload images (PNG, JPG, GIF, WebP)
• 🤖 AI-Powered Captions: Generate contextual captions using OpenAI's vision model
• 📐 Automatic Resizing: Convert images to 4:5 aspect ratio optimized for social media
• 🎨 JUSSAA Branding: Custom branded interface with school colors and logo
• 📱 Responsive Design: Works seamlessly on desktop and mobile devices
• ⚡ Real-time Processing: Instant feedback and processing status updates

Quick Start

1. Start the application

   npm start

2. Open your browser Navigate to http://localhost:3000

3. Upload an image

   • Drag and drop a photo onto the upload area, or
   • Click to browse and select an image file

4. Generate caption

   • Click "Generate Caption" to create an AI-powered description
   • The caption will appear in the text area

5. Download resized image

   • Click "Download Resized (4x5)" to get the social media optimized version
   • Image is automatically converted to 4:5 aspect ratio

Project Structure

jussaa-captionator/
├── package.json              # Main application dependencies
├── .env                     # Environment configuration (OpenAI API key)
├── README.md               # This documentation
├── assets/
│   └── jussaa_logo.jpg     # JUSSAA school logo
├── src/
│   ├── captioner-app.js    # Express server and API routes
│   ├── routes/
│   │   └── captioner-api.js # API endpoints for upload/caption/resize
│   ├── services/
│   │   ├── caption-service.js  # OpenAI integration for captions
│   │   └── image-service.js    # Image processing and resizing
│   └── utils/
│       └── logger.js       # Application logging
├── client/                 # React frontend application
│   ├── package.json       # Frontend dependencies
│   ├── public/
│   │   └── jussaa_logo.jpg # Logo for web interface
│   └── src/
│       ├── App.js         # Main React component
│       ├── components/
│       │   ├── CaptionerTab.js  # Main upload/caption interface
│       │   └── RefineTab.js     # Caption customization (future)
│       └── api/
│           └── captioner.js     # API client for backend
├── uploads/               # Temporary uploaded images
├── build/                # Built React app (served by Express)
└── logs/                 # Application logs

Installation & Setup

Prerequisites

• Node.js (v14 or higher)
• OpenAI API key

Installation Steps

1. Clone or download the project

   git clone <repository-url>
   cd jussaa-captionator

2. Install dependencies

   npm install
   cd client && npm install && cd ..

3. Configure environment variables Create a .env file in the root directory:

   OPENAI_API_KEY=your_openai_api_key_here
   NODE_ENV=production
   PORT=3000

4. Build the React frontend

   npm run build

5. Start the application

   npm start

6. Access the web interface Open http://localhost:3000 in your browser

Usage Instructions

For Social Media Interns

1. Navigate to the Captioner Tool

   • Open http://localhost:3000 in your web browser
   • You'll see the JUSSAA-branded interface with the greeting message

2. Upload Your Photo

   • Method 1: Drag your image file directly onto the upload area
   • Method 2: Click the upload area and select your image file
   • Supported formats: PNG, JPG, GIF, WebP (max 10MB)

3. Generate Caption

   • After upload, click the green "Generate Caption" button
   • Wait for the AI to analyze your image and create a caption
   • The caption will appear in the text box below

4. Download Resized Image

   • Click "Download Resized (4x5)" to get the optimized image
   • The image is automatically resized to 4:5 aspect ratio
   • Perfect for Instagram posts and stories

5. Start Over

   • Click "Start Over" at any time to upload a new image
   • This clears all current data and resets the interface

Tips for Best Results

• Use clear, well-lit photos for better AI caption generation
• Include people and activities - the AI works best with scenes containing school events, alumni gatherings, and people
• Check and edit captions - Always review the generated caption and modify as needed
• Keep original files - The tool doesn't modify your original images

API Endpoints

The application provides REST API endpoints:

• POST /api/captioner/upload - Upload image file
• POST /api/captioner/caption - Generate caption for uploaded image
• POST /api/captioner/resize - Resize image to 4:5 aspect ratio
• GET /api/captioner/download/:filename - Download processed image
• GET /health - Application health check

Development

Frontend Development

cd client
npm start  # Starts React dev server on port 3001

Backend Development

npm run dev  # Starts Express server with debug logging

Building for Production

npm run build  # Builds React app and copies to build/

Project Scripts

• npm start - Start production server
• npm run dev - Start development server
• npm run build - Build React frontend
• npm run build:client - Build client only
• npm run dev:client - Start client development server

Configuration

Environment Variables

# Required
OPENAI_API_KEY=sk-...    # Your OpenAI API key

# Optional
NODE_ENV=production      # Environment mode
PORT=3000               # Server port
LOG_LEVEL=info          # Logging level

Image Processing Settings

• Upload limit: 10MB per file
• Output format: JPEG for resized images
• Resize dimensions: 4:5 aspect ratio (optimized for social media)
• Quality: 90% JPEG quality for good balance of size/quality

Troubleshooting

Common Issues

1. "Image upload failed"

   • Check file size (must be under 10MB)
   • Ensure file is a valid image format
   • Check server logs for detailed error

2. "Caption generation failed"

   • Verify OpenAI API key is set correctly in .env
   • Check your OpenAI account has available credits
   • Review server logs for API errors

3. "Download failed"

   • Ensure image was successfully uploaded first
   • Check server disk space and permissions
   • Verify uploads/ directory exists and is writable

4. Old version showing after changes

   • Run npm run build to rebuild the frontend
   • Restart the server with npm start
   • Clear browser cache or hard refresh (Ctrl+Shift+R)

Health Monitoring

• Visit http://localhost:3000/health to check application status
• Check logs in the logs/ directory for detailed information

System Requirements

• Memory: 512MB RAM minimum
• Storage: 1GB free space for images and logs
• Network: Internet connection for OpenAI API calls
• Browser: Modern browser with JavaScript enabled

Security Notes

• API keys are stored in environment variables, never in code
• Uploaded images are temporarily stored and can be cleaned up regularly
• No user authentication required for internal use
• Consider network security if deploying on shared networks

Support

For technical issues:

1. Check the troubleshooting section above
2. Review application logs in logs/ directory
3. Verify environment configuration
4. Contact the development team with specific error messages

---

Built for The Junior & Senior School Alumni Association
Making social media management easier for our community