image_management_api/client/README.md

SeReact Frontend Client

A modern, responsive web frontend for the SeReact AI-powered image management platform. This is a pure frontend application that communicates directly with your SeReact backend API.

Features

• Pure Frontend: No backend dependencies - runs entirely in the browser
• Modern UI: Built with Bootstrap 5 and modern CSS features
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices
• Real-time Updates: Live connection status and automatic data refresh
• Keyboard Shortcuts: Power-user friendly navigation and actions
• Offline Awareness: Graceful handling of network connectivity issues

Core Functionality

• Configuration Management: Easy API endpoint and authentication setup
• Image Management: Upload, view, edit, and delete images with metadata
• AI-Powered Search: Semantic image search using natural language queries
• Team Management: Create and manage teams and user access
• User Management: Full user lifecycle with role-based permissions
• API Key Management: Generate and manage API keys for integrations

Quick Start

Prerequisites

• A running SeReact backend API server
• Modern web browser (Chrome, Firefox, Safari, Edge)
• Web server to serve static files (optional for development)

Installation

1. Download/Clone the frontend files:

   # If you have the full SeReact repository
   cd sereact/client
   
   # Or download just the client folder
   

2. Serve the files:

   Option A: Simple HTTP Server (Python)

   # Python 3
   python -m http.server 8080
   
   # Python 2
   python -m SimpleHTTPServer 8080
   

   Option B: Node.js HTTP Server

   npx http-server -p 8080
   

   Option C: Any web server

   • Copy files to your web server directory
   • Ensure index.html is accessible

3. Open in browser:

   http://localhost:8080
   

First-Time Setup

1. Configure API Connection:

   • Click "Configure Now" in the welcome dialog
   • Enter your SeReact API base URL (e.g., http://localhost:8000)
   • Enter your API key
   • Test the connection

2. Start Using:

   • Upload your first images
   • Try the AI-powered search
   • Manage teams and users

Configuration

API Settings

The frontend stores configuration in browser localStorage:

• API Base URL: The URL of your SeReact backend (e.g., http://localhost:8000)
• API Key: Your authentication key for the backend API

Environment Variables

For deployment, you can set default values by modifying js/config.js:

// Default configuration
this.apiBaseUrl = localStorage.getItem('apiBaseUrl') || 'https://your-api.example.com';
this.apiKey = localStorage.getItem('apiKey') || '';

File Structure

client/
├── index.html              # Main application entry point
├── styles.css              # Custom CSS styles
├── js/                     # JavaScript modules
│   ├── config.js          # Configuration management
│   ├── api.js             # API client and HTTP requests
│   ├── ui.js              # UI utilities and common functions
│   ├── images.js          # Image management functionality
│   ├── search.js          # AI search functionality
│   ├── teams.js           # Team management
│   ├── users.js           # User management
│   ├── apikeys.js         # API key management
│   └── app.js             # Main application initialization
└── README.md              # This file

Features in Detail

Image Management

• Upload: Drag & drop or click to upload images
• View: Full-size image viewing with details
• Edit: Update descriptions
• Delete: Remove images with confirmation

AI-Powered Search

• Natural Language: Search using descriptive text
• Similarity Threshold: Adjust search sensitivity
• Search History: Save and reuse frequent searches

Team & User Management

• Teams: Create and manage organizational teams
• Users: Add users with role-based permissions
• Admin Controls: Administrative functions for system management

API Key Management

• Generate Keys: Create API keys for integrations
• Security: One-time display of new keys
• Usage Tracking: Monitor key usage and activity

Keyboard Shortcuts

• Ctrl+K: Open search page and focus search input
• Ctrl+U: Upload new image
• Ctrl+,: Open configuration page
• 1-6: Navigate to different pages (Home, Images, Search, Teams, Users, API Keys)
• Esc: Close open modals

Browser Compatibility

• Chrome: 80+
• Firefox: 75+
• Safari: 13+
• Edge: 80+

Required Features

• ES6+ JavaScript support
• Fetch API
• CSS Grid and Flexbox
• Local Storage

Deployment

Static Hosting

The frontend can be deployed to any static hosting service:

• Netlify: Drag and drop the client folder
• Vercel: Connect your repository
• GitHub Pages: Push to a gh-pages branch
• AWS S3: Upload files to an S3 bucket with static hosting
• Azure Static Web Apps: Deploy via GitHub integration

Web Server Configuration

For proper routing with hash-based navigation, no special server configuration is needed. For history-based routing (if implemented), configure your server to serve index.html for all routes.

CORS Configuration

Ensure your SeReact backend API is configured to allow requests from your frontend domain:

# In your backend CORS configuration
ALLOWED_ORIGINS = [
    "http://localhost:8080",
    "https://your-frontend-domain.com"
]

Development

Local Development

1. Start a local server:

   python -m http.server 8080
   

2. Open browser with dev tools:

   http://localhost:8080
   

3. Make changes: Edit files and refresh browser

Debugging

• Open browser developer tools (F12)
• Check console for error messages
• Use Network tab to monitor API requests
• Application tab shows localStorage configuration

Adding Features

The modular structure makes it easy to add new features:

1. Create new JavaScript module in js/ folder
2. Add corresponding HTML section to index.html
3. Include script tag in index.html
4. Add navigation link if needed

Security Considerations

• API Keys: Stored in browser localStorage (consider security implications)
• HTTPS: Use HTTPS in production for secure communication
• CORS: Properly configure backend CORS settings
• Content Security Policy: Consider implementing CSP headers

Troubleshooting

Common Issues

1. Connection Errors:

   • Verify API base URL is correct
   • Check if backend server is running
   • Ensure CORS is properly configured

2. Authentication Errors:

   • Verify API key is valid and active
   • Check API key permissions
   • Ensure key hasn't expired

3. Image Upload Issues:

   • Check file size limits (default 10MB)
   • Verify file format is supported
   • Ensure sufficient backend storage

4. Search Not Working:

   • Verify images have been processed
   • Check vector database configuration
   • Try adjusting similarity threshold

Error Messages

• "API not configured": Set up API base URL and key in configuration
• "Connection failed": Check network and backend server status
• "Authentication failed": Verify API key is correct and active
• "File size exceeds limit": Choose a smaller image file

Support

For issues and questions:

1. Check the browser console for error messages
2. Verify backend API is running and accessible
3. Check network connectivity and CORS configuration
4. Review the SeReact backend documentation

License

This frontend client is part of the SeReact project. See the main project license for details.