image_management_api/client/README.md

# SEREACT Web Client

A comprehensive web interface for the SEREACT API, providing full CRUD operations for teams, users, images, and API keys, along with AI-powered image search capabilities.

## Features

- **Configuration Management**: Set API endpoint and authentication
- **Bootstrap Setup**: Initial system setup with team and admin user creation
- **Teams Management**: Create, view, edit, and delete teams
- **Users Management**: Create, view, edit, and delete users with role management
- **API Keys Management**: Create and manage API keys for authentication
- **Image Management**: Upload, view, edit, and delete images with metadata
- **AI-Powered Search**: Semantic image search using natural language queries
- **Responsive Design**: Modern Bootstrap-based UI that works on all devices

## Prerequisites

- Python 3.8+
- Running SEREACT API server
- Network access to the SEREACT API

## Installation

1. Navigate to the client directory:
   ```bash
   cd client
   ```

2. Create and activate a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate     # Windows
   ```

3. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Running the Client

1. Start the Flask development server:
   ```bash
   python app.py
   ```

2. Open your browser and navigate to:
   ```
   http://localhost:5000
   ```

## Initial Setup

### First Time Configuration

1. **Configure API Connection**:
   - Go to the "Config" page
   - Set your SEREACT API base URL (e.g., `http://localhost:8000`)
   - If you have an API key, enter it here

2. **Bootstrap the System** (if this is a new SEREACT installation):
   - Go to the "Bootstrap" page
   - Enter your organization details
   - Create the initial admin user
   - The system will generate an API key automatically

3. **Start Using the System**:
   - Upload images
   - Search for images using AI
   - Manage teams and users
   - Create additional API keys

## Usage Guide

### Teams Management
- **View Teams**: See all teams in your organization
- **Create Team**: Add new teams with descriptions
- **Edit Team**: Update team information
- **Delete Team**: Remove teams (admin only)

### Users Management
- **View Users**: See all users in your team/organization
- **Create User**: Add new users and assign them to teams
- **Edit User**: Update user information and admin status
- **Delete User**: Remove users from the system

### API Keys Management
- **View API Keys**: See all your API keys and their status
- **Create API Key**: Generate new API keys for applications
- **Revoke API Key**: Disable API keys that are no longer needed

### Image Management
- **Upload Images**: Add new images with descriptions and tags
- **Browse Images**: View all uploaded images with filtering
- **View Image Details**: See full image information and metadata
- **Edit Images**: Update descriptions and tags
- **Delete Images**: Remove images from storage

### AI-Powered Search
- **Semantic Search**: Use natural language to find images
- **Advanced Options**: Adjust similarity thresholds and result limits
- **Filter Results**: Combine search with tag filtering
- **Similarity Scores**: See how closely images match your query

## Configuration

### Environment Variables

You can set these environment variables to configure default values:

```bash
export SEREACT_API_URL=http://localhost:8000
export SEREACT_API_KEY=your-api-key
```

### Session Storage

The client stores configuration in the browser session:
- API base URL
- API key
- These are not persistent and need to be re-entered after browser restart

## API Integration

The client integrates with the following SEREACT API endpoints:

- `/api/v1/auth/*` - Authentication and API key management
- `/api/v1/teams/*` - Team management
- `/api/v1/users/*` - User management
- `/api/v1/images/*` - Image upload and management
- `/api/v1/search/*` - AI-powered image search

## Security Notes

- **API Keys**: Store API keys securely and never share them
- **HTTPS**: Use HTTPS in production for secure communication
- **Access Control**: The client respects the API's team-based access control
- **Session Security**: Configure secure session cookies in production

## Troubleshooting

### Common Issues

1. **Connection Errors**:
   - Verify the API base URL is correct
   - Ensure the SEREACT API server is running
   - Check network connectivity

2. **Authentication Errors**:
   - Verify your API key is valid and active
   - Check if the API key has expired
   - Ensure you have the necessary permissions

3. **Image Upload Issues**:
   - Check file size (max 10MB)
   - Verify file format is supported
   - Ensure sufficient storage space

4. **Search Not Working**:
   - Verify images have been processed (have embeddings)
   - Check if the vector database is configured
   - Try adjusting similarity thresholds

### Error Messages

- **"API key not set"**: Configure your API key in the Config page
- **"Request failed"**: Check API server status and network connection
- **"Invalid JSON response"**: API server may be returning errors
- **"File size exceeds limit"**: Choose a smaller image file

## Development

### Project Structure

```
client/
├── app.py                 # Main Flask application
├── requirements.txt       # Python dependencies
├── templates/            # HTML templates
│   ├── base.html         # Base template with navigation
│   ├── index.html        # Home page
│   ├── config.html       # Configuration page
│   ├── bootstrap.html    # Bootstrap setup page
│   ├── teams.html        # Teams listing
│   ├── team_form.html    # Team create/edit form
│   ├── users.html        # Users listing
│   ├── user_form.html    # User create/edit form
│   ├── api_keys.html     # API keys listing
│   ├── api_key_form.html # API key creation form
│   ├── images.html       # Images listing with pagination
│   ├── image_upload.html # Image upload form
│   ├── image_detail.html # Image detail view
│   ├── image_edit.html   # Image edit form
│   └── search.html       # AI search interface
└── uploads/              # Temporary upload directory
```

### Customization

- **Styling**: Modify the CSS in `templates/base.html`
- **Features**: Add new routes and templates in `app.py`
- **API Integration**: Extend the `make_api_request` function
- **UI Components**: Use Bootstrap classes for consistent styling

## License

This web client is part of the SEREACT project and follows the same license terms.