image_management_api/README.md

SEREACT - Secure Image Management API

SEREACT is a secure API for storing, organizing, and retrieving images with advanced search capabilities.

Features

• Secure image storage in Google Cloud Storage
• Team-based organization and access control
• API key authentication
• Semantic search using image embeddings
• Metadata extraction and storage
• Image processing capabilities
• Multi-team support

Architecture

sereact/
  ├── images/                    # Sample images for testing
  ├── sereact/                   # Main application code
  │   ├── deployment/            # Deployment configurations
  │   │   └── cloud-run/         # Google Cloud Run configuration
  │   ├── docs/                  # Documentation
  │   │   └── api/               # API documentation
  │   ├── scripts/               # Utility scripts
  │   ├── src/                   # Source code
  │   │   ├── api/               # API endpoints
  │   │   │   └── v1/            # API version 1
  │   │   ├── core/              # Core modules
  │   │   ├── db/                # Database models and repositories
  │   │   │   ├── models/        # Data models
  │   │   │   └── repositories/  # Database operations
  │   │   ├── schemas/           # API schemas (request/response)
  │   │   └── services/          # Business logic services
  │   └── tests/                 # Test code
  │       ├── api/               # API tests
  │       ├── db/                # Database tests
  │       └── services/          # Service tests
  ├── main.py                    # Application entry point
  ├── requirements.txt           # Python dependencies
  └── README.md                  # This file

Technology Stack

• FastAPI - Web framework
• Firestore - Database
• Google Cloud Storage - Image storage
• Pinecone - Vector database for semantic search
• CLIP - Image embedding model
• NumPy - Scientific computing
• Pydantic - Data validation

Setup and Installation

Prerequisites

• Python 3.8+
• Google Cloud account with Firestore and Storage enabled
• (Optional) Pinecone account for semantic search

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/sereact.git
   cd sereact
   

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate     # Windows
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Create a .env file with the following environment variables:

   # Firestore
   FIRESTORE_PROJECT_ID=your-gcp-project-id
   FIRESTORE_CREDENTIALS_FILE=path/to/firestore-credentials.json
   
   # Google Cloud Storage
   GCS_BUCKET_NAME=your-bucket-name
   GCS_CREDENTIALS_FILE=path/to/credentials.json
   
   # Security
   API_KEY_SECRET=your-secret-key
   
   # Vector database (optional)
   VECTOR_DB_API_KEY=your-pinecone-api-key
   VECTOR_DB_ENVIRONMENT=your-pinecone-environment
   VECTOR_DB_INDEX_NAME=image-embeddings
   

5. Run the application:

   uvicorn main:app --reload
   

6. Visit http://localhost:8000/docs in your browser to access the API documentation.

API Endpoints

The API provides the following main endpoints:

• /api/v1/auth/* - Authentication and API key management
• /api/v1/teams/* - Team management
• /api/v1/users/* - User management
• /api/v1/images/* - Image upload, download, and management
• /api/v1/search/* - Image search functionality

Refer to the Swagger UI documentation at /docs for detailed endpoint information.

Development

Running Tests

pytest

Creating a New API Version

1. Create a new package under src/api/ (e.g., v2)
2. Implement new endpoints
3. Update the main.py file to include the new routers

Deployment

Google Cloud Run

1. Build the Docker image:

   docker build -t gcr.io/your-project/sereact .
   

2. Push to Google Container Registry:

   docker push gcr.io/your-project/sereact
   

3. Deploy to Cloud Run:

   gcloud run deploy sereact --image gcr.io/your-project/sereact --platform managed
   

Local Development with Docker Compose

To run the application locally using Docker Compose:

1. Make sure you have Docker and Docker Compose installed
2. Run the following command in the project root:

docker compose up

This will:

• Build the API container based on the Dockerfile
• Mount your local codebase into the container for live reloading
• Mount your Firestore credentials for authentication
• Expose the API on http://localhost:8000

To stop the containers:

docker compose down

To rebuild containers after making changes to the Dockerfile or requirements:

docker compose up --build

Additional Information

License

This project is licensed under the MIT License - see the LICENSE file for details.