image_management_api/client/README.md

# Contoso Frontend Client

A modern, responsive web frontend for the Contoso AI-powered image management platform. This is a pure frontend application that communicates directly with your Contoso 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 Contoso 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**:
   ```bash
   # If you have the full Contoso repository
   cd contoso/client
   
   # Or download just the client folder
   ```

2. **Serve the files**:
   
   **Option A: Simple HTTP Server (Python)**
   ```bash
   # Python 3
   python -m http.server 8080
   
   # Python 2
   python -m SimpleHTTPServer 8080
   ```
   
   **Option B: Node.js HTTP Server**
   ```bash
   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 Contoso 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 Contoso 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`:

```javascript
// 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 Contoso backend API is configured to allow requests from your frontend domain:

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

## Development

### Local Development

1. **Start a local server**:
   ```bash
   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 Contoso backend documentation

## License

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